Architecture & Design

This page provides a technical overview of how the boilerplate is structured under the hood: architecture, authentication flow, security measures, testing setup, and the trade-offs made to keep it focused and easy to extend.

High-Level Architecture

The project is organised using a layered approach to keep concerns well-separated and the codebase easy to maintain:

  • UI Layer – pages, layouts, and presentational components in src/app and src/components.
  • Application Layer – route handlers and feature-specific services (e.g. auth) that orchestrate requests and responses.
  • Domain Layer – core auth logic, JWT handling, password hashing, and business rules in src/lib/auth.
  • Infrastructure Layer – repositories, email provider, environment parsing, rate limiter, and logging utilities.

Authentication logic is centralised in authService and related helpers. Data access is abstracted behind a UserRepository interface so the current in-memory implementation can be swapped for a database-backed one without changing the rest of the codebase.

Authentication Flow

Authentication is based on JSON Web Tokens with separate access and refresh tokens. The flow looks like this:

  1. User registers with email and password via POST /api/auth/register.
  2. Passwords are hashed using bcryptjs and stored via the UserRepository.
  3. On login, an access token (short-lived) and refresh token (longer-lived) are issued and stored as HttpOnly cookies.
  4. Protected pages (e.g. dashboard) rely on the access token, which is validated server-side using the JWT service.
  5. A password reset flow issues one-time reset tokens, stores them in the user record, and sends reset links via a pluggable email provider abstraction.

All token creation, verification, and cookie management is handled in the auth service and JWT helpers so the API route handlers stay thin and focused on HTTP concerns.

Routing & Middleware

The project uses the Next.js App Router with route handlers under src/app/api. Authentication-aware behaviour is implemented via src/middleware.ts:

  • Authenticated users are redirected away from auth pages (/login, /register etc.) to the dashboard.
  • Unauthenticated users attempting to access protected routes (e.g. /dashboard) are redirected to /login.
  • Middleware can read tokens from both cookies and the Authorization header, making it easier to extend into API clients later.

Security Considerations

  • JWT secrets and other critical values are validated at startup using zod in src/lib/env.ts.
  • Access and refresh tokens are stored in HttpOnly cookies, with the secure flag enabled in production.
  • A central HttpError type and API error handler ensure consistent error responses and logging.
  • A basic in-memory rate limiter is applied to sensitive endpoints like login and password reset to reduce brute-force attempts.

While the in-memory implementations are not intended for horizontal scaling, the abstractions are designed so that a Redis-backed rate limiter or database-backed user store can be introduced with minimal changes.

Testing & CI

The project uses Vitest for unit testing core logic:

  • Authentication service and JWT helpers
  • Password hashing utilities
  • Environment variable parsing and validation
  • Rate limiter logic
  • API route wrapper and error handling

A GitHub Actions workflow runs the test suite on every push and pull request using Node 20, providing fast feedback and ensuring the core behaviour stays correct as the project evolves.

Limitations & Next Steps

A few intentional limitations keep the boilerplate lightweight:

  • Users are stored in an in-memory repository.
  • Rate limiting is in-memory and process-bound.
  • The email provider currently logs messages to the console instead of sending real emails.

The next logical step would be integrating a real database (e.g. Postgres with Prisma or Drizzle), a Redis-backed rate limiter, and an external email provider such as Resend or Postmark. The existing abstractions are designed to make those upgrades straightforward.

Goal of This Boilerplate

The goal of this boilerplate is to act as a solid starting point for real-world products while also showcasing how I think about clean architecture, security, and developer experience in a modern Next.js codebase.