Architecture

Purpose

This document explains how the boilerplate is structured at a system level — the layers, data flow, and design decisions. Read this **before** making significant code changes so you understand where things belong and what shouldn't be touched.

High-Level Layers

The application is organized into these layers:

┌─────────────────────────────────────────────┐
│          App / UI Layer                     │
│  src/app (pages, layouts, route handlers)   │
│  src/components (reusable UI components)    │
├─────────────────────────────────────────────┤
│          Domain Modules                     │
│  src/modules/auth (auth logic & components) │
├─────────────────────────────────────────────┤
│          API Layer                          │
│  src/app/api/v1/ (versioned REST endpoints) │
├─────────────────────────────────────────────┤
│          Core Infrastructure                │
│  src/lib/auth/   src/lib/config/           │
│  src/db/         src/lib/security/         │
│  src/lib/observability/                    │
├─────────────────────────────────────────────┤
│          Integration Providers              │
│  src/providers/ (theme, query, toast, auth) │
└─────────────────────────────────────────────┘

Layer Rules

• **UI** can import from **Modules** and **Providers**
• **Modules** can import from **Core Infrastructure**
• **Core Infrastructure** should not import from **UI** or **Modules**
• **API Routes** use **Core Infrastructure** for auth, validation, and responses

Runtime Modes

The boilerplate supports two runtime configurations that change how the app behaves.

Backend Mode

Controls where API logic runs:

Set with: `NEXT_PUBLIC_BACKEND_MODE=internal` or `external`.

Auth Provider Mode

Controls where authentication logic runs:

Set with: `NEXT_PUBLIC_AUTH_PROVIDER=better-auth` or `custom-auth`.

Request Path (Internal Mode)

Here's the journey of a typical request:

Browser
  │
  ▼
1. Next.js App Router renders page
  │
  ▼
2. If page is /login or /register:
   ──► proxy.ts checks session cookie
       ├─ Signed in? → Redirect to /docs
       └─ Not signed in? → Show login/register page
  │
  ▼
3. API request (e.g., POST /api/v1/auth/login):
   ──► Route handler processes request
       ├─ Validates input with Zod
       ├─ Calls service layer (e.g., auth service)
       ├─ Interacts with database via Drizzle
       └─ Returns standardized JSON response
  │
  ▼
4. Response sent back to browser

Key Files in the Request Path

Configuration Architecture

Centralized URL / Origin (`src/lib/config/url.ts`)

A single source of truth for all URLs instead of scattered `http://localhost:3000` strings.

All consumers (`site-config.ts`, `cookie-security.ts`, `redirect.ts`, Playwright config, sitemap, robots) use these functions — never raw strings.

Runtime Validation (`src/lib/config/validate.ts`)

Runs at app startup to catch missing env vars before they cause runtime errors. Checks `DATABASE_URL`, `AUTH_SESSION_SECRET`, and custom auth configuration.

i18n Architecture

src/i18n/
├── routing.ts   → Locale list (8 locales), default locale, routing config
├── config.ts    → i18n config object
├── request.ts   → Reads NEXT_LOCALE cookie, loads messages
├── navigation.ts → next-intl navigation helpers
└── messages/    → JSON translation files
    ├── en.json  → English
    ├── bn.json  → Bangla
    ├── es.json  → Spanish
    ├── fr.json  → French
    ├── de.json  → German
    ├── hi.json  → Hindi
    ├── ja.json  → Japanese
    └── ar.json  → Arabic

The language switcher in the Navbar is a dropdown that cycles through all 8 locales, sets a `NEXT_LOCALE` cookie, and refreshes the page. Each locale has full translations for nav, buttons, features, and docs descriptions.

Auth & Security Design

Session Tokens

When a user logs in, the server creates a **signed session token** stored in an httpOnly cookie:

Cookie: auth_token=<signed-jwt-like-token>

The token contains:

• `sub` — User ID
• `email` — User's email
• `role` — `admin` or `user`
• `mfaVerified` — Whether MFA was completed (for admin step-up)
• `iat` / `exp` — Issued at / Expiration timestamps

Security Controls

Config System

Environment variables and feature flags are validated at runtime:

.env.local
    │
    ▼
src/lib/config/env.ts       ← Schema definition (Zod + @t3-oss)
    │
    ▼
src/lib/config/validate.ts  ← Run on startup to check all required vars
    │
    ▼
src/lib/config/app-config.ts ← Parsed configuration object
    │
    ▼
src/lib/config/featureFlags.ts ← Feature flag definitions & helpers

How to Add a New Environment Variable

1. Add the variable to `.env.example`
2. Add its schema in `src/lib/config/env.ts` (server or client section)
3. Add its runtime value in the `runtimeEnv` section of `env.ts`
4. Use it via `env.YOUR_VARIABLE` in your code

Data Layer

Database

• **PostgreSQL-compatible providers** — PostgreSQL, Neon, Supabase Postgres
• **Drizzle ORM** — Type-safe SQL query builder and migration tool
• **Runtime DB client** — centralized in `src/db/index.ts`

Schema Location

• `src/db/schema` — Main database schema definition
• `drizzle/` — Generated migration SQL files

Provider Pattern

Database access is centralized through:

src/db/index.ts

Provider switching (PostgreSQL vs Neon vs Supabase Postgres) is handled via `DATABASE_URL`, not separate code providers.

Testing Strategy

What to Test Where

• **Unit tests** — Pure functions, utilities, helpers
• **Integration tests** — API routes, auth flows, database operations
• **E2E tests** — Critical user journeys (login, register, navigation)

Related Docs