# utkarshj014/authsphere architecture

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

- Interactive diagram: https://gitdiagram.com/utkarshj014/authsphere
- Repository: https://github.com/utkarshj014/authsphere

## Overview

AuthSphere is an authentication and authorization platform exposed as an Express REST API; the listed web app is still the stock React/Vite starter, not a demonstrated product client. The principal workflow is an API request routed to authentication logic, which verifies or creates identity/session state and may issue tokens or queue email. Separate branches cover OAuth, MFA/security events, session management, user/role administration, and permission checks. The excerpts show only part of the implementation, so unsampled links are omitted rather than inferred.

Main entry points: [`apps/api/src/modules/auth/auth.service.ts`](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.service.ts) (Auth service), [`apps/api/src/modules/auth/oauth/oauth.service.ts`](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/oauth/oauth.service.ts) (OAuth flows), [`apps/api/src/app.ts`](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/app.ts) (Express application), [`apps/api/src/lib/prisma.ts`](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/lib/prisma.ts) (Prisma client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry"]
  node_app["Express application<br/>[app.ts]"]
end

subgraph group_identity["Identity and sessions"]
  node_auth["Authentication"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_auth_repository["Identity repository<br/>[auth.repository.ts]"]
  node_oauth["OAuth flows<br/>[oauth.service.ts]"]
  node_oauth_controller["OAuth controller"]
  node_oauth_providers["OAuth providers"]
  node_sessions["Session management"]
  node_sessions_service["Session service"]
  node_crypto["Token and MFA crypto"]
  node_jwt["JWT issuance"]
end

subgraph group_access["Access management"]
  node_users["User management"]
  node_roles["Role management"]
  node_authorization["Permission checks"]
end

subgraph group_platform["Persistence and messaging"]
  node_email_queue["Email queue<br/>[email.queue.ts]"]
  node_email_worker["Email worker<br/>[email.worker.ts]"]
  node_email_service["Email delivery<br/>[email.service.ts]"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_redis["Redis client<br/>[redis.ts]"]
  node_database[("PostgreSQL")]
end

node_caller(("API caller"))
node_provider_services["OAuth providers"]
node_email_provider["Resend"]

node_caller -->|"sends request"| node_app
node_app -->|"routes requests"| node_auth
node_app -->|"routes requests"| node_sessions
node_app -->|"routes requests"| node_users
node_app -->|"routes requests"| node_roles
node_auth -->|"registers routes"| node_auth_controller
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"reads and writes"| node_auth_repository
node_auth_repository -->|"queries"| node_prisma
node_auth_service -->|"uses"| node_crypto
node_auth_service -->|"issues tokens"| node_jwt
node_auth_service -->|"queues email"| node_email_queue
node_oauth_controller -->|"calls"| node_oauth
node_oauth -->|"looks up identities"| node_auth_repository
node_oauth -->|"creates sessions"| node_auth_service
node_oauth -->|"stores OAuth state"| node_redis
node_oauth -->|"dispatches to"| node_oauth_providers
node_provider_services -.->|"authorizes"| node_oauth
node_sessions -.->|"registers routes"| node_sessions_service
node_sessions_service -->|"records security event"| node_auth
node_sessions_service -.->|"accesses sessions"| node_prisma
node_roles -->|"invalidates permissions"| node_authorization
node_authorization -->|"caches permissions"| node_redis
node_authorization -->|"loads permissions"| node_prisma
node_users -.->|"persists users"| node_prisma
node_prisma -.->|"reads and writes"| node_database
node_email_queue -.->|"dispatches jobs"| node_email_worker
node_email_worker -->|"calls"| node_email_service
node_email_service -.->|"sends mail"| node_email_provider

click node_app "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/auth"
click node_auth_controller "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_auth_repository "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.repository.ts"
click node_oauth "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/oauth/oauth.service.ts"
click node_oauth_controller "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/oauth/oauth.controller.ts"
click node_oauth_providers "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/auth/oauth"
click node_sessions "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/sessions"
click node_sessions_service "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/sessions/sessions.service.ts"
click node_users "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/users"
click node_roles "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/roles"
click node_authorization "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/authorization/authorization.service.ts"
click node_crypto "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/lib/crypto"
click node_jwt "https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/lib/jwt"
click node_email_queue "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/email/email.queue.ts"
click node_email_worker "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/workers/email.worker.ts"
click node_email_service "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/email/email.service.ts"
click node_prisma "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/lib/prisma.ts"
click node_redis "https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/lib/redis.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_app toneBlue
class node_auth,node_auth_controller,node_auth_service,node_auth_repository,node_oauth,node_oauth_controller,node_oauth_providers,node_sessions,node_sessions_service,node_crypto,node_jwt toneAmber
class node_users,node_roles,node_authorization,node_caller toneMint
class node_email_queue,node_email_worker,node_email_service,node_prisma,node_redis,node_database toneRose
class node_provider_services,node_email_provider toneIndigo
```

## Components

### API entry

- [Express application](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`

### Identity and sessions

- [Authentication](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/auth): `apps/api/src/modules/auth`
- [Auth controller](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Identity repository](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/auth.repository.ts): `apps/api/src/modules/auth/auth.repository.ts`
- [OAuth flows](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/oauth/oauth.service.ts): `apps/api/src/modules/auth/oauth/oauth.service.ts`
- [OAuth controller](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/auth/oauth/oauth.controller.ts): `apps/api/src/modules/auth/oauth/oauth.controller.ts`
- [OAuth providers](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/auth/oauth): `apps/api/src/modules/auth/oauth`
- [Session management](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/sessions): `apps/api/src/modules/sessions`
- [Session service](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/sessions/sessions.service.ts): `apps/api/src/modules/sessions/sessions.service.ts`
- [Token and MFA crypto](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/lib/crypto): `apps/api/src/lib/crypto`
- [JWT issuance](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/lib/jwt): `apps/api/src/lib/jwt`

### Access management

- [User management](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/users): `apps/api/src/modules/users`
- [Role management](https://github.com/utkarshj014/authsphere/tree/main/apps/api/src/modules/roles): `apps/api/src/modules/roles`
- [Permission checks](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/authorization/authorization.service.ts): `apps/api/src/modules/authorization/authorization.service.ts`

### Persistence and messaging

- [Email queue](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/email/email.queue.ts): `apps/api/src/modules/email/email.queue.ts`
- [Email worker](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/workers/email.worker.ts): `apps/api/src/workers/email.worker.ts`
- [Email delivery](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/modules/email/email.service.ts): `apps/api/src/modules/email/email.service.ts`
- [Prisma client](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`
- [Redis client](https://github.com/utkarshj014/authsphere/blob/main/apps/api/src/lib/redis.ts): `apps/api/src/lib/redis.ts`
- **PostgreSQL**

### Other components

- **API caller**
- **OAuth providers**
- **Resend**

## Connections

- API caller → Express application: sends request (evidence: `README.md`)
- Express application → Authentication: routes requests (evidence: `apps/api/src/app.ts`)
- Express application → Session management: routes requests (evidence: `apps/api/src/app.ts`)
- Express application → User management: routes requests (evidence: `apps/api/src/app.ts`)
- Express application → Role management: routes requests (evidence: `apps/api/src/app.ts`)
- Authentication → Auth controller: registers routes (evidence: `apps/api/src/modules/auth/index.ts`)
- Auth controller → Auth service: calls (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Auth service → Identity repository: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Identity repository → Prisma client: queries (evidence: `apps/api/src/modules/auth/auth.repository.ts`)
- Auth service → Token and MFA crypto: uses (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Auth service → JWT issuance: issues tokens (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Auth service → Email queue: queues email (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- OAuth controller → OAuth flows: calls (evidence: `apps/api/src/modules/auth/oauth/oauth.controller.ts`)
- OAuth flows → Identity repository: looks up identities (evidence: `apps/api/src/modules/auth/oauth/oauth.service.ts`)
- OAuth flows → Auth service: creates sessions (evidence: `apps/api/src/modules/auth/oauth/oauth.service.ts`)
- OAuth flows → Redis client: stores OAuth state (evidence: `apps/api/src/modules/auth/oauth/oauth.service.ts`)
- OAuth flows → OAuth providers: dispatches to (evidence: `apps/api/src/modules/auth/oauth/oauth.service.ts`)
- OAuth providers → OAuth flows: authorizes
- Session management → Session service: registers routes (evidence: `apps/api/src/modules/sessions/sessions.controller.ts`)
- Session service → Authentication: records security event (evidence: `apps/api/src/modules/sessions/sessions.service.ts`)
- Session service → Prisma client: accesses sessions
- Role management → Permission checks: invalidates permissions (evidence: `apps/api/src/modules/roles/roles.service.ts`)
- Permission checks → Redis client: caches permissions (evidence: `apps/api/src/modules/authorization/authorization.service.ts`)
- Permission checks → Prisma client: loads permissions
- User management → Prisma client: persists users
- Prisma client → PostgreSQL: reads and writes
- Email queue → Email worker: dispatches jobs
- Email worker → Email delivery: calls (evidence: `apps/api/src/workers/email.worker.ts`)
- Email delivery → Resend: sends mail
