# ixartz/next-js-boilerplate architecture

> Architecture diagram of the GitHub repository ixartz/next-js-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ixartz/next-js-boilerplate
- Repository: https://github.com/ixartz/next-js-boilerplate

## Overview

1. This repository is a Next.js 16 App Router starter, not a domain-specific app. The architecture is intentionally modular: route groups, shared UI components, a thin data layer, and a set of cross-cutting platform integrations for auth, i18n, database, observability, and testing.

2. The UI is split by route boundary under `src/app/[locale]` into three main experiences: `marketing`, `auth`, and `dashboard`. That means the app is organized around public pages, authentication flows, and a protected user area rather than around feature-heavy business modules.

3. The request entry path is localized and protected at the edge. The `proxy.ts` file is the main boundary for request-time policy, and the README says it applies Arcjet rules there. Arcjet provides bot detection and WAF-style protections before requests reach route handlers or pages.

4. Authentication is handled by Clerk and concentrated in the auth route group. The sign-in, sign-up, and user profile flows live under `src/app/[locale]/(auth)/(center)` and `src/app/[locale]/(auth)/dashboard/user-profile`, with the dashboard itself sitting behind an auth layout. This keeps identity concerns separate from public marketing content.

5. Internationalization is a first-class app concern, not an afterthought. The app is localized at the routing level, with locale-aware navigation helpers in `src/libs/I18n*`, message catalogs in `src/locales/en.json` and `fr.json`, and a `LocaleSwitcher` component. Crowdin is used as the translation sync service for non-default languages.

6. The data layer is centered on Drizzle ORM and migrations. `src/models/Schema.ts` defines the schema, `migrations/` contains the SQL history, and `src/libs/DB.ts` plus `src/utils/DBConnection.ts` encapsulate database access. The project is designed to run locally against PGlite and in production against PostgreSQL, typically Neon.

7. There is a small API surface in `src/app/api`, currently exemplified by `api/counter/route.ts`. The counter feature is the clearest vertical slice in the repo: a form component, validation in `src/validations/CounterValidation.ts`, a display component for the current count, and a route handler that exposes the server-side state. This shows how UI, validation, and persistence are wired together.

8. Shared presentation code lives outside the route tree in `src/components`, `src/templates`, and `src/styles`. `BaseTemplate` is the default app shell/theme, while components like `DemoBanner`, `Sponsors`, and `Hello` are reusable building blocks used across pages and stories.

9. Environment and app configuration are centralized in `src/libs/Env.ts`, `src/utils/AppConfig.ts`, and similar utility modules. This keeps runtime configuration, app metadata, and library setup out of page code and makes the architecture more portable across environments.

10. Observability is built in as separate infrastructure concerns. Sentry handles error reporting, LogTape handles application logging, PostHog handles analytics, and Better Stack receives logs in production. `src/instrumentation.ts` and `src/instrumentation-client.ts` indicate that telemetry is wired into both server and client execution paths.

11. Quality gates are enforced at multiple layers. Vitest covers units and component logic, Playwright covers integration, E2E, visual, and Checkly-style uptime checks, and Storybook supports isolated UI development. This means the repo treats UI, behavior, and production availability as distinct verification boundaries.

12. The repo also includes a strong automation/tooling layer around the application: GitHub Actions workflows for CI, release, translation sync, and monitoring; Drizzle tooling for schema evolution; and quality tools like Oxlint, Oxfmt, Knip, Commitlint, Lefthook, and Codecov. These tools support the codebase but are not part of the runtime app architecture.

13. For an architecture diagram, the important flow is: browser request -> locale-aware edge/proxy protection -> Next.js App Router route group -> auth/i18n/layout layers -> shared components/templates -> API route or Drizzle-backed data access when needed -> observability and test/CI feedback loops around the system.

