# mwanga45/nextjs-toolkit architecture

> Architecture diagram of the GitHub repository mwanga45/nextjs-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mwanga45/nextjs-toolkit
- Repository: https://github.com/mwanga45/nextjs-toolkit

## Overview

Next Toolkit is a frontend-only Next.js foundation for applications backed by an external REST API. The main workflow is users submitting validated login or registration forms, server actions calling auth endpoints, and successful tokens being stored in secure cookies before navigation. Protected dashboard access verifies the session and role; refresh and proxy handlers support ongoing API access. The README also documents password recovery, email verification, typed API boundaries, and client-side user state. The graph uses documented capabilities where source was not sampled; unsampled relationships are omitted.

Main entry points: [`src/features/auth/actions/auth-actions.ts`](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/actions/auth-actions.ts) (Auth actions), [`src/app/(auth)/login/page.tsx`](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(auth)/login/page.tsx) (Auth routes), [`src/lib/auth/session.ts`](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/auth/session.ts) (Session access), [`src/lib/api/client.ts`](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/api/client.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Application experience"]
  node_auth_pages["Auth routes<br/>[page.tsx]"]
  node_login_form["Login form<br/>[login-form.tsx]"]
  node_register_form["Registration form<br/>[register-form.tsx]"]
  node_verify_status["Email verification"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_role_gate["Role gate<br/>[role-gate.tsx]"]
  node_query_provider["Query provider<br/>[query-provider.tsx]"]
end

subgraph group_auth["Authentication"]
  node_user_hook["User state hook<br/>[use-user.ts]"]
  node_auth_actions["Auth actions<br/>[auth-actions.ts]"]
  node_auth_validation["Auth schemas<br/>[auth.ts]"]
  node_auth_api["Auth API<br/>[auth-api.ts]"]
end

subgraph group_session["Session security"]
  node_session_access["Session access<br/>[session.ts]"]
  node_jwt["JWT verification<br/>[jwt.ts]"]
  node_cookies["Session cookies<br/>[cookies.ts]"]
  node_refresh["Token refresh<br/>[refresh.ts]"]
  node_refresh_route["Refresh handler<br/>[route.ts]"]
  node_route_guard["Route guard<br/>[proxy.ts]"]
end

subgraph group_backend["API integration"]
  node_api_client["Typed API client<br/>[client.ts]"]
  node_api_proxy["API proxy<br/>[route.ts]"]
  node_rest_api{{"External REST API"}}
end

node_visitor(("User"))

node_visitor -->|"opens auth"| node_auth_pages
node_visitor -.->|"opens dashboard"| node_dashboard
node_auth_pages -->|"renders"| node_login_form
node_auth_pages -->|"renders"| node_register_form
node_login_form -->|"validates with"| node_auth_validation
node_register_form -->|"validates with"| node_auth_validation
node_login_form -->|"submits to"| node_auth_actions
node_register_form -->|"submits to"| node_auth_actions
node_verify_status -->|"calls"| node_auth_actions
node_auth_actions -->|"validates with"| node_auth_validation
node_auth_actions -->|"calls login/register"| node_auth_api
node_auth_actions -->|"calls"| node_api_client
node_auth_actions -->|"sets and clears"| node_cookies
node_auth_actions -->|"reads expiry"| node_jwt
node_auth_api -->|"requests through"| node_api_client
node_dashboard -->|"checks session"| node_session_access
node_dashboard -->|"renders"| node_role_gate
node_session_access -->|"reads token"| node_cookies
node_session_access -->|"verifies token"| node_jwt
node_role_gate -->|"uses role type"| node_jwt
node_refresh_route -->|"refreshes tokens"| node_refresh
node_refresh_route -->|"reads and sets"| node_cookies
node_route_guard -.->|"guards routes"| node_session_access
node_route_guard -->|"routes by policy"| node_auth_pages
node_api_client -->|"reads access token"| node_cookies
node_api_client -->|"fetches endpoints"| node_rest_api
node_api_proxy -.->|"forwards requests"| node_rest_api
node_user_hook -->|"calls user action"| node_auth_actions
node_query_provider -.->|"provides query state"| node_user_hook

click node_auth_pages "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(auth)/login/page.tsx"
click node_login_form "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/components/login-form.tsx"
click node_register_form "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/components/register-form.tsx"
click node_verify_status "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(auth)/verify-email/verify-email-status.tsx"
click node_dashboard "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_role_gate "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/components/shared/role-gate.tsx"
click node_query_provider "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/providers/query-provider.tsx"
click node_user_hook "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/hooks/use-user.ts"
click node_auth_actions "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/actions/auth-actions.ts"
click node_auth_validation "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/schemas/auth.ts"
click node_auth_api "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/api/auth-api.ts"
click node_session_access "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/auth/session.ts"
click node_jwt "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/jwt.ts"
click node_cookies "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/cookies.ts"
click node_refresh "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/refresh.ts"
click node_refresh_route "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/api/auth/refresh/route.ts"
click node_route_guard "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/proxy.ts"
click node_api_client "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/api/client.ts"
click node_api_proxy "https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/api/proxy/%5B...path%5D/route.ts"

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_auth_pages,node_login_form,node_register_form,node_verify_status,node_dashboard,node_role_gate,node_query_provider,node_visitor toneBlue
class node_user_hook,node_auth_actions,node_auth_validation,node_auth_api toneAmber
class node_session_access,node_jwt,node_cookies,node_refresh,node_refresh_route,node_route_guard toneMint
class node_api_client,node_api_proxy,node_rest_api toneRose
```

## Components

### Application experience

- [Auth routes](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Login form](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/components/login-form.tsx): `src/features/auth/components/login-form.tsx`
- [Registration form](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/components/register-form.tsx): `src/features/auth/components/register-form.tsx`
- [Email verification](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(auth)/verify-email/verify-email-status.tsx): `src/app/(auth)/verify-email/verify-email-status.tsx`
- [Dashboard](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/(dashboard)/dashboard/page.tsx): `src/app/(dashboard)/dashboard/page.tsx`
- [Role gate](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/components/shared/role-gate.tsx): `src/components/shared/role-gate.tsx`
- [Query provider](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/providers/query-provider.tsx): `src/providers/query-provider.tsx`

### Authentication

- [User state hook](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/hooks/use-user.ts): `src/features/auth/hooks/use-user.ts`
- [Auth actions](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/actions/auth-actions.ts): `src/features/auth/actions/auth-actions.ts`
- [Auth schemas](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/schemas/auth.ts): `src/features/auth/schemas/auth.ts`
- [Auth API](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/features/auth/api/auth-api.ts): `src/features/auth/api/auth-api.ts`

### Session security

- [Session access](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/auth/session.ts): `src/lib/auth/session.ts`
- [JWT verification](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/jwt.ts): `src/lib/session/jwt.ts`
- [Session cookies](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/cookies.ts): `src/lib/session/cookies.ts`
- [Token refresh](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/session/refresh.ts): `src/lib/session/refresh.ts`
- [Refresh handler](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/api/auth/refresh/route.ts): `src/app/api/auth/refresh/route.ts`
- [Route guard](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/proxy.ts): `src/proxy.ts`

### API integration

- [Typed API client](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/lib/api/client.ts): `src/lib/api/client.ts`
- [API proxy](https://github.com/mwanga45/nextjs-toolkit/blob/main/src/app/api/proxy/%5B...path%5D/route.ts): `src/app/api/proxy/[...path]/route.ts`
- **External REST API**

### Other components

- **User**

## Connections

- User → Auth routes: opens auth (evidence: `src/app/(auth)/login/page.tsx`)
- User → Dashboard: opens dashboard (evidence: `src/app/(dashboard)/dashboard/page.tsx`)
- Auth routes → Login form: renders (evidence: `src/app/(auth)/login/page.tsx`)
- Auth routes → Registration form: renders
- Login form → Auth schemas: validates with (evidence: `src/features/auth/components/login-form.tsx`)
- Registration form → Auth schemas: validates with (evidence: `src/features/auth/components/register-form.tsx`)
- Login form → Auth actions: submits to (evidence: `src/features/auth/components/login-form.tsx`)
- Registration form → Auth actions: submits to (evidence: `src/features/auth/components/register-form.tsx`)
- Email verification → Auth actions: calls (evidence: `src/app/(auth)/verify-email/verify-email-status.tsx`)
- Auth actions → Auth schemas: validates with (evidence: `src/features/auth/actions/auth-actions.ts`)
- Auth actions → Auth API: calls login/register (evidence: `src/features/auth/actions/auth-actions.ts`)
- Auth actions → Typed API client: calls (evidence: `src/features/auth/actions/auth-actions.ts`)
- Auth actions → Session cookies: sets and clears (evidence: `src/features/auth/actions/auth-actions.ts`)
- Auth actions → JWT verification: reads expiry (evidence: `src/features/auth/actions/auth-actions.ts`)
- Auth API → Typed API client: requests through (evidence: `src/features/auth/api/auth-api.ts`)
- Dashboard → Session access: checks session (evidence: `src/app/(dashboard)/dashboard/page.tsx`)
- Dashboard → Role gate: renders (evidence: `src/app/(dashboard)/dashboard/page.tsx`)
- Session access → Session cookies: reads token (evidence: `src/lib/auth/session.ts`)
- Session access → JWT verification: verifies token (evidence: `src/lib/auth/session.ts`)
- Role gate → JWT verification: uses role type (evidence: `src/components/shared/role-gate.tsx`)
- Refresh handler → Token refresh: refreshes tokens (evidence: `src/app/api/auth/refresh/route.ts`)
- Refresh handler → Session cookies: reads and sets (evidence: `src/app/api/auth/refresh/route.ts`)
- Route guard → Session access: guards routes
- Route guard → Auth routes: routes by policy (evidence: `src/proxy.ts`)
- Typed API client → Session cookies: reads access token (evidence: `src/lib/api/client.ts`)
- Typed API client → External REST API: fetches endpoints (evidence: `src/lib/api/client.ts`)
- API proxy → External REST API: forwards requests (evidence: `src/app/api/proxy/[...path]/route.ts`)
- User state hook → Auth actions: calls user action (evidence: `src/features/auth/hooks/use-user.ts`)
- Query provider → User state hook: provides query state
