wealth/.claude/skills/front-end-architect/references/project-structure.md

343 lines
18 KiB
Markdown

# Project structure
`<placeholders>` are names you choose. `@project` stands for the workspace's npm scope.
Contents: Top level · App · Platform · Feature anatomy · Shared · island · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking
## Top level
```
apps/ # deployable apps
platforms/ # each app's logic, one project per app
packages/
├── island/ # design system (atomic design)
├── libs/ # framework-agnostic libraries, e.g. http and env
├── integrations/ # third-party integrations
└── tools/ # shared runtime tools
tools/ # workspace scripts for AI, Nx, and the repo, e.g. a doc validator
```
Three folders are named `tools`. Keep them apart:
- Root `tools/`: scripts that run in a terminal, in CI, or through Nx (generators, validators). App code never imports them. TypeScript scripts run with jiti.
- `packages/tools/`: shared runtime tools that apps and projects import.
- `packages/island/src/tools/`: design-system tools such as `cn`, `icon-sprite-plugin`, and `icon-name-extraction`.
## App (Next.js)
```
apps/<app>/src/
├── bootstrap/
│ ├── bootstrap.client.ts # runs before client components render (SSR and browser)
│ ├── bootstrap.server.ts # runs once on the server before rendering
│ └── index.ts
├── i18n/
│ ├── i18n.ts
│ └── index.ts
├── instrumentation.ts # configures the error handler on the server; onRequestError reports
├── app/ # Next.js App Router
│ ├── global-error.tsx # EB-W: replaces the root layout; own <html> and <body>
│ ├── not-found.tsx
│ └── (auth)/
│ ├── layout.tsx
│ ├── loading.tsx
│ ├── error.tsx # page-size EB-S for the group
│ └── auth/
│ └── login/
│ ├── page.tsx
│ ├── organisms/ # optional: organisms only this route uses
│ └── templates/ # optional: this route's mobile and desktop templates
├── styles/
│ ├── app.css # Tailwind entry; imports island.css
│ ├── fonts.ts # next/font/local faces from island fonts/, set as CSS variables on <html>
│ └── index.ts
├── configs/
│ ├── seo.ts
│ ├── react-query.ts
│ └── index.ts
├── constants/
│ ├── auth.ts # e.g. the OTP re-send timeout
│ └── index.ts
└── env/ # the only code that reads process.env (see lib-env.md)
├── env.client.ts # public variables: createClientEnv
├── env.server.ts # server variables: createServerEnv; import 'server-only'
├── index.ts # clientEnv
└── server.ts # serverEnv; import 'server-only'
```
- Pages are thin entrypoints. A page picks the mobile or the desktop template on the server, so no component branches on viewport size.
- Every route level may keep its own `organisms/` and `templates/`, shaped like island organisms. They are not routable because they contain no `page.tsx`.
- `styles/`, `configs/`, and `constants/` grow as needed; each keeps an `index.ts`.
- The app holds no features, stores, or business logic; those live in `platforms/<app>/`.
## Platform
```
platforms/<app>/src/
├── app/
│ ├── app-shell/ # top-level provider shell shared by the mobile and desktop views
│ │ ├── AppShell.tsx
│ │ ├── types.ts
│ │ └── index.ts
│ ├── guards/ # e.g. the route authentication guard
│ │ └── <guard-name>/
│ │ ├── <guard-name>.ts or <GuardName>.tsx
│ │ └── index.ts
│ ├── error-boundaries/ # see error-handling.md
│ │ ├── part-boundary/ # PartBoundary: catchError around a part
│ │ ├── error-fallback/ # ErrorFallback: what every boundary renders
│ │ ├── status-empty-state/ # the not-found and no-access empty states
│ │ └── read-on-server/ # readOnServer; server-only, exported through server.ts
│ └── navigation/
│ ├── navigation.ts # typed route paths and navigation menus
│ ├── constants.ts
│ ├── types.ts
│ ├── hooks/
│ │ └── use-<hook-name>.ts
│ ├── components/ # navigation UI, shaped like organisms
│ └── index.ts
├── features/ # DDD, see Feature anatomy
├── stores/ # one store per feature or domain
├── shared/ # see Shared
├── index.ts
└── server.ts
```
## Feature anatomy
```
features/<feature>/
├── entities/ # back-end data model: types, enums, unions
│ └── <entity-name>/
│ ├── types.ts
│ └── index.ts
├── repositories/ # request + return data; no client-side dependencies
│ └── <repository-name>/
│ ├── <repository-name>.ts
│ ├── types.ts # e.g. LoginArgs, LoginDto, LoginResponseDto, LoginPayload
│ ├── mappers.ts # *Args → *Dto (outgoing), *ResponseDto → *Payload (incoming)
│ ├── constants.ts # endpoints and query keys
│ └── index.ts
├── caches/ # server-only React cache() reads
│ ├── <cache-name>.ts
│ ├── types.ts
│ ├── constants.ts
│ └── server.ts # the module's entry; no index.ts
├── actions/
│ └── <action-name>/
│ ├── actions.ts # the operation from start to end; emits its event
│ └── index.ts
├── models/ # logic per page and per part, as hooks
│ ├── login/ # a page with one model
│ │ ├── use-login-page.ts
│ │ ├── types.ts
│ │ ├── constants.ts
│ │ └── index.ts
│ └── shipment/ # a page model plus one model per part
│ ├── use-shipment-page.ts
│ ├── use-shipment-address-part.ts
│ ├── use-shipment-legal-part.ts
│ ├── use-shipment-bill-part.ts
│ └── index.ts
├── http.ts # the feature's HTTP client: http.extend(...); used only by its repositories
├── types.ts
├── constants.ts
└── index.ts # never exports the http.ts client
```
Rules inside a feature:
- Layers import only from earlier layers: entities → repositories → actions → models → UI.
- Repositories import only entities, libs, the feature's `http.ts`, and their own files. Actions may also use stores and browser libs such as `storage`, `cookie`, and the event emitter. Models may also use actions, stores, and validations.
- Caches sit beside that chain, on the server: they import only entities, repositories, and their own files, and only server code imports them (server page loaders in `models/`, pages, `generateMetadata`, and server components). Details: [b2c-b2b.md](b2c-b2b.md#data-flow).
- Every action takes an optional last parameter `{ emit?: boolean }`, default `true`, and emits its `<feature>.<action>` event from the feature's `constants.ts` when its steps succeed.
- A page model owns what its parts share, such as the current step and the final submit. Each part model owns its part's data and form.
- `http.ts` exports one client, `http.extend(...)`, named after the feature (`catalogHttp`). It may set the base URL, headers, timeout, retry, and feature-only interceptors. It never sets refresh, credentials, or cookie forwarding; the type of `extend` rejects them. Details: [lib-http.md](lib-http.md#root-and-feature-clients).
- Models call repositories directly for queries. Mutations with side effects beyond the request go through an action.
- `*Payload` is the only repository type used outside the repository. If server field names differ from `*Args` names, the mappers translate the server's `fieldErrors` keys too.
- Another feature is imported only through its `index.ts`.
## Shared
```
shared/
├── constants/
│ ├── <constant-name>.ts
│ └── index.ts
├── utils/
│ ├── <util-name>.ts
│ └── index.ts
└── validations/
├── types.ts
├── constants.ts
├── base-validations.ts
├── <feature>-validations.ts
└── index.ts
```
`shared/utils/` holds `apply-server-errors.ts` and `show-action-error.ts`, the two functions every failed action goes through ([code-patterns.md](code-patterns.md#validation-model-and-server-errors)).
`shared/` never imports from `features/`, `stores/`, or `app/`.
## island (`packages/island`)
```
packages/island/src/
├── atoms/
│ └── <component-name>/ # component module
├── molecules/ # like atoms, e.g. empty-state and error-state
├── organisms/
│ └── <component-name>/ # component module + private components/ and hooks/
├── templates/ # like organisms
├── primitives/ # non-visual structural pieces, e.g. portal, error-boundary; like organisms
├── tools/
│ └── <tool-name>/ # e.g. cn, icon-sprite-plugin, icon-name-extraction
│ ├── <tool-name>.ts or <tool-name>.tsx
│ ├── types.ts
│ ├── constants.ts
│ └── index.ts
├── styles/
│ ├── island.css # entry that apps import into their Tailwind v4 CSS
│ ├── theme.css # primitive and semantic tokens
│ └── utilities.css # custom @utility definitions
├── env/ # island's env: setEnv and getEnv, filled by the app's bootstrap
│ ├── env.ts
│ ├── types.ts
│ └── index.ts
├── icons/
│ ├── symbol-defs.svg # sprite generated by Icomoon
│ └── selection.json # Icomoon snapshot; re-import it into Icomoon to update the set
├── fonts/ # every app's fonts, e.g. yekan-bakh-vf.woff2; each app loads them with next/font/local
├── constants.ts # island-level constants
├── index.ts
└── server.ts
```
Component module:
| Entry | Required | Holds |
|---|---|---|
| `<ComponentName>.tsx` | Yes | The component |
| `types.ts` | Yes | Every type the component needs, including its props |
| `variants.ts` | Yes | The cva definitions. A non-visual primitive with no styles may skip it |
| `constants.ts` | No | Component-level constants |
| `index.ts` | Yes | The public API, re-exported by name |
| `components/` | Organisms, templates, primitives | Private sub-components shaped like atoms; never imported from outside, except a compound component's named parts, which its `index.ts` re-exports ([design-patterns.md](design-patterns.md)) |
| `hooks/` | Organisms, templates, primitives | Private `use-<hook-name>.ts` hooks |
Tools:
- `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/` folder. Build-time tools are imported only from build configs, never from app code.
- `icon-name-extraction` extracts icon names from the Icomoon files, for example to type the `Icon` component's `name` prop.
## libs, integrations, and tools packages
```
packages/libs/src/<lib-name>/ # e.g. http, env, error-handler, cookie, local-storage,
├── <lib-name>.ts # custom prototypes, regex, event-emitter
├── types.ts
├── constants.ts
└── index.ts
packages/integrations/src/<integration-name>/ # e.g. sentry, analytics
├── <integration-name>.ts
├── components/ # shaped like organisms
├── hooks/
│ └── use-<hook-name>.ts
├── constants.ts
├── types.ts
└── index.ts
packages/tools/src/<tool-name>/ # shared runtime tools
├── <tool-name>.ts
├── types.ts
├── constants.ts
└── index.ts
```
- libs are framework-agnostic: no React, Next.js, or TanStack imports. They never read env; the app's bootstrap passes their settings through `configure`.
- A lib may split its main file into more files when it grows. `http` does; its layout is in lib-http.md.
- Side-effect modules such as custom prototype extensions must be listed in `sideEffects` (see Exports).
Fundamental libs have full specs:
| Lib | Instance | Owns | Spec |
|---|---|---|---|
| `http` | Root `http`; one `http.extend(...)` client per feature | Every request: verbs, upload and download, interceptors, retry, one refresh at a time on 401, abort, `HttpError`; cookie forwarding on the server | [lib-http.md](lib-http.md) |
| `error-handler` | `configureErrorHandler`, `classifyError`, `describeError`, `handleError` | What each error shows (boundary, empty state, toast), its words and reference ID, its retry kind, and reporting 5xx and logic errors once | [lib-error-handler.md](lib-error-handler.md) |
| `env` | `createClientEnv`; `createServerEnv` (server) | Validating the app's env: public variables on both sides, server variables on the server only | [lib-env.md](lib-env.md) |
| `cookie` | `cookie` | Browser cookies for small values the server needs (locale, theme); never tokens | [lib-cookie.md](lib-cookie.md) |
| `local-storage` | `storage` | Prefixed, client-only, non-critical data and persisted zustand stores; never tokens or personal data | [lib-local-storage.md](lib-local-storage.md) |
`cookie` and `storage` are browser-only and export nothing from `server.ts`; `error-handler` runs on both sides and exports nothing from it either. `http` exports `configureServerHttp` from `server.ts`. `env` exports `createServerEnv` from its own `env/server.ts`, which the project's `server.ts` re-exports.
## Env flow
1. The app declares its variables in `apps/<app>/src/env/` and validates them with the env lib: `createClientEnv` for public variables and `createServerEnv` for server variables. These files are the only code that reads `process.env`, and a bad variable stops the app with one error that lists every problem.
2. Every other project that reads env has `src/env/` (`env.ts`, `types.ts`, `index.ts`) with `setEnv`, which stores its own values, and `getEnv`, which returns them and throws a clear error before `setEnv` has run. Its code reads env only through `getEnv`, inside functions, never at module top level.
3. At startup the app's bootstrap calls each project's `setEnv` with the values that project needs. Projects never import the app, so the dependency graph stays acyclic. Libs never read env: the bootstrap passes their settings through `configure`.
4. `bootstrap.server.ts` fills the server module graph and may pass server-side values, such as an internal service address; `bootstrap.client.ts` fills the client module graph with public values only. Public variables use the `NEXT_PUBLIC_` prefix and are listed one by one in `runtimeEnv`, because Next.js inlines only literal `process.env.NEXT_PUBLIC_*` references.
Code: [lib-env.md](lib-env.md).
## Nx tags and boundaries
Default tags. Reuse the repo's own tags if it already has them.
| Project | Tags |
|---|---|
| `apps/<app>` | `type:app`, `scope:<app>` |
| `platforms/<app>` | `type:platform`, `scope:<app>` |
| `packages/integrations` | `type:integration`, `scope:shared` |
| `packages/island` | `type:ui`, `scope:shared` |
| `packages/libs` | `type:lib`, `scope:shared` |
| `packages/tools` | `type:tool`, `scope:shared` |
`@nx/enforce-module-boundaries` constraints, the only ESLint rules the repo runs:
| Source tag | May depend on |
|---|---|
| `type:app` | `type:platform`, `type:integration`, `type:ui`, `type:lib`, `type:tool` |
| `type:platform` | `type:integration`, `type:ui`, `type:lib`, `type:tool` |
| `type:integration` | `type:ui`, `type:lib`, `type:tool` |
| `type:ui` | `type:lib`, `type:tool` |
| `type:lib` | `type:tool` |
| `type:tool` | Nothing |
| `scope:<app>` | `scope:<app>`, `scope:shared` |
| `scope:shared` | `scope:shared` |
Layer rules inside a project are checked in review, or by `eslint-plugin-boundaries` when the repo configures it:
- island: no import from a higher atomic level; an organism's `components/` and `hooks/` stay private.
- features: the layer order in Feature anatomy.
- `shared/`: imports nothing above it.
## Exports and tree-shaking
Expose each module on its own subpath. With package.json `exports` (Nx workspaces that use TypeScript project references):
```json
{
"name": "@project/island",
"sideEffects": ["**/*.css"],
"exports": {
".": "./src/index.ts",
"./server": "./src/server.ts",
"./atoms/*": "./src/atoms/*/index.ts",
"./molecules/*": "./src/molecules/*/index.ts",
"./organisms/*": "./src/organisms/*/index.ts",
"./templates/*": "./src/templates/*/index.ts",
"./primitives/*": "./src/primitives/*/index.ts",
"./tools/*": "./src/tools/*/index.ts",
"./env": "./src/env/index.ts",
"./styles/*": "./src/styles/*"
}
}
```
Workspaces that use `tsconfig.base.json` path aliases instead map `"@project/island": ["packages/island/src/index.ts"]` and `"@project/island/*": ["packages/island/src/*"]`.
- `sideEffects`: pure TypeScript modules have none. List every file that must run on import, such as CSS and custom prototype extensions; otherwise bundlers drop it.
- The root `index.ts` re-exports every module by name, so `@project/island` and `@project/island/atoms/button` expose the same symbols.
- A module with its own `server.ts` also gets a `<module>/server` subpath, for example `"./env/server": "./src/env/server.ts"` in libs. The project's `server.ts` re-exports it, so `@project/libs/server` and `@project/libs/env/server` expose the same symbols.