# `frontend/shared/`

**Status:** Scaffold — code not migrated yet  
**Phase:** Migration Phase 1 (shared architecture creation)

## Purpose

Central **platform layer** for cross-module UI, utilities, and infrastructure. All business modules (Accounting, Beauty, Healthcare, future CRM/Delivery) consume code from here — never the reverse.

## Relationship to legacy paths

Existing shared code remains in place until incremental migration (Phase 2+):

| Shared area | Legacy location today | Target |
|-------------|----------------------|--------|
| UI primitives | `components/ds/`, `components/ui/` | `shared/ui/`, `shared/design-system/` |
| Forms | `components/ds/FormControls.tsx` | `shared/forms/` |
| Layouts | Portal shells in `components/{module}/` | `shared/layouts/` |
| Tables | `components/ds/Page.tsx` (`DataTable`) | `shared/tables/` |
| Charts | (not implemented; `recharts` installed) | `shared/charts/` |
| Calendar | `components/ds/DatePicker.tsx` | `shared/calendar/` |
| Hooks | `hooks/` | `shared/hooks/` |
| Utils | `lib/utils.ts` | `shared/utils/` |
| API core | `lib/auth.ts`, fetch patterns in `lib/*-api.ts` | `shared/api/` |
| Theme | `lib/theme.ts`, `styles/globals.css` | `shared/theme/` |
| Providers | `components/providers/`, `ThemeProvider.tsx` | `shared/providers/` |
| Icons | `lucide-react` direct imports | `shared/icons/` |
| Types | scattered | `shared/types/` |
| Constants | `lib/apps-catalog.ts`, env | `shared/constants/` |
| Design system | `components/ds/` | `shared/design-system/` |

## Subdirectories

| Directory | Documentation |
|-----------|---------------|
| [ui/](./ui/README.md) | Low-level UI atoms |
| [forms/](./forms/README.md) | Form primitives and RHF helpers |
| [layouts/](./layouts/README.md) | Shells, portal chrome, page scaffolding |
| [tables/](./tables/README.md) | Data tables and toolbars |
| [charts/](./charts/README.md) | Chart wrappers |
| [calendar/](./calendar/README.md) | Jalali/Gregorian date pickers |
| [hooks/](./hooks/README.md) | Cross-module React hooks |
| [utils/](./utils/README.md) | Pure utilities |
| [api/](./api/README.md) | Shared fetch client and auth |
| [theme/](./theme/README.md) | White-label theming |
| [providers/](./providers/README.md) | React context providers |
| [icons/](./icons/README.md) | Icon re-exports and mappings |
| [types/](./types/README.md) | Shared TypeScript types |
| [constants/](./constants/README.md) | App-wide constants |
| [design-system/](./design-system/README.md) | Tokens, patterns, composition rules |

## Import rules

```
app/ and modules/  →  shared/*  ✅
shared/*           →  modules/*  ❌
shared/*           →  components/{accounting,beauty,healthcare}/*  ❌
```

Phase 1 does **not** change existing `@/components/ds` imports. New code may optionally use `@/shared/*` once migration begins.

## Path alias (optional, Phase 1)

```json
"@/shared/*": ["./shared/*"]
```

Configured in `tsconfig.json` for future use; legacy `@/*` imports remain valid.