Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
75 lines (56 loc) · 2.25 KB

ARCHITECTURE.md

File metadata and controls

75 lines (56 loc) · 2.25 KB

Architecture

Overview

This project uses Next.js 15 App Router with React 19.
By default, we use React Server Components (RSC) for rendering, and API routes for all backend access.

The goal is to keep UI thin, backend logic centralized, and ensure type safety across the stack.

Project Structure

app/ → Routes and layouts api/ → API endpoints (backend logic only) components/ → Reusable UI components (server/client) lib/ → Backend utilities, DB access, third-party integrations hooks/ → Custom React hooks (client only) context/ → Global state providers public/ → Static assets tests/ → Unit, integration, and e2e tests

Data Flow

  1. Client Components → UI interactivity only.
  2. Server Components → Fetch data from backend APIs.
  3. API Routes → Single source of truth for DB queries and external APIs.
  4. Database / Services → Accessed only from backend.

State Management

  • Local state → useState / useReducer.
  • Global state → Context or Zustand (only if necessary).
  • Derived state → Prefer resolving on the server.

Styling

  • TailwindCSS for styling.
  • Use clsx or tailwind-variants for conditional classes.

Testing

  • Unit Tests → Jest + React Testing Library.
  • Integration Tests → Supertest for API routes.
  • E2E Tests → Playwright for full app flows.
  • Every feature must include tests.

Next.js 15+ Features

  • React 19 hooks (useActionState, useFormStatus) enabled.
  • Typed Routes (typedRoutes: true in next.config.ts).
  • Explicit Caching → No implicit caching, must configure (dynamic, revalidate).
  • after() API for background tasks after response streaming.
  • Turbopack in dev mode for faster builds.
  • Experimental Auth Interrupts (forbidden(), unauthorized()).

Deployment

  • Use .env.local for environment variables.
  • Deploy with Vercel by default.
  • Edge runtime (runtime = 'edge') for latency-sensitive routes.

Rules

  1. All backend access must go through API routes.
  2. Never fetch directly from DB in components.
  3. Use strict TypeScript.
  4. Keep components small and composable.
  5. All features must include tests before merging.