# corced/discorddam architecture

> Architecture diagram of the GitHub repository corced/discorddam, 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/corced/discorddam
- Repository: https://github.com/corced/discorddam

## Overview

DiscordDam gates web access on Discord OAuth and target-guild membership, then issues JWT-backed access. The auth server owns verification, sessions, and internal APIs; the Discord bot supplies membership checks and moderation commands through HTTP. The web screens represent login and access outcomes. Relationships involving unsampled UI pages and bot event handlers are omitted where the excerpts do not show their wiring.

Main entry points: [`packages/auth-server/src/routes/auth.ts`](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/auth.ts) (OAuth routes), [`packages/auth-server/src/routes/internal.ts`](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/internal.ts) (Internal API), [`packages/auth-server/src/db/repositories/userRepository.ts`](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/userRepository.ts) (User records), [`packages/auth-server/src/app.ts`](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/app.ts) (HTTP app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_login["Login screen<br/>[page.tsx]"]
  node_callback["OAuth callback<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_denied["Access denied<br/>[page.tsx]"]
end

subgraph group_auth["Auth service"]
  node_auth_app["HTTP app<br/>[app.ts]"]
  node_auth_routes["OAuth routes<br/>[auth.ts]"]
  node_token_routes["Token routes<br/>[token.ts]"]
  node_internal_routes["Internal API<br/>[internal.ts]"]
  node_oauth["Discord OAuth<br/>[discordOAuth.ts]"]
  node_guild_check["Guild verifier<br/>[guildVerifier.ts]"]
  node_jwt["JWT service<br/>[jwtService.ts]"]
  node_middleware["Request middleware"]
end

subgraph group_bot["Discord bot"]
  node_bot_client["Discord client<br/>[client.ts]"]
  node_commands["Moderation commands"]
  node_bot_api["Membership API<br/>[server.ts]"]
  node_verify_route["Verify route<br/>[verify.ts]"]
  node_webhook["Auth webhook client<br/>[authWebhook.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_types["Shared contracts<br/>[verification.ts]"]
end

subgraph group_state["Persistence and cache"]
  node_users[("User records<br/>[userRepository.ts]")]
  node_sessions[("Session records")]
  node_audit[("Audit records<br/>[auditRepository.ts]")]
  node_auth_redis[("Auth Redis<br/>[redisService.ts]")]
  node_bot_redis[("Bot Redis<br/>[redisService.ts]")]
end

node_visitor(("Visitor"))
node_discord["Discord"]
node_postgres[("PostgreSQL")]

node_auth_app -->|"mounts"| node_auth_routes
node_auth_app -->|"mounts"| node_token_routes
node_auth_app -->|"mounts"| node_internal_routes
node_auth_routes -->|"uses"| node_middleware
node_auth_routes -->|"exchanges code"| node_oauth
node_auth_routes -->|"checks membership"| node_guild_check
node_auth_routes -->|"upserts user"| node_users
node_auth_routes -->|"issues tokens"| node_jwt
node_auth_routes -->|"creates session"| node_sessions
node_auth_routes -->|"OAuth exchange"| node_discord
node_token_routes -->|"checks membership"| node_guild_check
node_token_routes -->|"validates tokens"| node_jwt
node_internal_routes -->|"queries users"| node_users
node_internal_routes -->|"manages sessions"| node_sessions
node_internal_routes -->|"records events"| node_audit
node_oauth -->|"stores PKCE"| node_auth_redis
node_guild_check -.->|"checks membership"| node_bot_api
node_jwt -->|"tracks tokens"| node_auth_redis
node_users -->|"logs revocation"| node_audit
node_users -->|"queries"| node_postgres
node_sessions -->|"queries"| node_postgres
node_audit -->|"queries"| node_postgres
node_bot_api -->|"registers route"| node_verify_route
node_verify_route -->|"checks Discord"| node_bot_client
node_commands -->|"calls internal API"| node_webhook
node_webhook -->|"HTTP requests"| node_internal_routes
node_commands -.->|"uses sync lock"| node_bot_redis
node_visitor -.->|"opens"| node_login
node_login -.->|"starts OAuth"| node_auth_routes
node_auth_routes -.->|"redirects outcomes"| node_callback
node_callback -.->|"shows access"| node_dashboard
node_callback -.->|"shows rejection"| node_denied

click node_login "https://github.com/corced/discorddam/blob/main/packages/web/app/login/page.tsx"
click node_callback "https://github.com/corced/discorddam/blob/main/packages/web/app/auth/callback/page.tsx"
click node_dashboard "https://github.com/corced/discorddam/blob/main/packages/web/app/dashboard/page.tsx"
click node_denied "https://github.com/corced/discorddam/blob/main/packages/web/app/access-denied/page.tsx"
click node_auth_app "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/app.ts"
click node_auth_routes "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/auth.ts"
click node_token_routes "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/token.ts"
click node_internal_routes "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/internal.ts"
click node_oauth "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/discordOAuth.ts"
click node_guild_check "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/guildVerifier.ts"
click node_jwt "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/jwtService.ts"
click node_middleware "https://github.com/corced/discorddam/tree/main/packages/auth-server/src/middleware"
click node_bot_client "https://github.com/corced/discorddam/blob/main/packages/bot/src/client.ts"
click node_commands "https://github.com/corced/discorddam/tree/main/packages/bot/src/commands"
click node_bot_api "https://github.com/corced/discorddam/blob/main/packages/bot/src/http/server.ts"
click node_verify_route "https://github.com/corced/discorddam/blob/main/packages/bot/src/http/routes/verify.ts"
click node_webhook "https://github.com/corced/discorddam/blob/main/packages/bot/src/services/authWebhook.ts"
click node_users "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/userRepository.ts"
click node_sessions "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/sessionRepository.ts"
click node_audit "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/auditRepository.ts"
click node_auth_redis "https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/redisService.ts"
click node_bot_redis "https://github.com/corced/discorddam/blob/main/packages/bot/src/services/redisService.ts"
click node_shared_types "https://github.com/corced/discorddam/blob/main/packages/shared/src/types/verification.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_login,node_callback,node_dashboard,node_denied toneBlue
class node_auth_app,node_auth_routes,node_token_routes,node_internal_routes,node_oauth,node_guild_check,node_jwt,node_middleware,node_postgres toneAmber
class node_bot_client,node_commands,node_bot_api,node_verify_route,node_webhook toneMint
class node_shared_types toneRose
class node_users,node_sessions,node_audit,node_auth_redis,node_bot_redis,node_visitor,node_discord toneIndigo
```

## Components

### Web experience

- [Login screen](https://github.com/corced/discorddam/blob/main/packages/web/app/login/page.tsx): `packages/web/app/login/page.tsx`
- [OAuth callback](https://github.com/corced/discorddam/blob/main/packages/web/app/auth/callback/page.tsx): `packages/web/app/auth/callback/page.tsx`
- [Dashboard](https://github.com/corced/discorddam/blob/main/packages/web/app/dashboard/page.tsx): `packages/web/app/dashboard/page.tsx`
- [Access denied](https://github.com/corced/discorddam/blob/main/packages/web/app/access-denied/page.tsx): `packages/web/app/access-denied/page.tsx`

### Auth service

- [HTTP app](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/app.ts): `packages/auth-server/src/app.ts`
- [OAuth routes](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/auth.ts): `packages/auth-server/src/routes/auth.ts`
- [Token routes](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/token.ts): `packages/auth-server/src/routes/token.ts`
- [Internal API](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/routes/internal.ts): `packages/auth-server/src/routes/internal.ts`
- [Discord OAuth](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/discordOAuth.ts): `packages/auth-server/src/services/discordOAuth.ts`
- [Guild verifier](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/guildVerifier.ts): `packages/auth-server/src/services/guildVerifier.ts`
- [JWT service](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/jwtService.ts): `packages/auth-server/src/services/jwtService.ts`
- [Request middleware](https://github.com/corced/discorddam/tree/main/packages/auth-server/src/middleware): `packages/auth-server/src/middleware`

### Discord bot

- [Discord client](https://github.com/corced/discorddam/blob/main/packages/bot/src/client.ts): `packages/bot/src/client.ts`
- [Moderation commands](https://github.com/corced/discorddam/tree/main/packages/bot/src/commands): `packages/bot/src/commands`
- [Membership API](https://github.com/corced/discorddam/blob/main/packages/bot/src/http/server.ts): `packages/bot/src/http/server.ts`
- [Verify route](https://github.com/corced/discorddam/blob/main/packages/bot/src/http/routes/verify.ts): `packages/bot/src/http/routes/verify.ts`
- [Auth webhook client](https://github.com/corced/discorddam/blob/main/packages/bot/src/services/authWebhook.ts): `packages/bot/src/services/authWebhook.ts`

### Shared contracts

- [Shared contracts](https://github.com/corced/discorddam/blob/main/packages/shared/src/types/verification.ts): `packages/shared/src/types/verification.ts`

### Persistence and cache

- [User records](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/userRepository.ts): `packages/auth-server/src/db/repositories/userRepository.ts`
- [Session records](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/sessionRepository.ts): `packages/auth-server/src/db/repositories/sessionRepository.ts`
- [Audit records](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/db/repositories/auditRepository.ts): `packages/auth-server/src/db/repositories/auditRepository.ts`
- [Auth Redis](https://github.com/corced/discorddam/blob/main/packages/auth-server/src/services/redisService.ts): `packages/auth-server/src/services/redisService.ts`
- [Bot Redis](https://github.com/corced/discorddam/blob/main/packages/bot/src/services/redisService.ts): `packages/bot/src/services/redisService.ts`

### Other components

- **Visitor**
- **Discord**
- **PostgreSQL**

## Connections

- HTTP app → OAuth routes: mounts (evidence: `packages/auth-server/src/app.ts`)
- HTTP app → Token routes: mounts (evidence: `packages/auth-server/src/app.ts`)
- HTTP app → Internal API: mounts (evidence: `packages/auth-server/src/app.ts`)
- OAuth routes → Request middleware: uses (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → Discord OAuth: exchanges code (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → Guild verifier: checks membership (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → User records: upserts user (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → JWT service: issues tokens (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → Session records: creates session (evidence: `packages/auth-server/src/routes/auth.ts`)
- OAuth routes → Discord: OAuth exchange (evidence: `packages/auth-server/src/routes/auth.ts`)
- Token routes → Guild verifier: checks membership (evidence: `packages/auth-server/src/routes/token.ts`)
- Token routes → JWT service: validates tokens (evidence: `packages/auth-server/src/routes/token.ts`)
- Internal API → User records: queries users (evidence: `packages/auth-server/src/routes/internal.ts`)
- Internal API → Session records: manages sessions (evidence: `packages/auth-server/src/routes/internal.ts`)
- Internal API → Audit records: records events (evidence: `packages/auth-server/src/routes/internal.ts`)
- Discord OAuth → Auth Redis: stores PKCE (evidence: `packages/auth-server/src/services/discordOAuth.ts`)
- Guild verifier → Membership API: checks membership
- JWT service → Auth Redis: tracks tokens (evidence: `packages/auth-server/src/services/jwtService.ts`)
- User records → Audit records: logs revocation (evidence: `packages/auth-server/src/db/repositories/userRepository.ts`)
- User records → PostgreSQL: queries (evidence: `packages/auth-server/src/db/repositories/userRepository.ts`)
- Session records → PostgreSQL: queries (evidence: `packages/auth-server/src/db/repositories/sessionRepository.ts`)
- Audit records → PostgreSQL: queries (evidence: `packages/auth-server/src/db/repositories/auditRepository.ts`)
- Membership API → Verify route: registers route (evidence: `packages/bot/src/http/server.ts`)
- Verify route → Discord client: checks Discord (evidence: `packages/bot/src/http/routes/verify.ts`)
- Moderation commands → Auth webhook client: calls internal API (evidence: `packages/bot/src/commands/index.ts`)
- Auth webhook client → Internal API: HTTP requests (evidence: `packages/bot/src/services/authWebhook.ts`)
- Moderation commands → Bot Redis: uses sync lock (evidence: `packages/bot/src/commands/syncmembers.ts`)
- Visitor → Login screen: opens
- Login screen → OAuth routes: starts OAuth
- OAuth routes → OAuth callback: redirects outcomes
- OAuth callback → Dashboard: shows access
- OAuth callback → Access denied: shows rejection