Main entry points: [`src/app/[locale]/layout.tsx`](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/layout.tsx) (Locale Root), [`src/app/[locale]/(auth)/layout.tsx`](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/layout.tsx) (Auth), [`src/app/[locale]/(marketing)/page.tsx`](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(marketing)/page.tsx) (Pages), [`src/libs/DB.ts`](https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/DB.ts) (DB Access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_proxy["Proxy<br/>edge policy<br/>[proxy.ts]"]
end

subgraph group_app["App UI"]
  node_locale_layout["Locale Root<br/>app shell<br/>[layout.tsx]"]
  node_marketing_layout["Marketing<br/>route group<br/>[layout.tsx]"]
  node_auth_layout["Auth<br/>route group<br/>[layout.tsx]"]
  node_dashboard_layout["Dashboard<br/>protected area<br/>[layout.tsx]"]
  node_api_counter["Counter API<br/>route handler<br/>[route.ts]"]
  node_marketing_pages["Pages<br/>public routes<br/>[page.tsx]"]
  node_auth_flows["Sign-in Up<br/>auth flows<br/>[page.tsx]"]
  node_user_profile["User Profile<br/>account flow<br/>[page.tsx]"]
end

subgraph group_shared["Shared UI"]
  node_components["Components<br/>ui primitives<br/>[Hello.tsx]"]
  node_template["Base Template<br/>app shell<br/>[BaseTemplate.tsx]"]
  node_validation["Counter Validation<br/>schema"]
end

subgraph group_data["Data"]
  node_schema["Schema<br/>[Schema.ts]"]
  node_db["DB Access<br/>data access<br/>[DB.ts]"]
  node_migrations[("Migrations<br/>sql history<br/>[0000_init-db.sql]")]
end

subgraph group_platform["Platform"]
  node_i18n["I18n<br/>locale runtime<br/>[I18n.ts]"]
  node_env_config["Config<br/>[Env.ts]"]
  node_observability["Telemetry<br/>observability<br/>[instrumentation.ts]"]
end

subgraph group_quality["Quality"]
  node_tests["Tests<br/>verification<br/>[Counter.integ.ts]"]
  node_tooling["Tooling<br/>automation<br/>[CI.yml]"]
end

node_proxy -->|"guards"| node_locale_layout
node_locale_layout -->|"routes to"| node_marketing_layout
node_locale_layout -->|"routes to"| node_auth_layout
node_auth_layout -->|"protects"| node_dashboard_layout
node_marketing_layout -->|"hosts"| node_marketing_pages
node_auth_layout -->|"hosts"| node_auth_flows
node_dashboard_layout -->|"hosts"| node_user_profile
node_marketing_pages -->|"uses"| node_components
node_marketing_pages -->|"wraps"| node_template
node_components -->|"composes"| node_template
node_api_counter -->|"validates"| node_validation
node_api_counter -->|"persists"| node_db
node_db -->|"maps"| node_schema
node_db -->|"evolves"| node_migrations
node_locale_layout -->|"localizes"| node_i18n
node_auth_layout -->|"configures"| node_env_config
node_locale_layout -->|"instruments"| node_observability
node_tests -->|"verifies"| node_components
node_tests -->|"covers"| node_api_counter
node_tooling -->|"automates"| node_tests
node_tooling -->|"manages"| node_migrations

click node_proxy "https://github.com/ixartz/next-js-boilerplate/blob/main/src/proxy.ts"
click node_locale_layout "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/layout.tsx"
click node_marketing_layout "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(marketing)/layout.tsx"
click node_auth_layout "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/layout.tsx"
click node_dashboard_layout "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/dashboard/layout.tsx"
click node_api_counter "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/api/counter/route.ts"
click node_marketing_pages "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(marketing)/page.tsx"
click node_auth_flows "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/(center)/sign-in/[[...sign-in]]/page.tsx"
click node_user_profile "https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/dashboard/user-profile/[[...user-profile]]/page.tsx"
click node_components "https://github.com/ixartz/next-js-boilerplate/blob/main/src/components/Hello.tsx"
click node_template "https://github.com/ixartz/next-js-boilerplate/blob/main/src/templates/BaseTemplate.tsx"
click node_validation "https://github.com/ixartz/next-js-boilerplate/blob/main/src/validations/CounterValidation.ts"
click node_schema "https://github.com/ixartz/next-js-boilerplate/blob/main/src/models/Schema.ts"
click node_db "https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/DB.ts"
click node_migrations "https://github.com/ixartz/next-js-boilerplate/blob/main/migrations/0000_init-db.sql"
click node_i18n "https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/I18n.ts"
click node_env_config "https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/Env.ts"
click node_observability "https://github.com/ixartz/next-js-boilerplate/blob/main/src/instrumentation.ts"
click node_tests "https://github.com/ixartz/next-js-boilerplate/blob/main/tests/integration/Counter.integ.ts"
click node_tooling "https://github.com/ixartz/next-js-boilerplate/blob/main/.github/workflows/CI.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_proxy toneBlue
class node_locale_layout,node_marketing_layout,node_auth_layout,node_dashboard_layout,node_api_counter,node_marketing_pages,node_auth_flows,node_user_profile toneAmber
class node_components,node_template,node_validation toneMint
class node_schema,node_db,node_migrations toneRose
class node_i18n,node_env_config,node_observability toneIndigo
class node_tests,node_tooling toneTeal
```

## Components

### Routing

Locale-aware request boundary and route composition

- [Proxy](https://github.com/ixartz/next-js-boilerplate/blob/main/src/proxy.ts): edge policy · Locale-aware request gate with Arcjet protection · `src/proxy.ts`

### App UI

Marketing, auth, dashboard, and API routes

- [Locale Root](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/layout.tsx): app shell · Top-level localized App Router layout · `src/app/[locale]/layout.tsx`
- [Marketing](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(marketing)/layout.tsx): route group · Public pages and demo surfaces · `src/app/[locale]/(marketing)/layout.tsx`
- [Auth](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/layout.tsx): route group · Clerk-centered authentication boundary · `src/app/[locale]/(auth)/layout.tsx`
- [Dashboard](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/dashboard/layout.tsx): protected area · Authenticated user area shell · `src/app/[locale]/(auth)/dashboard/layout.tsx`
- [Counter API](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/api/counter/route.ts): route handler · Server endpoint for the counter slice · `src/app/api/counter/route.ts`
- [Pages](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(marketing)/page.tsx): public routes · Home, about, portfolio, and counter pages · `src/app/[locale]/(marketing)/page.tsx`
- [Sign-in Up](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/(center)/sign-in/[[...sign-in]]/page.tsx): auth flows · Hosted sign-in and sign-up screens · `src/app/[locale]/(auth)/(center)/sign-in/[[...sign-in]]/page.tsx`
- [User Profile](https://github.com/ixartz/next-js-boilerplate/blob/main/src/app/[locale]/(auth)/dashboard/user-profile/[[...user-profile]]/page.tsx): account flow · Clerk profile management surface · `src/app/[locale]/(auth)/dashboard/user-profile/[[...user-profile]]/page.tsx`

### Shared UI

Reusable components, templates, styles, and validation

- [Components](https://github.com/ixartz/next-js-boilerplate/blob/main/src/components/Hello.tsx): ui primitives · Reusable UI building blocks · `src/components/Hello.tsx`
- [Base Template](https://github.com/ixartz/next-js-boilerplate/blob/main/src/templates/BaseTemplate.tsx): app shell · Default visual shell and theme template · `src/templates/BaseTemplate.tsx`
- [Counter Validation](https://github.com/ixartz/next-js-boilerplate/blob/main/src/validations/CounterValidation.ts): schema · Input validation for the counter slice · `src/validations/CounterValidation.ts`

### Data

Database schema, access, and migrations

- [Schema](https://github.com/ixartz/next-js-boilerplate/blob/main/src/models/Schema.ts): drizzle schema · Database model definition · `src/models/Schema.ts`
- [DB Access](https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/DB.ts): data access · Database connection and ORM access layer · `src/libs/DB.ts`
- [Migrations](https://github.com/ixartz/next-js-boilerplate/blob/main/migrations/0000_init-db.sql): sql history · Database migration history · `migrations/0000_init-db.sql`

### Platform

Auth, i18n, config, observability, and runtime wiring

- [I18n](https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/I18n.ts): locale runtime · Locale routing and translation helpers · `src/libs/I18n.ts`
- [Config](https://github.com/ixartz/next-js-boilerplate/blob/main/src/libs/Env.ts): runtime config · Environment and app configuration · `src/libs/Env.ts`
- [Telemetry](https://github.com/ixartz/next-js-boilerplate/blob/main/src/instrumentation.ts): observability · Logging, error reporting, and analytics wiring · `src/instrumentation.ts`

### Quality

Testing, stories, and automation

- [Tests](https://github.com/ixartz/next-js-boilerplate/blob/main/tests/integration/Counter.integ.ts): verification · Unit, integration, E2E, visual, and story checks · `tests/integration/Counter.integ.ts`
- [Tooling](https://github.com/ixartz/next-js-boilerplate/blob/main/.github/workflows/CI.yml): automation · CI, release, translation sync, and code quality automation · `.github/workflows/CI.yml`

## Connections

- Proxy → Locale Root: guards · Protected, locale-aware entrypoint before routes render
- Locale Root → Marketing: routes to · Public experience branch
- Locale Root → Auth: routes to · Authentication branch
- Auth → Dashboard: protects · Authenticated area sits behind the auth shell
- Marketing → Pages: hosts · Marketing route group renders public pages
- Auth → Sign-in Up: hosts · Sign-in and sign-up pages are grouped here
- Dashboard → User Profile: hosts · User profile lives inside the protected dashboard
- Pages → Components: uses · Public pages reuse shared UI blocks
- Pages → Base Template: wraps · Pages are rendered within the base shell
- Components → Base Template: composes · Shared components are assembled by the template layer
- Counter API → Counter Validation: validates · Request payloads are checked before handling
- Counter API → DB Access: persists · Counter state is stored through the data layer
- DB Access → Schema: maps · ORM access is defined by the schema
- DB Access → Migrations: evolves · Schema changes are applied via SQL migrations
- Locale Root → I18n: localizes · Routing and navigation are locale-aware
- Auth → Config: configures · Auth behavior depends on runtime configuration
- Locale Root → Telemetry: instruments · Server and client telemetry hooks are wired at app startup
- Tests → Components: verifies · Component logic and UI behavior are covered by tests
- Tests → Counter API: covers · Integration and E2E checks exercise the counter flow
- Tooling → Tests: automates · CI and workflow automation run the verification stack
- Tooling → Migrations: manages · Database and release automation support schema evolution
