Project Structure (Frontend Standard)

This document defines the standard code organization for Next.js frontends.

Standard structure (required)

Use feature-first under src/features/<feature>/... with a shared component library in src/components/.

src/
  features/
    auth/
      components/
      hooks/
      api.ts
      schemas.ts
    billing/
      components/
      hooks/
      api.ts
  components/
    buttons/
      Button/
        Button.tsx
        Button.test.tsx
        index.ts
      IconButton/
        IconButton.tsx
        index.ts
    fields/
      TextField/
      SelectField/
      CheckboxField/
    modals/
      Modal/
      ConfirmModal/
    tables/
      DataTable/
    layout/
      AppShell/
      PageHeader/
  lib/
    apiClient.ts
    env.ts
    utils.ts

Component placement rule (required)

• If a component is reused across 2+ features, it lives in src/components/.
• Otherwise, keep it inside the feature (src/features/<feature>/components/).

Feature module contents

Typical expectations for src/features/<feature>/:

• components/: feature-specific UI only
• hooks/: feature-specific hooks
• api.ts: feature API functions calling the BFF
• schemas.ts: Zod schemas for feature forms and runtime validation

Rule: feature modules should not leak “private” internals to other features without an explicit shared abstraction.