# akshat-shukla18/scalable-auth architecture

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

- Interactive diagram: https://gitdiagram.com/akshat-shukla18/scalable-auth
- Repository: https://github.com/akshat-shukla18/scalable-auth

## Overview

This is a web authentication and session-management platform. The main workflow runs from browser registration and email verification through login, token refresh, and session management; the API persists identity/session state and queues verification email for background delivery. Separate branches provide distributed rate limiting and operational health/metrics. The README documents broader scaling and security capabilities, but the supplied tree does not include the reverse-proxy or deployment configuration, so those runtime components are not mapped.

Main entry points: [`apps/web/src/api/client.ts`](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/api/client.ts) (API client), [`apps/web/src/App.tsx`](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/App.tsx) (Web application), [`apps/api/src/app.ts`](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/app.ts) (HTTP application), [`apps/api/src/modules/auth/auth.routes.ts`](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.routes.ts) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_authstate["Auth context<br/>[AuthContext.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_authpages["Auth pages<br/>[RegisterPage.tsx]"]
  node_dashboard["Session dashboard<br/>[DashboardPage.tsx]"]
  node_observabilityui["Observability UI"]
end

subgraph group_api["API and identity"]
  node_apiapp["HTTP application<br/>[app.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_authcontroller["Auth controller<br/>[auth.controller.ts]"]
  node_authservice["Auth service<br/>[auth.service.ts]"]
  node_authrepo["Auth repository<br/>[auth.repository.ts]"]
  node_sessionroutes["Session routes<br/>[session.routes.ts]"]
  node_sessioncontroller["Session controller"]
  node_sessionservice["Session service<br/>[session.service.ts]"]
  node_authmiddleware["Authentication middleware<br/>[authenticate.ts]"]
  node_ratelimit["Rate limiting<br/>[rate-limiter.ts]"]
  node_sharedcontracts["Shared auth contracts<br/>[auth.schema.ts]"]
end

subgraph group_async["Email delivery"]
  node_emailqueue["Email job queue<br/>[email.queue.ts]"]
  node_emailworker["Email worker<br/>[email.worker.ts]"]
  node_emailprovider["Email providers<br/>[email.factory.ts]"]
  node_devmailbox["Dev mailbox<br/>[dev.routes.ts]"]
end

subgraph group_state["Shared state"]
  node_postgres[("PostgreSQL<br/>[prisma.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

subgraph group_ops["Operations"]
  node_systemroutes["System endpoints<br/>[system.routes.ts]"]
  node_systemcontroller["Health and metrics"]
end

node_visitor(("Browser user"))

node_visitor -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authpages
node_webapp -->|"routes to"| node_dashboard
node_webapp -->|"routes to"| node_observabilityui
node_webapp -->|"provides auth"| node_authstate
node_authpages -->|"updates auth"| node_authstate
node_authpages -->|"calls API"| node_apiclient
node_dashboard -->|"calls API"| node_apiclient
node_observabilityui -->|"fetches metrics"| node_apiclient
node_authstate -->|"restores session"| node_apiclient
node_apiclient -.->|"HTTP requests"| node_apiapp
node_apiapp -->|"mounts"| node_authroutes
node_apiapp -->|"mounts"| node_sessionroutes
node_apiapp -->|"mounts"| node_systemroutes
node_apiapp -->|"mounts in dev"| node_devmailbox
node_authroutes -->|"dispatches"| node_authcontroller
node_authcontroller -->|"delegates to"| node_authservice
node_authservice -->|"reads and writes"| node_authrepo
node_authrepo -->|"queries"| node_postgres
node_authservice -->|"queues verification"| node_emailqueue
node_emailqueue -.->|"stores jobs"| node_redis
node_emailworker -->|"dispatches email"| node_emailprovider
node_devmailbox -->|"inspects mock inbox"| node_emailprovider
node_sessionroutes -->|"dispatches"| node_sessioncontroller
node_sessioncontroller -->|"delegates to"| node_sessionservice
node_sessionservice -->|"uses session data"| node_authrepo
node_sessionroutes -->|"protects routes"| node_authmiddleware
node_authroutes -->|"protects routes"| node_authmiddleware
node_authroutes -->|"limits requests"| node_ratelimit
node_ratelimit -.->|"checks limits"| node_redis
node_systemroutes -->|"dispatches"| node_systemcontroller
node_systemcontroller -->|"checks health"| node_postgres
node_systemcontroller -->|"checks health"| node_redis
node_systemcontroller -->|"reads queue metrics"| node_emailqueue
node_authservice -->|"uses auth types"| node_sharedcontracts
node_apiclient -->|"uses response types"| node_sharedcontracts

click node_webapp "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/App.tsx"
click node_authstate "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/context/AuthContext.tsx"
click node_apiclient "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/api/client.ts"
click node_authpages "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/RegisterPage.tsx"
click node_dashboard "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/DashboardPage.tsx"
click node_observabilityui "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/ObservabilityPage.tsx"
click node_apiapp "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/app.ts"
click node_authroutes "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.routes.ts"
click node_authcontroller "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_authservice "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_authrepo "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.repository.ts"
click node_sessionroutes "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.routes.ts"
click node_sessioncontroller "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.controller.ts"
click node_sessionservice "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.service.ts"
click node_authmiddleware "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/middleware/authenticate.ts"
click node_ratelimit "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/middleware/rate-limiter.ts"
click node_emailqueue "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/queues/email.queue.ts"
click node_emailworker "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/workers/email.worker.ts"
click node_emailprovider "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/services/email/email.factory.ts"
click node_devmailbox "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/dev/dev.routes.ts"
click node_postgres "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/database/prisma.ts"
click node_redis "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/redis/redis.ts"
click node_systemroutes "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/system/system.routes.ts"
click node_systemcontroller "https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/system/system.controller.ts"
click node_sharedcontracts "https://github.com/akshat-shukla18/scalable-auth/blob/main/packages/shared/src/schemas/auth.schema.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_webapp,node_authstate,node_apiclient,node_authpages,node_dashboard,node_observabilityui,node_visitor toneBlue
class node_apiapp,node_authroutes,node_authcontroller,node_authservice,node_authrepo,node_sessionroutes,node_sessioncontroller,node_sessionservice,node_authmiddleware,node_ratelimit,node_sharedcontracts toneAmber
class node_emailqueue,node_emailworker,node_emailprovider,node_devmailbox toneMint
class node_postgres,node_redis toneRose
class node_systemroutes,node_systemcontroller toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Auth context](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/context/AuthContext.tsx): `apps/web/src/context/AuthContext.tsx`
- [API client](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`
- [Auth pages](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/RegisterPage.tsx): `apps/web/src/pages/RegisterPage.tsx`
- [Session dashboard](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/DashboardPage.tsx): `apps/web/src/pages/DashboardPage.tsx`
- [Observability UI](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/web/src/pages/ObservabilityPage.tsx): `apps/web/src/pages/ObservabilityPage.tsx`

### API and identity

- [HTTP application](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Auth routes](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.routes.ts): `apps/api/src/modules/auth/auth.routes.ts`
- [Auth controller](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Auth repository](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/auth/auth.repository.ts): `apps/api/src/modules/auth/auth.repository.ts`
- [Session routes](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.routes.ts): `apps/api/src/modules/sessions/session.routes.ts`
- [Session controller](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.controller.ts): `apps/api/src/modules/sessions/session.controller.ts`
- [Session service](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/sessions/session.service.ts): `apps/api/src/modules/sessions/session.service.ts`
- [Authentication middleware](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/middleware/authenticate.ts): `apps/api/src/middleware/authenticate.ts`
- [Rate limiting](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/middleware/rate-limiter.ts): `apps/api/src/middleware/rate-limiter.ts`
- [Shared auth contracts](https://github.com/akshat-shukla18/scalable-auth/blob/main/packages/shared/src/schemas/auth.schema.ts): `packages/shared/src/schemas/auth.schema.ts`

### Email delivery

- [Email job queue](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/queues/email.queue.ts): `apps/api/src/queues/email.queue.ts`
- [Email worker](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/workers/email.worker.ts): `apps/api/src/workers/email.worker.ts`
- [Email providers](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/services/email/email.factory.ts): `apps/api/src/services/email/email.factory.ts`
- [Dev mailbox](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/dev/dev.routes.ts): `apps/api/src/modules/dev/dev.routes.ts`

### Shared state

- [PostgreSQL](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/database/prisma.ts): `apps/api/src/database/prisma.ts`
- [Redis](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/redis/redis.ts): `apps/api/src/redis/redis.ts`

### Operations

- [System endpoints](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/system/system.routes.ts): `apps/api/src/modules/system/system.routes.ts`
- [Health and metrics](https://github.com/akshat-shukla18/scalable-auth/blob/main/apps/api/src/modules/system/system.controller.ts): `apps/api/src/modules/system/system.controller.ts`

### Other components

- **Browser user**

## Connections

- Browser user → Web application: uses (evidence: `apps/web/src/App.tsx`)
- Web application → Auth pages: routes to (evidence: `apps/web/src/App.tsx`)
- Web application → Session dashboard: routes to (evidence: `apps/web/src/App.tsx`)
- Web application → Observability UI: routes to (evidence: `apps/web/src/App.tsx`)
- Web application → Auth context: provides auth (evidence: `apps/web/src/App.tsx`)
- Auth pages → Auth context: updates auth (evidence: `apps/web/src/pages/RegisterPage.tsx`)
- Auth pages → API client: calls API (evidence: `apps/web/src/pages/RegisterPage.tsx`)
- Session dashboard → API client: calls API (evidence: `apps/web/src/pages/DashboardPage.tsx`)
- Observability UI → API client: fetches metrics (evidence: `apps/web/src/pages/ObservabilityPage.tsx`)
- Auth context → API client: restores session (evidence: `apps/web/src/context/AuthContext.tsx`)
- API client → HTTP application: HTTP requests
- HTTP application → Auth routes: mounts (evidence: `apps/api/src/app.ts`)
- HTTP application → Session routes: mounts (evidence: `apps/api/src/app.ts`)
- HTTP application → System endpoints: mounts (evidence: `apps/api/src/app.ts`)
- HTTP application → Dev mailbox: mounts in dev (evidence: `apps/api/src/app.ts`)
- Auth routes → Auth controller: dispatches (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Auth controller → Auth service: delegates to (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Auth service → Auth repository: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Auth repository → PostgreSQL: queries (evidence: `apps/api/src/modules/auth/auth.repository.ts`)
- Auth service → Email job queue: queues verification (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Email job queue → Redis: stores jobs
- Email worker → Email providers: dispatches email (evidence: `apps/api/src/workers/email.worker.ts`)
- Dev mailbox → Email providers: inspects mock inbox (evidence: `apps/api/src/modules/dev/dev.routes.ts`)
- Session routes → Session controller: dispatches (evidence: `apps/api/src/modules/sessions/session.routes.ts`)
- Session controller → Session service: delegates to (evidence: `apps/api/src/modules/sessions/session.controller.ts`)
- Session service → Auth repository: uses session data (evidence: `apps/api/src/modules/sessions/session.service.ts`)
- Session routes → Authentication middleware: protects routes (evidence: `apps/api/src/modules/sessions/session.routes.ts`)
- Auth routes → Authentication middleware: protects routes (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Auth routes → Rate limiting: limits requests (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Rate limiting → Redis: checks limits
- System endpoints → Health and metrics: dispatches (evidence: `apps/api/src/modules/system/system.routes.ts`)
- Health and metrics → PostgreSQL: checks health (evidence: `apps/api/src/modules/system/system.controller.ts`)
- Health and metrics → Redis: checks health (evidence: `apps/api/src/modules/system/system.controller.ts`)
- Health and metrics → Email job queue: reads queue metrics (evidence: `apps/api/src/modules/system/system.controller.ts`)
- Auth service → Shared auth contracts: uses auth types (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- API client → Shared auth contracts: uses response types (evidence: `apps/web/src/api/client.ts`)
