| name | frontend-architecture |
| description | Use when moving frontend files, creating React modules, refactoring UI, or deciding whether code belongs in app, domains, features, or shared. |
Frontend Architecture
Keep the frontend readable by enforcing structure, direct imports, and small files.
Non-Negotiable Rules
- Never create
public/, index.ts, or index.tsx anywhere under src/.
- Never create
components/ or utils/ as first-level folders inside src/features/* or src/domains/*.
- Use only these first-level folders inside features/domains:
screens, sections, ui, hooks, state, services, lib, types, internal.
shared is only for generic code. If code knows about GitLab, schedule logic, worklog, settings, or another business concept, it does not belong in shared.- Cross-feature reusable domain code belongs in
src/domains/*.
- Route containers, app shell, global providers, desktop integration, and Zustand access belong in
src/app/*.
- Prefer props over store access. Route/layout/bootstrap code may read
useAppStore; feature and domain UI should receive data through props.
- Use direct file imports only.
- Colocate tests with the source file using
Thing.tsx and Thing.test.tsx.
Placement Guide
src/app/*: router, layouts, boot flow, providers, desktop bridge, overlays, state.src/domains/*: reusable domain modules shared by multiple features or routes.src/features/*: user-facing flows that are owned by one feature.src/shared/ui/*: generic UI primitives.src/shared/lib/*: generic pure helpers.src/shared/testing/*: shared test-only helpers and fixtures.
Size Discipline
- Split
screens/*.tsx before they exceed 300 lines.
- Split
ui/*.tsx before they exceed 220 lines.
- Split
hooks, state, services, and lib files before they exceed 250 lines.
- Use
internal/ folders for private parts of a single unit when a file is getting crowded.
Import Boundaries
shared must not import from app, domains, or features.domains must not import from features.features must not import from other features.internal/* may only be imported by the owning unit.
Workflow
- Decide whether the code is app-level, domain-level, feature-level, or shared.
- Put it in the smallest folder scope that still matches its reuse boundary.
- Add or move the colocated test with the file.
- Run
npm run lint and npm run build.
