# alexrosario/delegatorbackend architecture

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

- Interactive diagram: https://gitdiagram.com/alexrosario/delegatorbackend
- Repository: https://github.com/alexrosario/delegatorbackend

## Overview

Delegator is a civic-engagement backend: constituents register and verify their identity/address, browse legislation, inspect representative and recorded-vote information, and participate through votes and bill discussions. A separate scheduled ingestion workflow refreshes Congress bills, members, and roll calls, then supports delegation reconciliation. The graph follows the server’s mounted routes and sampled worker/ingestion calls; unsampled major routes are represented by their exact source paths, but their internal dependencies are not inferred.

Main entry points: [`server.ts`](https://github.com/alexrosario/delegatorbackend/blob/main/server.ts) (HTTP server), [`prisma/prisma.ts`](https://github.com/alexrosario/delegatorbackend/blob/main/prisma/prisma.ts) (Application database), [`src/router/auth.router.ts`](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/auth.router.ts) (Account and auth), [`src/utils/auth-utils.ts`](https://github.com/alexrosario/delegatorbackend/blob/main/src/utils/auth-utils.ts) (Session utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_server["HTTP server<br/>[server.ts]"]
  node_auth["Account and auth<br/>[auth.router.ts]"]
  node_authutils["Session utilities<br/>[auth-utils.ts]"]
  node_schemas["Request schemas<br/>[zodSchema.ts]"]
  node_contacts["Contact messages<br/>[contact.router.ts]"]
end

subgraph group_civic["Legislative engagement"]
  node_bills["Bill discovery<br/>[bill.router.ts]"]
  node_votes["Constituent votes<br/>[vote.router.ts]"]
  node_reps["Representative data<br/>[rep.router.ts]"]
  node_location["Address lookup<br/>[location.router.ts]"]
  node_fivecalls["Advocacy lookup"]
  node_translation["Bill translation"]
end

subgraph group_ingest["Legislative data ingestion"]
  node_billworker["Daily bill job<br/>[dailyBillIngest.ts]"]
  node_memberworker["Daily member job"]
  node_reconcile["Delegation reconcile"]
  node_runlog["Ingestion tracking<br/>[runIngestion.ts]"]
  node_billbatch["Bill batch ingest"]
  node_billitem["Bill ingestion<br/>[ingestBill.ts]"]
  node_billnormalize["Bill normalization<br/>[normalizeBill.ts]"]
  node_billupsert["Bill persistence<br/>[upsertBill.ts]"]
  node_memberbatch["Member batch ingest"]
  node_rollcalls["Roll-call persistence<br/>[upsertRollCalls.ts]"]
end

subgraph group_services["External data services"]
  node_congress["Congress.gov API"]
  node_district["District resolver"]
  node_donors["Donor summaries<br/>[donorService.ts]"]
  node_fec["FEC data client<br/>[fecClient.ts]"]
  node_fecmap["FEC candidate mapping<br/>[fecMapping.ts]"]
  node_email["Email provider<br/>[emailProvider.ts]"]
end

node_constituent(("Constituent"))
node_db[("Application database<br/>[prisma.ts]")]

node_constituent -->|"requests"| node_server
node_server -->|"mounts"| node_auth
node_server -->|"mounts"| node_bills
node_server -->|"mounts"| node_votes
node_server -->|"mounts"| node_reps
node_server -->|"mounts"| node_contacts
node_server -->|"mounts"| node_location
node_server -->|"mounts"| node_fivecalls
node_server -->|"mounts"| node_translation
node_auth -->|"reads and writes"| node_db
node_auth -->|"resolves address"| node_district
node_auth -->|"sends verification"| node_email
node_auth -->|"validates input"| node_schemas
node_auth -->|"creates session"| node_authutils
node_bills -->|"queries corpus"| node_db
node_bills -->|"fetches missing bill"| node_congress
node_bills -->|"reads session"| node_authutils
node_bills -->|"validates comments"| node_schemas
node_votes -->|"records votes"| node_db
node_votes -->|"validates votes"| node_schemas
node_votes -->|"checks session"| node_authutils
node_reps -->|"reads representatives"| node_db
node_reps -->|"loads donor summary"| node_donors
node_reps -->|"checks session"| node_authutils
node_location -->|"resolves district"| node_district
node_contacts -->|"stores messages"| node_db
node_contacts -->|"checks session"| node_authutils
node_fivecalls -->|"checks session"| node_authutils
node_translation -->|"reads stored text"| node_db
node_billworker -->|"tracks run"| node_runlog
node_billworker -->|"ingests batch"| node_billbatch
node_memberworker -->|"tracks run"| node_runlog
node_memberworker -->|"ingests members"| node_memberbatch
node_server -->|"schedules job"| node_billworker
node_server -->|"schedules job"| node_memberworker
node_server -->|"runs after refresh"| node_reconcile
node_runlog -->|"records run state"| node_db
node_billbatch -->|"lists bills"| node_congress
node_billbatch -->|"ingests each bill"| node_billitem
node_billitem -->|"fetches bill resources"| node_congress
node_billitem -->|"persists bill"| node_billupsert
node_billitem -->|"stores recorded votes"| node_rollcalls
node_billitem -->|"commits transaction"| node_db
node_billupsert -->|"normalizes record"| node_billnormalize
node_memberbatch -->|"fetches members"| node_congress
node_memberbatch -.->|"persists members"| node_db
node_reconcile -->|"resolves delegations"| node_district
node_reconcile -->|"updates mappings"| node_db

click node_server "https://github.com/alexrosario/delegatorbackend/blob/main/server.ts"
click node_auth "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/auth.router.ts"
click node_authutils "https://github.com/alexrosario/delegatorbackend/blob/main/src/utils/auth-utils.ts"
click node_schemas "https://github.com/alexrosario/delegatorbackend/blob/main/src/zodSchema.ts"
click node_contacts "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/contact.router.ts"
click node_bills "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/bill.router.ts"
click node_votes "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/vote.router.ts"
click node_reps "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/rep.router.ts"
click node_location "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/location.router.ts"
click node_fivecalls "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/external/fivecalls.router.ts"
click node_translation "https://github.com/alexrosario/delegatorbackend/blob/main/src/router/external/translate.router.ts"
click node_db "https://github.com/alexrosario/delegatorbackend/blob/main/prisma/prisma.ts"
click node_billworker "https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/dailyBillIngest.ts"
click node_memberworker "https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/dailyMemberIngest.ts"
click node_reconcile "https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/reconcileDelegations.ts"
click node_runlog "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/runIngestion.ts"
click node_billbatch "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestBillsBatch.ts"
click node_billitem "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestBill.ts"
click node_billnormalize "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/normalizeBill.ts"
click node_billupsert "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/upsertBill.ts"
click node_memberbatch "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestMembersBatch.ts"
click node_rollcalls "https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/upsertRollCalls.ts"
click node_congress "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/congressGovClient.ts"
click node_district "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/districtResolver.ts"
click node_donors "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/donorService.ts"
click node_fec "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/fecClient.ts"
click node_fecmap "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/fecMapping.ts"
click node_email "https://github.com/alexrosario/delegatorbackend/blob/main/src/services/emailProvider.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_auth,node_authutils,node_schemas,node_contacts toneBlue
class node_bills,node_votes,node_reps,node_location,node_fivecalls,node_translation,node_db toneAmber
class node_billworker,node_memberworker,node_reconcile,node_runlog,node_billbatch,node_billitem,node_billnormalize,node_billupsert,node_memberbatch,node_rollcalls toneMint
class node_congress,node_district,node_donors,node_fec,node_fecmap,node_email toneRose
class node_constituent toneIndigo
```

## Components

### API and identity

- [HTTP server](https://github.com/alexrosario/delegatorbackend/blob/main/server.ts): `server.ts`
- [Account and auth](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/auth.router.ts): `src/router/auth.router.ts`
- [Session utilities](https://github.com/alexrosario/delegatorbackend/blob/main/src/utils/auth-utils.ts): `src/utils/auth-utils.ts`
- [Request schemas](https://github.com/alexrosario/delegatorbackend/blob/main/src/zodSchema.ts): `src/zodSchema.ts`
- [Contact messages](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/contact.router.ts): `src/router/contact.router.ts`

### Legislative engagement

- [Bill discovery](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/bill.router.ts): `src/router/bill.router.ts`
- [Constituent votes](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/vote.router.ts): `src/router/vote.router.ts`
- [Representative data](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/rep.router.ts): `src/router/rep.router.ts`
- [Address lookup](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/location.router.ts): `src/router/location.router.ts`
- [Advocacy lookup](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/external/fivecalls.router.ts): `src/router/external/fivecalls.router.ts`
- [Bill translation](https://github.com/alexrosario/delegatorbackend/blob/main/src/router/external/translate.router.ts): `src/router/external/translate.router.ts`

### Legislative data ingestion

- [Daily bill job](https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/dailyBillIngest.ts): `src/workers/dailyBillIngest.ts`
- [Daily member job](https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/dailyMemberIngest.ts): `src/workers/dailyMemberIngest.ts`
- [Delegation reconcile](https://github.com/alexrosario/delegatorbackend/blob/main/src/workers/reconcileDelegations.ts): `src/workers/reconcileDelegations.ts`
- [Ingestion tracking](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/runIngestion.ts): `src/ingestion/runIngestion.ts`
- [Bill batch ingest](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestBillsBatch.ts): `src/ingestion/ingestBillsBatch.ts`
- [Bill ingestion](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestBill.ts): `src/ingestion/ingestBill.ts`
- [Bill normalization](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/normalizeBill.ts): `src/ingestion/normalizeBill.ts`
- [Bill persistence](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/upsertBill.ts): `src/ingestion/upsertBill.ts`
- [Member batch ingest](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/ingestMembersBatch.ts): `src/ingestion/ingestMembersBatch.ts`
- [Roll-call persistence](https://github.com/alexrosario/delegatorbackend/blob/main/src/ingestion/upsertRollCalls.ts): `src/ingestion/upsertRollCalls.ts`

### External data services

- [Congress.gov API](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/congressGovClient.ts): `src/services/congressGovClient.ts`
- [District resolver](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/districtResolver.ts): `src/services/districtResolver.ts`
- [Donor summaries](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/donorService.ts): `src/services/donorService.ts`
- [FEC data client](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/fecClient.ts): `src/services/fecClient.ts`
- [FEC candidate mapping](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/fecMapping.ts): `src/services/fecMapping.ts`
- [Email provider](https://github.com/alexrosario/delegatorbackend/blob/main/src/services/emailProvider.ts): `src/services/emailProvider.ts`

### Other components

- **Constituent**
- [Application database](https://github.com/alexrosario/delegatorbackend/blob/main/prisma/prisma.ts): `prisma/prisma.ts`

## Connections

- Constituent → HTTP server: requests (evidence: `server.ts`)
- HTTP server → Account and auth: mounts (evidence: `server.ts`)
- HTTP server → Bill discovery: mounts (evidence: `server.ts`)
- HTTP server → Constituent votes: mounts (evidence: `server.ts`)
- HTTP server → Representative data: mounts (evidence: `server.ts`)
- HTTP server → Contact messages: mounts (evidence: `server.ts`)
- HTTP server → Address lookup: mounts (evidence: `server.ts`)
- HTTP server → Advocacy lookup: mounts (evidence: `server.ts`)
- HTTP server → Bill translation: mounts (evidence: `server.ts`)
- Account and auth → Application database: reads and writes (evidence: `src/router/auth.router.ts`)
- Account and auth → District resolver: resolves address (evidence: `src/router/auth.router.ts`)
- Account and auth → Email provider: sends verification (evidence: `src/router/auth.router.ts`)
- Account and auth → Request schemas: validates input (evidence: `src/router/auth.router.ts`)
- Account and auth → Session utilities: creates session (evidence: `src/router/auth.router.ts`)
- Bill discovery → Application database: queries corpus (evidence: `src/router/bill.router.ts`)
- Bill discovery → Congress.gov API: fetches missing bill (evidence: `src/router/bill.router.ts`)
- Bill discovery → Session utilities: reads session (evidence: `src/router/bill.router.ts`)
- Bill discovery → Request schemas: validates comments (evidence: `src/router/bill.router.ts`)
- Constituent votes → Application database: records votes (evidence: `src/router/vote.router.ts`)
- Constituent votes → Request schemas: validates votes (evidence: `src/router/vote.router.ts`)
- Constituent votes → Session utilities: checks session (evidence: `src/router/vote.router.ts`)
- Representative data → Application database: reads representatives (evidence: `src/router/rep.router.ts`)
- Representative data → Donor summaries: loads donor summary (evidence: `src/router/rep.router.ts`)
- Representative data → Session utilities: checks session (evidence: `src/router/rep.router.ts`)
- Address lookup → District resolver: resolves district (evidence: `src/router/location.router.ts`)
- Contact messages → Application database: stores messages (evidence: `src/router/contact.router.ts`)
- Contact messages → Session utilities: checks session (evidence: `src/router/contact.router.ts`)
- Advocacy lookup → Session utilities: checks session (evidence: `src/router/external/fivecalls.router.ts`)
- Bill translation → Application database: reads stored text (evidence: `src/router/external/translate.router.ts`)
- Daily bill job → Ingestion tracking: tracks run (evidence: `src/workers/dailyBillIngest.ts`)
- Daily bill job → Bill batch ingest: ingests batch (evidence: `src/workers/dailyBillIngest.ts`)
- Daily member job → Ingestion tracking: tracks run (evidence: `src/workers/dailyMemberIngest.ts`)
- Daily member job → Member batch ingest: ingests members (evidence: `src/workers/dailyMemberIngest.ts`)
- HTTP server → Daily bill job: schedules job (evidence: `server.ts`)
- HTTP server → Daily member job: schedules job (evidence: `server.ts`)
- HTTP server → Delegation reconcile: runs after refresh (evidence: `server.ts`)
- Ingestion tracking → Application database: records run state (evidence: `src/ingestion/runIngestion.ts`)
- Bill batch ingest → Congress.gov API: lists bills (evidence: `src/ingestion/ingestBillsBatch.ts`)
- Bill batch ingest → Bill ingestion: ingests each bill (evidence: `src/ingestion/ingestBillsBatch.ts`)
- Bill ingestion → Congress.gov API: fetches bill resources (evidence: `src/ingestion/ingestBill.ts`)
- Bill ingestion → Bill persistence: persists bill (evidence: `src/ingestion/ingestBill.ts`)
- Bill ingestion → Roll-call persistence: stores recorded votes (evidence: `src/ingestion/ingestBill.ts`)
- Bill ingestion → Application database: commits transaction (evidence: `src/ingestion/ingestBill.ts`)
- Bill persistence → Bill normalization: normalizes record (evidence: `src/ingestion/upsertBill.ts`)
- Member batch ingest → Congress.gov API: fetches members (evidence: `src/ingestion/ingestMembersBatch.ts`)
- Member batch ingest → Application database: persists members
- Delegation reconcile → District resolver: resolves delegations (evidence: `src/workers/reconcileDelegations.ts`)
- Delegation reconcile → Application database: updates mappings (evidence: `src/workers/reconcileDelegations.ts`)