Application Layering

This page translates the conventions we follow inside src/app into a set of layers so new contributors can orient themselves before shipping features. It is based on the current code that lives in ../src:

src/
├── app/
│   ├── [locale]/            # Server Components per locale
│   ├── actions/             # Server Actions (mutations)
│   ├── server/              # Server-side queries (reads)
│   ├── lib/                 # Shared domain & infra utilities
│   ├── api/                 # Route handlers / webhooks
│   ├── components/, hooks/  # Presentation helpers
│   └── types/               # Cross-layer types
├── fonts/, providers/, store/, types/
└── i18n/, middleware.ts

Layer Stack

Guiding rule: presentation never talks to Supabase directly. Every data read or mutation flows through the Application layer and eventually through a repository.

Request & Data Flow

1. Routing & Rendering – src/app/layout.tsx and every route under src/app/[locale]/… render via React Server Components. Client-only features (e.g., src/app/components/chat/chat-input.tsx) mark "use client" and call server actions through form action props or useServerAction hooks.
2. Server Actions (src/app/actions/*) – Each mutation file is a "use server" module that parses inputs (Zod schemas in src/app/lib/validations), enforces auth (requireAuth from src/app/lib/auth.ts), delegates to repositories, and returns an ActionResult<T> from src/app/lib/action-result.ts. Admin-only actions wrap their handler with withAdminAuth from src/app/lib/admin-action-wrapper.ts to avoid repeating boilerplate.
3. Server Queries (src/app/server/*) – Read-only helpers (e.g., server/projects/get-project-by-slug.ts) encapsulate Supabase fetches behind caching utilities such as createCachedQueryWithParams in src/app/lib/cache.ts. Presentation layers consume these helpers instead of hitting Supabase directly.
4. Repositories (src/app/lib/repositories/*) – Concrete data access (e.g., ProjectRepository, ConversationRepository) inherits from base-repository.ts and maps Database['public']['Tables'] rows into domain objects through src/app/lib/mappers/*. Admin repositories (like admin-repository.ts) call createAdminClient while regular repositories rely on createClient or createServerClient to respect RLS.
5. Supabase Clients & Utilities – src/app/lib/supabase/{server,client,admin}.ts centralize client creation, attach the correct session, and plug into helpers like query-timeout.ts and error-handler.ts. Never instantiate createBrowserClient or createClient outside this folder.
6. Caching & Invalidation – All shared cache tags are defined in src/app/lib/cache.ts. Every mutation must import the relevant revalidate* helper (e.g., revalidateProjects) after persisting data so Server Components see fresh content.
7. Observability & Analytics – src/app/lib/logger.ts and logger-edge.ts create pino-based loggers. Analytics events are centralized in src/app/lib/analytics-events.ts so server actions log consistent Mixpanel/GA payloads. Feature-specific analytics hooks live in src/app/hooks/*.

Application Layer Anatomy

• Server Actions Directory Structure – src/app/actions mirrors feature domains (ai/, projects/, products/, insights/, etc.). Every folder exposes functions via index.ts for discoverability and has unit tests under actions/__tests__/.
• Server Queries – Each file handles one query. Example: server/projects/get-project-by-slug.ts creates a cached query, fetches the row via Supabase, maps it with mapDbToProject, and logs errors using createServiceLogger('projects').
• ActionResult Pattern – ActionResult<T> enforces discriminated unions for success/failure. Helper functions success, failure, isSuccess, and getErrorMessage reduce boilerplate inside actions and repositories.
• Admin Wrapper – withAdminAuth reads the admin session via validateAdminAuth, so admin actions only focus on business logic.

Domain & Data Access Layer

Infrastructure Concerns

• Authentication – src/app/auth contains auth helpers (requireAuth, maybeGetSession, etc.). Middleware in src/middleware.ts wires next-intl locales and Supabase cookies so Server Components always know the user.
• Rate Limiting – src/app/lib/rate-limit.ts exposes Upstash-backed throttling, while src/app/lib/api-rate-limit.ts provides per-route helpers.
• External Providers – Stripe lives in lib/stripe*.ts, Resend in lib/resend.ts, analytics in lib/analytics.ts. Each provider has its own logger (stripe-logger.ts) to keep failure data structured.
• Testing & Quality Gates – Vitest config in vitest.config.ts, Playwright in playwright.config.ts, plus test helpers under src/app/test. Every significant action/query should have coverage in actions/__tests__/ or server/__tests__/.

Workflow Reminders

1. Add Zod schema before touching a repository. Schemas live in lib/validations and are reused by server actions and components.
2. Return ActionResult everywhere. It makes error handling predictable for UI callers.
3. Wrap admin mutations. Use withAdminAuth or withAdminAuthSimple to avoid duplicating session checks.
4. Always revalidate caches. Mutations must import the relevant revalidate* helper from lib/cache.ts.
5. Keep architecture docs updated. If you introduce a new cross-cutting service or data store, add a section here and link to more detailed ADRs.