# amalkrishnaas/auth-toolbox architecture

> Architecture diagram of the GitHub repository amalkrishnaas/auth-toolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amalkrishnaas/auth-toolbox
- Repository: https://github.com/amalkrishnaas/auth-toolbox

## Overview

1. **Overall shape**
   - This is a Next.js 14 App Router authentication starter.
   - The architecture is centered around a server-first auth stack: Auth.js/NextAuth v5, Prisma/PostgreSQL, server actions, and route protection via middleware.

2. **Route structure: public vs protected**
   - Public pages live under `app/auth/*` for sign-in, registration, reset, new password, and verification flows.
   - Protected application pages live under `app/(protected)/*` and are grouped into `client`, `server`, `admin`, and `settings`.
   - `app/layout.tsx` and `app/(protected)/layout.tsx` provide the global and authenticated shells, with shared navigation in `app/(protected)/_components/Navbar.tsx`.

3. **Authentication entry points**
   - The central auth runtime is split across `auth.ts` and `auth.config.ts`.
   - `app/api/auth/[...nextauth]/route.ts` exposes the Auth.js handler for sign-in, session, and provider callbacks.
   - `app/api/admin/route.ts` is a separate protected API boundary for admin-only behavior.

4. **Server actions as the main mutation layer**
   - The `actions/` folder contains server actions for login, register, logout, settings updates, password reset, new password submission, admin operations, and verification flows.
   - These actions are the primary bridge between form UI and backend state changes, keeping most auth mutations off the client.

5. **Data access and persistence**
   - Prisma is the ORM layer, with schema and migrations under `prisma/`.
   - The `data/` folder contains model-specific access helpers for users, accounts, tokens, password reset tokens, verification tokens, and two-factor data.
   - `lib/db.ts` likely provides the shared Prisma client, and `lib/tokens.ts` centralizes token generation/verification logic.

6. **Auth flow features**
   - The repo supports email/password auth, OAuth providers, email verification, password reset, and two-factor authentication.
   - These flows are coordinated through the server actions, the token tables, and the auth pages under `app/auth/*`.
   - `app/auth/error/page.tsx` and `app/auth/new-verification/page.tsx` handle post-flow states and failure recovery.

7. **Session and identity propagation**
   - The hooks in `hooks/` expose the current user and role to client components.
   - `next-auth.d.ts` extends session/user typing so the app can safely consume role and auth metadata.
   - `components/auth/RoleGate.tsx` and `components/UserInfo.tsx` are presentation gates around identity-aware UI.

8. **Protected UI composition**
   - The protected area is split by audience or capability: client, server, and admin pages.
   - This suggests a layered authorization model where some pages are merely authenticated, while others check role or admin claims.
   - `components/auth/UserButton.tsx`, `LogoutButton.tsx`, and `LoginButton.tsx` provide the session-aware navigation actions.

9. **Email and verification delivery**
   - `mail.ts` and `email-template.ts` encapsulate outbound email delivery, backed by Resend per the README.
   - Verification and reset flows depend on these email paths, so mail is a first-class subsystem rather than incidental utility.
   - The token tables in `data/` support one-time links and time-bound verification.

10. **Cross-cutting security controls**
   - `middleware.ts` is the route-level guard that enforces access control before pages render.
   - `middleware/ratelimit.ts` adds abuse protection, likely around sensitive auth endpoints or actions.
   - `routes.ts` appears to centralize route constants so auth redirects and guards stay consistent.

11. **UI and form system**
   - `components/auth/*` contains the reusable auth-specific forms and wrappers, while `components/ui/*` is the lower-level design system built on shadcn/ui.
   - Validation and form state are handled in the form components, with `components/FormError.tsx` and `components/FormSuccess.tsx` providing common feedback states.
   - `components/settings/settings-form.tsx` is the main authenticated profile/settings editor.

12. **Architecture boundaries to draw**
   - Client components: forms, buttons, gates, and user-facing shells.
   - Server actions and route handlers: all mutations and auth endpoints.
   - Persistence: Prisma models plus token/user/account tables.
   - External services: OAuth providers, Resend for email, PostgreSQL via Neon.
   - Security layer: Auth.js session handling plus middleware and rate limiting.

13. **What is intentionally not central**
   - This is not a generic business app; the entire repository is optimized around identity lifecycle management.
   - Most “application” pages are placeholders for auth-state-based access patterns, demonstrating how to separate public, authenticated, and admin experiences within one Next.js codebase.

