# souryaneelpal/whistledrop architecture

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

- Interactive diagram: https://gitdiagram.com/souryaneelpal/whistledrop
- Repository: https://github.com/souryaneelpal/whistledrop

## Overview

WhistleDrop is a confidential reporting API: reporters submit without accounts, receive a one-time case code, and use it to check status and public updates; moderators authenticate, review reports, and advance their workflow. The graph follows the documented API entry points into controllers and services, with persistence, privacy checks, and on-read AI triage as supporting layers. Source excerpts do not show every route or startup detail; documented capabilities are retained, while uncertain connections are omitted.

Main entry points: [`src/routes/moderator.routes.ts`](https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/moderator.routes.ts) (Moderator routes), [`src/routes/report.routes.ts`](https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/report.routes.ts) (Report routes), [`src/services/report.service.ts`](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/report.service.ts) (Report operations), [`src/app.ts`](https://github.com/souryaneelpal/whistledrop/blob/main/src/app.ts) (App setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["App setup<br/>[app.ts]"]
  node_report_routes["Report routes<br/>[report.routes.ts]"]
  node_mod_routes["Moderator routes"]
  node_docs["API docs<br/>[docs.routes.ts]"]
  node_validation["Request validation<br/>[validate.ts]"]
  node_rate_limit["Rate limits<br/>[rateLimit.ts]"]
  node_errors["Error responses<br/>[errorHandler.ts]"]
end

subgraph group_reporting["Anonymous reporting"]
  node_report_controller["Report handling"]
  node_case_codes["Case codes"]
  node_report_service["Report operations<br/>[report.service.ts]"]
end

subgraph group_moderation["Moderator workflow"]
  node_auth["Moderator auth<br/>[auth.ts]"]
  node_moderator_controller["Moderator handling"]
  node_moderator_service["Login and tokens"]
end

subgraph group_intelligence["Privacy and triage"]
  node_leak_check["Identity leak check"]
  node_triage["Category triage<br/>[triage.service.ts]"]
  node_embedding["Text embeddings"]
end

subgraph group_persistence["Persistence and domain"]
  node_workflow["Status workflow<br/>[statusWorkflow.ts]"]
  node_database[("Application database<br/>[schema.prisma]")]
end

node_reporter(("Reporter"))
node_moderator(("Moderator"))

node_server -->|"starts"| node_app
node_app -->|"mounts routes"| node_report_routes
node_app -->|"mounts docs"| node_docs
node_reporter -.->|"submits and tracks"| node_report_routes
node_moderator -.->|"logs in and reviews"| node_mod_routes
node_report_routes -->|"validates requests"| node_validation
node_report_routes -->|"limits requests"| node_rate_limit
node_report_routes -->|"dispatches"| node_report_controller
node_mod_routes -->|"validates requests"| node_validation
node_mod_routes -->|"limits login"| node_rate_limit
node_mod_routes -->|"guards routes"| node_auth
node_mod_routes -->|"dispatches"| node_moderator_controller
node_report_controller -->|"creates and finds"| node_report_service
node_report_controller -->|"checks text"| node_leak_check
node_report_service -->|"generates and hashes"| node_case_codes
node_report_service -->|"reads and writes"| node_database
node_report_service -->|"checks transitions"| node_workflow
node_moderator_controller -->|"authenticates"| node_moderator_service
node_moderator_controller -->|"lists and updates"| node_report_service
node_moderator_controller -->|"requests suggestions"| node_triage
node_auth -->|"verifies tokens"| node_moderator_service
node_moderator_service -->|"reads moderators"| node_database
node_triage -->|"loads and embeds"| node_embedding
node_app -->|"handles errors"| node_errors

click node_server "https://github.com/souryaneelpal/whistledrop/blob/main/src/server.ts"
click node_app "https://github.com/souryaneelpal/whistledrop/blob/main/src/app.ts"
click node_report_routes "https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/report.routes.ts"
click node_mod_routes "https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/moderator.routes.ts"
click node_docs "https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/docs.routes.ts"
click node_validation "https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/validate.ts"
click node_rate_limit "https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/rateLimit.ts"
click node_auth "https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/auth.ts"
click node_report_controller "https://github.com/souryaneelpal/whistledrop/blob/main/src/controllers/report.controller.ts"
click node_case_codes "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/caseCode.service.ts"
click node_leak_check "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/leakCheck.service.ts"
click node_moderator_controller "https://github.com/souryaneelpal/whistledrop/blob/main/src/controllers/moderator.controller.ts"
click node_moderator_service "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/moderator.service.ts"
click node_report_service "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/report.service.ts"
click node_workflow "https://github.com/souryaneelpal/whistledrop/blob/main/src/domain/statusWorkflow.ts"
click node_triage "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/triage.service.ts"
click node_embedding "https://github.com/souryaneelpal/whistledrop/blob/main/src/services/embedding.service.ts"
click node_database "https://github.com/souryaneelpal/whistledrop/blob/main/prisma/schema.prisma"
click node_errors "https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/errorHandler.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_server,node_app,node_report_routes,node_mod_routes,node_docs,node_validation,node_rate_limit,node_errors toneBlue
class node_report_controller,node_case_codes,node_report_service toneAmber
class node_auth,node_moderator_controller,node_moderator_service toneMint
class node_leak_check,node_triage,node_embedding toneRose
class node_workflow,node_database,node_reporter,node_moderator toneIndigo
```

## Components

### API and access

- [HTTP server](https://github.com/souryaneelpal/whistledrop/blob/main/src/server.ts): `src/server.ts`
- [App setup](https://github.com/souryaneelpal/whistledrop/blob/main/src/app.ts): `src/app.ts`
- [Report routes](https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/report.routes.ts): `src/routes/report.routes.ts`
- [Moderator routes](https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/moderator.routes.ts): `src/routes/moderator.routes.ts`
- [API docs](https://github.com/souryaneelpal/whistledrop/blob/main/src/routes/docs.routes.ts): `src/routes/docs.routes.ts`
- [Request validation](https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/validate.ts): `src/middleware/validate.ts`
- [Rate limits](https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/rateLimit.ts): `src/middleware/rateLimit.ts`
- [Error responses](https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/errorHandler.ts): `src/middleware/errorHandler.ts`

### Anonymous reporting

- [Report handling](https://github.com/souryaneelpal/whistledrop/blob/main/src/controllers/report.controller.ts): `src/controllers/report.controller.ts`
- [Case codes](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/caseCode.service.ts): `src/services/caseCode.service.ts`
- [Report operations](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/report.service.ts): `src/services/report.service.ts`

### Moderator workflow

- [Moderator auth](https://github.com/souryaneelpal/whistledrop/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [Moderator handling](https://github.com/souryaneelpal/whistledrop/blob/main/src/controllers/moderator.controller.ts): `src/controllers/moderator.controller.ts`
- [Login and tokens](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/moderator.service.ts): `src/services/moderator.service.ts`

### Privacy and triage

- [Identity leak check](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/leakCheck.service.ts): `src/services/leakCheck.service.ts`
- [Category triage](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/triage.service.ts): `src/services/triage.service.ts`
- [Text embeddings](https://github.com/souryaneelpal/whistledrop/blob/main/src/services/embedding.service.ts): `src/services/embedding.service.ts`

### Persistence and domain

- [Status workflow](https://github.com/souryaneelpal/whistledrop/blob/main/src/domain/statusWorkflow.ts): `src/domain/statusWorkflow.ts`
- [Application database](https://github.com/souryaneelpal/whistledrop/blob/main/prisma/schema.prisma): `prisma/schema.prisma`

### Other components

- **Reporter**
- **Moderator**

## Connections

- HTTP server → App setup: starts (evidence: `src/server.ts`)
- App setup → Report routes: mounts routes (evidence: `src/app.ts`)
- App setup → API docs: mounts docs (evidence: `src/app.ts`)
- Reporter → Report routes: submits and tracks (evidence: `README.md`)
- Moderator → Moderator routes: logs in and reviews (evidence: `README.md`)
- Report routes → Request validation: validates requests (evidence: `src/routes/report.routes.ts`)
- Report routes → Rate limits: limits requests (evidence: `src/routes/report.routes.ts`)
- Report routes → Report handling: dispatches (evidence: `src/routes/report.routes.ts`)
- Moderator routes → Request validation: validates requests (evidence: `src/routes/moderator.routes.ts`)
- Moderator routes → Rate limits: limits login (evidence: `src/routes/moderator.routes.ts`)
- Moderator routes → Moderator auth: guards routes (evidence: `src/routes/moderator.routes.ts`)
- Moderator routes → Moderator handling: dispatches (evidence: `src/routes/moderator.routes.ts`)
- Report handling → Report operations: creates and finds (evidence: `src/controllers/report.controller.ts`)
- Report handling → Identity leak check: checks text (evidence: `src/controllers/report.controller.ts`)
- Report operations → Case codes: generates and hashes (evidence: `src/services/report.service.ts`)
- Report operations → Application database: reads and writes (evidence: `src/services/report.service.ts`)
- Report operations → Status workflow: checks transitions (evidence: `src/services/report.service.ts`)
- Moderator handling → Login and tokens: authenticates (evidence: `src/controllers/moderator.controller.ts`)
- Moderator handling → Report operations: lists and updates (evidence: `src/controllers/moderator.controller.ts`)
- Moderator handling → Category triage: requests suggestions (evidence: `src/controllers/moderator.controller.ts`)
- Moderator auth → Login and tokens: verifies tokens (evidence: `src/middleware/auth.ts`)
- Login and tokens → Application database: reads moderators (evidence: `src/services/moderator.service.ts`)
- Category triage → Text embeddings: loads and embeds (evidence: `src/services/triage.service.ts`)
- App setup → Error responses: handles errors (evidence: `src/app.ts`)
