How ixartz/next-js-boilerplate works
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: [locale]/layout.tsx Locale Root · (auth)/layout.tsx Auth · page.tsx Pages · DB.ts DB Access
Components 20
Routing
Locale-aware request boundary and route composition
- Proxy · Locale-aware request gate with Arcjet protection
src/proxy.ts
App UI
Marketing, auth, dashboard, and API routes
- Locale Root · Top-level localized App Router layout
src/app/[locale]/layout.tsx - Marketing · Public pages and demo surfaces
src/app/[locale]/(marketing)/layout.tsx - Auth · Clerk-centered authentication boundary
src/app/[locale]/(auth)/layout.tsx - Dashboard · Authenticated user area shell
src/app/[locale]/(auth)/dashboard/layout.tsx - Counter API · Server endpoint for the counter slice
src/app/api/counter/route.ts - Pages · Home, about, portfolio, and counter pages
src/app/[locale]/(marketing)/page.tsx - Sign-in Up · Hosted sign-in and sign-up screens
src/app/[locale]/(auth)/(center)/sign-in/[[...sign-in]]/page.tsx - User Profile · Clerk profile management surface
src/app/[locale]/(auth)/dashboard/user-profile/[[...user-profile]]/page.tsx
Shared UI
Reusable components, templates, styles, and validation
- Components · Reusable UI building blocks
src/components/Hello.tsx - Base Template · Default visual shell and theme template
src/templates/BaseTemplate.tsx - Counter Validation · Input validation for the counter slice
src/validations/CounterValidation.ts
Data
Database schema, access, and migrations
- Schema · Database model definition
src/models/Schema.ts - DB Access · Database connection and ORM access layer
src/libs/DB.ts - Migrations · Database migration history
migrations/0000_init-db.sql
Platform
Auth, i18n, config, observability, and runtime wiring
Connections 21
- 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