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

18 KiB

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, cvx, 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
│   └── 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. AuthGuard for pages that need a logged-in user
│   │   └── <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.
  • 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.
  • 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).

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, cvx, 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
│   └── fonts.css               # @font-face rules for fonts/
├── 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
├── 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)
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
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
env createClientEnv; createServerEnv (server) Validating the app's env: public variables on both sides, server variables on the server only lib-env.md
cookie cookie Browser cookies for small values the server needs (locale, theme); never tokens 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

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.

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):

{
  "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.