Main entry points: [`actions`](https://github.com/amalkrishnaas/auth-toolbox/tree/main/actions) (Server actions), [`auth.ts`](https://github.com/amalkrishnaas/auth-toolbox/blob/main/auth.ts) (Auth core), [`app/(protected)/layout.tsx`](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/(protected)/layout.tsx) (Protected shell), [`middleware.ts`](https://github.com/amalkrishnaas/auth-toolbox/blob/main/middleware.ts) (Middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["Routes"]
  node_app_layout["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_protected_layout["Protected shell<br/>Route layout<br/>[layout.tsx]"]
  node_auth_pages["Auth pages<br/>Public routes"]
  node_protected_pages["Protected pages<br/>App sections"]
end

subgraph group_auth["Auth Runtime"]
  node_auth_route["Auth handler<br/>Route handler<br/>[route.ts]"]
  node_admin_route["Admin API<br/>Route handler<br/>[route.ts]"]
  node_auth_config["Auth config<br/>[auth.config.ts]"]
  node_auth_runtime["Auth core<br/>Auth.js runtime<br/>[auth.ts]"]
end

subgraph group_mutation["Mutations"]
  node_server_actions["Server actions<br/>Mutation layer"]
end

subgraph group_data["Persistence"]
  node_users_data["User data<br/>Prisma access<br/>[user.ts]"]
  node_token_data["Token data<br/>Prisma access"]
  node_two_factor_data["2FA data<br/>Prisma access"]
end

subgraph group_ui["UI"]
  node_auth_ui["Auth UI<br/>Forms and gates"]
  node_settings_ui["Settings UI<br/>Profile form<br/>[settings-form.tsx]"]
  node_shared_ui["Shared UI<br/>Presentational components"]
  node_navbar["Navbar<br/>Shell component<br/>[Navbar.tsx]"]
end

subgraph group_security["Security"]
  node_middleware["Middleware<br/>Route guard<br/>[middleware.ts]"]
  node_ratelimit["Rate limit<br/>Abuse control<br/>[ratelimit.ts]"]
  node_session_types["Session types<br/>Type augmentation<br/>[next-auth.d.ts]"]
end

subgraph group_services["Services"]
  node_db_client[("DB client<br/>Prisma client<br/>[db.ts]")]
  node_token_service["Token service<br/>Token utils<br/>[tokens.ts]"]
  node_mail_service["Mail service<br/>Email delivery<br/>[mail.ts]"]
end

node_app_layout -->|"renders"| node_auth_pages
node_app_layout -->|"includes"| node_protected_layout
node_protected_layout -->|"uses"| node_navbar
node_protected_layout -->|"hosts"| node_protected_pages
node_auth_pages -->|"uses"| node_auth_ui
node_protected_pages -->|"uses"| node_settings_ui
node_protected_pages -->|"uses"| node_shared_ui
node_auth_ui -->|"submits to"| node_server_actions
node_settings_ui -->|"updates via"| node_server_actions
node_server_actions -->|"reads/writes"| node_users_data
node_server_actions -->|"uses"| node_token_data
node_server_actions -->|"uses"| node_two_factor_data
node_server_actions -->|"sends"| node_mail_service
node_server_actions -->|"issues"| node_token_service
node_users_data -->|"backed by"| node_db_client
node_token_data -->|"backed by"| node_db_client
node_two_factor_data -->|"backed by"| node_db_client
node_auth_runtime -->|"configured by"| node_auth_config
node_auth_route -->|"serves"| node_auth_runtime
node_admin_route -->|"delegates"| node_server_actions
node_middleware -->|"protects"| node_auth_runtime
node_middleware -->|"guards"| node_protected_layout
node_middleware -->|"invokes"| node_ratelimit
node_auth_runtime -->|"extends"| node_session_types
node_shared_ui -->|"consumes"| node_session_types
node_navbar -->|"reads session"| node_auth_runtime
node_mail_service -->|"encodes links"| node_token_service
node_auth_config -->|"uses adapters"| node_users_data

click node_app_layout "https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/layout.tsx"
click node_protected_layout "https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/(protected)/layout.tsx"
click node_auth_pages "https://github.com/amalkrishnaas/auth-toolbox/tree/main/app/auth"
click node_protected_pages "https://github.com/amalkrishnaas/auth-toolbox/tree/main/app/(protected)"
click node_auth_route "https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_admin_route "https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/api/admin/route.ts"
click node_auth_config "https://github.com/amalkrishnaas/auth-toolbox/blob/main/auth.config.ts"
click node_auth_runtime "https://github.com/amalkrishnaas/auth-toolbox/blob/main/auth.ts"
click node_server_actions "https://github.com/amalkrishnaas/auth-toolbox/tree/main/actions"
click node_users_data "https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/user.ts"
click node_token_data "https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/verification-token.ts"
click node_two_factor_data "https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/two-factor-token.ts"
click node_db_client "https://github.com/amalkrishnaas/auth-toolbox/blob/main/lib/db.ts"
click node_token_service "https://github.com/amalkrishnaas/auth-toolbox/blob/main/lib/tokens.ts"
click node_mail_service "https://github.com/amalkrishnaas/auth-toolbox/blob/main/mail.ts"
click node_middleware "https://github.com/amalkrishnaas/auth-toolbox/blob/main/middleware.ts"
click node_ratelimit "https://github.com/amalkrishnaas/auth-toolbox/blob/main/middleware/ratelimit.ts"
click node_session_types "https://github.com/amalkrishnaas/auth-toolbox/blob/main/next-auth.d.ts"
click node_auth_ui "https://github.com/amalkrishnaas/auth-toolbox/tree/main/components/auth"
click node_settings_ui "https://github.com/amalkrishnaas/auth-toolbox/blob/main/components/settings/settings-form.tsx"
click node_shared_ui "https://github.com/amalkrishnaas/auth-toolbox/tree/main/components"
click node_navbar "https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/(protected)/_components/Navbar.tsx"

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_app_layout,node_protected_layout,node_auth_pages,node_protected_pages,node_db_client,node_token_service,node_mail_service toneBlue
class node_auth_route,node_admin_route,node_auth_config,node_auth_runtime toneAmber
class node_server_actions toneMint
class node_users_data,node_token_data,node_two_factor_data toneRose
class node_auth_ui,node_settings_ui,node_shared_ui,node_navbar toneIndigo
class node_middleware,node_ratelimit,node_session_types toneTeal
```

## Components

### Routes

Public and protected Next.js App Router surfaces.

- [App shell](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/layout.tsx): Next.js layout · Global application layout for the App Router. · `app/layout.tsx`
- [Protected shell](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/(protected)/layout.tsx): Route layout · Authenticated app shell with shared navigation. · `app/(protected)/layout.tsx`
- [Auth pages](https://github.com/amalkrishnaas/auth-toolbox/tree/main/app/auth): Public routes · Sign-in, registration, reset, and verification pages. · `app/auth`
- [Protected pages](https://github.com/amalkrishnaas/auth-toolbox/tree/main/app/(protected)): App sections · Client, server, admin, and settings sections. · `app/(protected)`

### Auth Runtime

Core authentication configuration and handlers.

- [Auth handler](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/api/auth/[...nextauth]/route.ts): Route handler · Auth.js endpoint for sign-in, session, and callbacks. · `app/api/auth/[...nextauth]/route.ts`
- [Admin API](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/api/admin/route.ts): Route handler · Protected API boundary for admin-only behavior. · `app/api/admin/route.ts`
- [Auth config](https://github.com/amalkrishnaas/auth-toolbox/blob/main/auth.config.ts): Auth config · Provider, callback, and session configuration. · `auth.config.ts`
- [Auth core](https://github.com/amalkrishnaas/auth-toolbox/blob/main/auth.ts): Auth.js runtime · Server auth composition and shared auth entrypoint. · `auth.ts`

### Mutations

Server actions that drive auth and account changes.

- [Server actions](https://github.com/amalkrishnaas/auth-toolbox/tree/main/actions): Mutation layer · Login, register, logout, settings, reset, verification, and admin actions. · `actions`

### Persistence

Prisma models and shared data access helpers.

- [User data](https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/user.ts): Prisma access · User and account persistence helpers. · `data/user.ts`
- [Token data](https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/verification-token.ts): Prisma access · Password reset, verification, and two-factor token storage. · `data/verification-token.ts`
- [2FA data](https://github.com/amalkrishnaas/auth-toolbox/blob/main/data/two-factor-token.ts): Prisma access · Two-factor token and confirmation persistence helpers. · `data/two-factor-token.ts`

### UI

Reusable auth, settings, and shell components.

- [Auth UI](https://github.com/amalkrishnaas/auth-toolbox/tree/main/components/auth): Forms and gates · Auth forms, buttons, role gates, and shared feedback components. · `components/auth`
- [Settings UI](https://github.com/amalkrishnaas/auth-toolbox/blob/main/components/settings/settings-form.tsx): Profile form · Authenticated profile and settings editor. · `components/settings/settings-form.tsx`
- [Shared UI](https://github.com/amalkrishnaas/auth-toolbox/tree/main/components): Presentational components · User info and reusable success/error messaging. · `components`
- [Navbar](https://github.com/amalkrishnaas/auth-toolbox/blob/main/app/(protected)/_components/Navbar.tsx): Shell component · Authenticated navigation and session-aware actions. · `app/(protected)/_components/Navbar.tsx`

### Security

Route protection, rate limiting, and session typing.

- [Middleware](https://github.com/amalkrishnaas/auth-toolbox/blob/main/middleware.ts): Route guard · Edge-level access control for protected routes. · `middleware.ts`
- [Rate limit](https://github.com/amalkrishnaas/auth-toolbox/blob/main/middleware/ratelimit.ts): Abuse control · Rate limiting for sensitive auth endpoints and actions. · `middleware/ratelimit.ts`
- [Session types](https://github.com/amalkrishnaas/auth-toolbox/blob/main/next-auth.d.ts): Type augmentation · Extends auth session and user typing with role metadata. · `next-auth.d.ts`

### Services

Email, tokens, and database integration.

- [DB client](https://github.com/amalkrishnaas/auth-toolbox/blob/main/lib/db.ts): Prisma client · Shared Prisma database connection. · `lib/db.ts`
- [Token service](https://github.com/amalkrishnaas/auth-toolbox/blob/main/lib/tokens.ts): Token utils · Token generation and verification helpers. · `lib/tokens.ts`
- [Mail service](https://github.com/amalkrishnaas/auth-toolbox/blob/main/mail.ts): Email delivery · Outbound email composition and sending. · `mail.ts`

## Connections

- App shell → Auth pages: renders · Global layout wraps public auth screens.
- App shell → Protected shell: includes · Application shell nests protected shell.
- Protected shell → Navbar: uses · Protected layout shares the navigation bar.
- Protected shell → Protected pages: hosts · Authenticated layout contains protected sections.
- Auth pages → Auth UI: uses · Public auth screens compose reusable auth forms.
- Protected pages → Settings UI: uses · Settings section uses the profile editor.
- Protected pages → Shared UI: uses · Protected pages display shared user/feedback UI.
- Auth UI → Server actions: submits to · Forms and buttons trigger mutation actions.
- Settings UI → Server actions: updates via · Settings changes are persisted through server actions.
- Server actions → User data: reads/writes · Account flows access user and account records.
- Server actions → Token data: uses · Reset and verification flows store one-time tokens.
- Server actions → 2FA data: uses · Two-factor flows persist confirmations and tokens.
- Server actions → Mail service: sends · Verification and reset flows deliver email.
- Server actions → Token service: issues · Actions create and validate flow tokens.
- User data → DB client: backed by · User persistence runs through Prisma.
- Token data → DB client: backed by · Token tables are accessed through Prisma.
- 2FA data → DB client: backed by · Two-factor persistence uses Prisma models.
- Auth core → Auth config: configured by · Auth core is assembled from the shared config.
- Auth handler → Auth core: serves · Route handler exposes the auth runtime.
- Admin API → Server actions: delegates · Admin API boundary is implemented through actions.
- Middleware → Auth core: protects · Middleware relies on auth state for route guarding.
- Middleware → Protected shell: guards · Protected app surface is gated before render.
- Middleware → Rate limit: invokes · Security middleware can rate limit sensitive requests.
- Auth core → Session types: extends · Session and user claims are typed for app consumption.
- Shared UI → Session types: consumes · Identity-aware UI depends on typed session data.
- Navbar → Auth core: reads session · Navigation changes based on current auth state.
- Mail service → Token service: encodes links · Email content embeds time-bound auth tokens.
- Auth config → User data: uses adapters · Auth configuration maps identity records to persistence.
