# lightningbolts/state-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/lightningbolts/state-pulse
- Repository: https://github.com/lightningbolts/state-pulse
- Video tour (about a minute): https://gitdiagram.com/lightningbolts/state-pulse/video

## Overview

StatePulse is a civic-information web application that aggregates legislation and representative data, makes it easier to understand, and supports civic action and personal tracking. The principal user journey is to find legislation, review summaries and related activity, then bookmark or follow it or engage through community and representative-contact tools. The README documents the wider feature set; sampled route code confirms MongoDB-backed representative and dashboard data access, while wiring among many unsampled pages and services is not asserted.

Main entry points: [`src/app/(main)/page.tsx`](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/page.tsx) (StatePulse web app), [`src/app/(main)/legislation/page.tsx`](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/legislation/page.tsx) (Legislation pages), [`src/app/(main)/representatives/page.tsx`](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/representatives/page.tsx) (Representative pages), [`src/app/(main)/dashboard/page.tsx`](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/dashboard/page.tsx) (Personal dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Civic experience"]
  node_web["StatePulse web app<br/>[page.tsx]"]
  node_billpages["Legislation pages<br/>[page.tsx]"]
  node_representativepages["Representative pages<br/>[page.tsx]"]
  node_communitypages["Community pages<br/>[page.tsx]"]
  node_dashboardpage["Personal dashboard<br/>[page.tsx]"]
end

subgraph group_legislation["Legislation insight"]
  node_legislationapi["Legislation API<br/>[route.ts]"]
  node_legislationservice["Legislation services"]
  node_summaries["AI summaries"]
  node_relatedbills["Related bills"]
  node_predictions["Vote predictions"]
end

subgraph group_civic["Civic tools"]
  node_representativeapi["Representative API<br/>[route.ts]"]
  node_civiclookup["Civic lookup<br/>[route.ts]"]
  node_message["Message generator<br/>[route.ts]"]
  node_policytracker["Policy tracking<br/>[route.ts]"]
  node_postsapi["Community API<br/>[route.ts]"]
  node_bookmarks["Bookmarks API<br/>[route.ts]"]
end

subgraph group_platform["Application services"]
  node_database[("MongoDB<br/>[mongodb.ts]")]
  node_auth["Clerk authentication<br/>[middleware.ts]"]
  node_statevotes["State vote ingestion<br/>[orchestrator.ts]"]
end

node_citizen(("Citizen"))

node_citizen -->|"uses"| node_web
node_web -->|"browses"| node_billpages
node_web -->|"finds officials"| node_representativepages
node_web -->|"joins discussion"| node_communitypages
node_web -->|"tracks activity"| node_dashboardpage
node_billpages -->|"requests bills"| node_legislationapi
node_legislationapi -->|"delegates"| node_legislationservice
node_legislationservice -->|"reads data"| node_database
node_billpages -->|"requests summaries"| node_summaries
node_billpages -->|"explores links"| node_relatedbills
node_billpages -->|"views predictions"| node_predictions
node_representativepages -->|"requests officials"| node_representativeapi
node_representativeapi -->|"reads and writes"| node_database
node_representativepages -->|"locates district"| node_civiclookup
node_representativepages -->|"creates message"| node_message
node_dashboardpage -->|"tracks policies"| node_policytracker
node_dashboardpage -->|"manages saved bills"| node_bookmarks
node_communitypages -->|"loads posts"| node_postsapi
node_postsapi -->|"stores content"| node_database
node_dashboardpage -.->|"requires account"| node_auth
node_statevotes -->|"stores vote records"| node_database

click node_web "https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/page.tsx"
click node_billpages "https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/legislation/page.tsx"
click node_representativepages "https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/representatives/page.tsx"
click node_communitypages "https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/posts/page.tsx"
click node_dashboardpage "https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/dashboard/page.tsx"
click node_legislationapi "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/legislation/route.ts"
click node_legislationservice "https://github.com/lightningbolts/state-pulse/blob/main/src/services/legislationService.ts"
click node_summaries "https://github.com/lightningbolts/state-pulse/blob/main/src/ai/flows/summarize-legislation.ts"
click node_relatedbills "https://github.com/lightningbolts/state-pulse/blob/main/src/services/relatedBillsService.ts"
click node_predictions "https://github.com/lightningbolts/state-pulse/blob/main/src/services/votingPredictionService.ts"
click node_representativeapi "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/representatives/route.ts"
click node_civiclookup "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/civic/route.ts"
click node_message "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/generate-message/route.ts"
click node_policytracker "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/policy-tracker/route.ts"
click node_postsapi "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/posts/route.ts"
click node_bookmarks "https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/bookmarks/route.ts"
click node_database "https://github.com/lightningbolts/state-pulse/blob/main/src/lib/mongodb.ts"
click node_auth "https://github.com/lightningbolts/state-pulse/blob/main/src/middleware.ts"
click node_statevotes "https://github.com/lightningbolts/state-pulse/blob/main/src/scrapers/stateVotes/orchestrator.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_web,node_billpages,node_representativepages,node_communitypages,node_dashboardpage toneBlue
class node_legislationapi,node_legislationservice,node_summaries,node_relatedbills,node_predictions toneAmber
class node_representativeapi,node_civiclookup,node_message,node_policytracker,node_postsapi,node_bookmarks toneMint
class node_database,node_auth,node_statevotes toneRose
class node_citizen toneIndigo
```

## Components

### Civic experience

- [StatePulse web app](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/page.tsx): `src/app/(main)/page.tsx`
- [Legislation pages](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/legislation/page.tsx): `src/app/(main)/legislation/page.tsx`
- [Representative pages](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/representatives/page.tsx): `src/app/(main)/representatives/page.tsx`
- [Community pages](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/posts/page.tsx): `src/app/(main)/posts/page.tsx`
- [Personal dashboard](https://github.com/lightningbolts/state-pulse/blob/main/src/app/(main)/dashboard/page.tsx): `src/app/(main)/dashboard/page.tsx`

### Legislation insight

- [Legislation API](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/legislation/route.ts): `src/app/api/legislation/route.ts`
- [Legislation services](https://github.com/lightningbolts/state-pulse/blob/main/src/services/legislationService.ts): `src/services/legislationService.ts`
- [AI summaries](https://github.com/lightningbolts/state-pulse/blob/main/src/ai/flows/summarize-legislation.ts): `src/ai/flows/summarize-legislation.ts`
- [Related bills](https://github.com/lightningbolts/state-pulse/blob/main/src/services/relatedBillsService.ts): `src/services/relatedBillsService.ts`
- [Vote predictions](https://github.com/lightningbolts/state-pulse/blob/main/src/services/votingPredictionService.ts): `src/services/votingPredictionService.ts`

### Civic tools

- [Representative API](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/representatives/route.ts): `src/app/api/representatives/route.ts`
- [Civic lookup](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/civic/route.ts): `src/app/api/civic/route.ts`
- [Message generator](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/generate-message/route.ts): `src/app/api/generate-message/route.ts`
- [Policy tracking](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/policy-tracker/route.ts): `src/app/api/policy-tracker/route.ts`
- [Community API](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/posts/route.ts): `src/app/api/posts/route.ts`
- [Bookmarks API](https://github.com/lightningbolts/state-pulse/blob/main/src/app/api/bookmarks/route.ts): `src/app/api/bookmarks/route.ts`

### Application services

- [MongoDB](https://github.com/lightningbolts/state-pulse/blob/main/src/lib/mongodb.ts): `src/lib/mongodb.ts`
- [Clerk authentication](https://github.com/lightningbolts/state-pulse/blob/main/src/middleware.ts): `src/middleware.ts`
- [State vote ingestion](https://github.com/lightningbolts/state-pulse/blob/main/src/scrapers/stateVotes/orchestrator.ts): `src/scrapers/stateVotes/orchestrator.ts`

### Other components

- **Citizen**

## Connections

- Citizen → StatePulse web app: uses
- StatePulse web app → Legislation pages: browses
- StatePulse web app → Representative pages: finds officials
- StatePulse web app → Community pages: joins discussion
- StatePulse web app → Personal dashboard: tracks activity
- Legislation pages → Legislation API: requests bills
- Legislation API → Legislation services: delegates
- Legislation services → MongoDB: reads data
- Legislation pages → AI summaries: requests summaries
- Legislation pages → Related bills: explores links
- Legislation pages → Vote predictions: views predictions
- Representative pages → Representative API: requests officials
- Representative API → MongoDB: reads and writes
- Representative pages → Civic lookup: locates district
- Representative pages → Message generator: creates message
- Personal dashboard → Policy tracking: tracks policies
- Personal dashboard → Bookmarks API: manages saved bills
- Community pages → Community API: loads posts
- Community API → MongoDB: stores content
- Personal dashboard → Clerk authentication: requires account
- State vote ingestion → MongoDB: stores vote records