# haixinnn05/news-next-door architecture

> Architecture diagram of the GitHub repository haixinnn05/news-next-door, 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/haixinnn05/news-next-door
- Repository: https://github.com/haixinnn05/news-next-door

## Overview

News Next Door turns civic planning documents and application updates into source-backed proposal pages, audio briefings, and text reminders. The core proposal workflow is document import, structured extraction with quote validation, team review and publication, then resident discovery and following. Separate branches cover live NYC Planning applications, city news, location search, and resident accounts. The README documents several integrations and capabilities not fully sampled; those links are shown where documented, while uncertain internal wiring is omitted.

Main entry points: [`server/http/app.ts`](https://github.com/haixinnn05/news-next-door/blob/main/server/http/app.ts) (HTTP API), [`server/services/extraction.ts`](https://github.com/haixinnn05/news-next-door/blob/main/server/services/extraction.ts) (Draft extraction), [`server/services/proposals.ts`](https://github.com/haixinnn05/news-next-door/blob/main/server/services/proposals.ts) (Review and publish), [`server/main.ts`](https://github.com/haixinnn05/news-next-door/blob/main/server/main.ts) (Process and workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Resident and team web"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_residentpages["Resident pages"]
  node_admin["Team console"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_civic["Proposal publishing"]
  node_documents["Document import<br/>[documents.ts]"]
  node_extract["Draft extraction<br/>[extraction.ts]"]
  node_reviewpublish["Review and publish<br/>[proposals.ts]"]
  node_addresses["Address coverage<br/>[addresses.ts]"]
  node_location["Location lookup<br/>[locate.ts]"]
  node_boundary["District boundaries<br/>[boundary.ts]"]
end

subgraph group_engagement["Briefings and messaging"]
  node_appbriefings["Application briefings<br/>[appBriefings.ts]"]
  node_citynews["City briefings<br/>[cityBriefings.ts]"]
  node_audio["Audio generation<br/>[audio.ts]"]
  node_subscriptions["Text subscriptions<br/>[subscriptions.ts]"]
  node_notifications["Reminder delivery<br/>[notifications.ts]"]
end

subgraph group_platform["Server platform"]
  node_http["HTTP API<br/>[app.ts]"]
  node_db[("SQLite state<br/>[db.ts]")]
  node_accounts["Resident accounts<br/>[account.ts]"]
  node_servermain["Process and workers<br/>[main.ts]"]
end

node_resident(("Resident"))
node_team(("Review team"))
node_grok{{"Grok"}}
node_nyt{{"New York Times"}}
node_elevenlabs{{"ElevenLabs"}}
node_photon{{"Photon iMessage"}}

node_resident -->|"browses"| node_webapp
node_team -->|"reviews drafts"| node_admin
node_webapp -->|"routes to"| node_residentpages
node_webapp -->|"routes to"| node_admin
node_residentpages -->|"requests data"| node_webapi
node_admin -->|"requests data"| node_webapi
node_webapi -->|"calls"| node_http
node_http -->|"imports document"| node_documents
node_http -->|"extracts document"| node_extract
node_extract -->|"reads pages"| node_documents
node_extract -->|"requests draft"| node_grok
node_team -->|"approves publication"| node_reviewpublish
node_reviewpublish -->|"validates draft"| node_extract
node_http -->|"serves proposals"| node_reviewpublish
node_reviewpublish -->|"matches locations"| node_addresses
node_http -->|"looks up places"| node_location
node_http -->|"loads boundary"| node_boundary
node_http -->|"loads saved proposals"| node_accounts
node_http -->|"handles inbound texts"| node_subscriptions
node_servermain -->|"starts server"| node_http
node_servermain -->|"runs worker"| node_notifications
node_servermain -->|"starts service"| node_appbriefings
node_appbriefings -->|"generates audio"| node_audio
node_appbriefings -->|"generates versions"| node_grok
node_citynews -->|"gets headlines"| node_nyt
node_audio -->|"narrates and dubs"| node_elevenlabs
node_subscriptions -->|"schedules messages"| node_notifications
node_notifications -->|"sends messages"| node_photon
node_documents -.->|"stores records"| node_db
node_extract -.->|"stores drafts"| node_db
node_reviewpublish -.->|"stores proposals"| node_db

click node_webapp "https://github.com/haixinnn05/news-next-door/blob/main/web/src/App.tsx"
click node_residentpages "https://github.com/haixinnn05/news-next-door/tree/main/web/src/pages"
click node_admin "https://github.com/haixinnn05/news-next-door/tree/main/web/src/admin"
click node_webapi "https://github.com/haixinnn05/news-next-door/blob/main/web/src/lib/api.ts"
click node_http "https://github.com/haixinnn05/news-next-door/blob/main/server/http/app.ts"
click node_documents "https://github.com/haixinnn05/news-next-door/blob/main/server/services/documents.ts"
click node_extract "https://github.com/haixinnn05/news-next-door/blob/main/server/services/extraction.ts"
click node_reviewpublish "https://github.com/haixinnn05/news-next-door/blob/main/server/services/proposals.ts"
click node_db "https://github.com/haixinnn05/news-next-door/blob/main/server/db.ts"
click node_addresses "https://github.com/haixinnn05/news-next-door/blob/main/server/lib/addresses.ts"
click node_location "https://github.com/haixinnn05/news-next-door/blob/main/server/services/locate.ts"
click node_boundary "https://github.com/haixinnn05/news-next-door/blob/main/server/services/boundary.ts"
click node_appbriefings "https://github.com/haixinnn05/news-next-door/blob/main/server/services/appBriefings.ts"
click node_citynews "https://github.com/haixinnn05/news-next-door/blob/main/server/services/cityBriefings.ts"
click node_audio "https://github.com/haixinnn05/news-next-door/blob/main/server/services/audio.ts"
click node_subscriptions "https://github.com/haixinnn05/news-next-door/blob/main/server/services/subscriptions.ts"
click node_notifications "https://github.com/haixinnn05/news-next-door/blob/main/server/services/notifications.ts"
click node_accounts "https://github.com/haixinnn05/news-next-door/blob/main/server/services/account.ts"
click node_servermain "https://github.com/haixinnn05/news-next-door/blob/main/server/main.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_webapp,node_residentpages,node_admin,node_webapi,node_team toneBlue
class node_documents,node_extract,node_reviewpublish,node_addresses,node_location,node_boundary toneAmber
class node_appbriefings,node_citynews,node_audio,node_subscriptions,node_notifications toneMint
class node_http,node_db,node_accounts,node_servermain toneRose
class node_resident,node_grok,node_nyt,node_elevenlabs,node_photon toneIndigo
```

## Components

### Resident and team web

- [Web app routes](https://github.com/haixinnn05/news-next-door/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Resident pages](https://github.com/haixinnn05/news-next-door/tree/main/web/src/pages): `web/src/pages`
- [Team console](https://github.com/haixinnn05/news-next-door/tree/main/web/src/admin): `web/src/admin`
- [Web API client](https://github.com/haixinnn05/news-next-door/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`

### Proposal publishing

- [Document import](https://github.com/haixinnn05/news-next-door/blob/main/server/services/documents.ts): `server/services/documents.ts`
- [Draft extraction](https://github.com/haixinnn05/news-next-door/blob/main/server/services/extraction.ts): `server/services/extraction.ts`
- [Review and publish](https://github.com/haixinnn05/news-next-door/blob/main/server/services/proposals.ts): `server/services/proposals.ts`
- [Address coverage](https://github.com/haixinnn05/news-next-door/blob/main/server/lib/addresses.ts): `server/lib/addresses.ts`
- [Location lookup](https://github.com/haixinnn05/news-next-door/blob/main/server/services/locate.ts): `server/services/locate.ts`
- [District boundaries](https://github.com/haixinnn05/news-next-door/blob/main/server/services/boundary.ts): `server/services/boundary.ts`

### Briefings and messaging

- [Application briefings](https://github.com/haixinnn05/news-next-door/blob/main/server/services/appBriefings.ts): `server/services/appBriefings.ts`
- [City briefings](https://github.com/haixinnn05/news-next-door/blob/main/server/services/cityBriefings.ts): `server/services/cityBriefings.ts`
- [Audio generation](https://github.com/haixinnn05/news-next-door/blob/main/server/services/audio.ts): `server/services/audio.ts`
- [Text subscriptions](https://github.com/haixinnn05/news-next-door/blob/main/server/services/subscriptions.ts): `server/services/subscriptions.ts`
- [Reminder delivery](https://github.com/haixinnn05/news-next-door/blob/main/server/services/notifications.ts): `server/services/notifications.ts`

### Server platform

- [HTTP API](https://github.com/haixinnn05/news-next-door/blob/main/server/http/app.ts): `server/http/app.ts`
- [SQLite state](https://github.com/haixinnn05/news-next-door/blob/main/server/db.ts): `server/db.ts`
- [Resident accounts](https://github.com/haixinnn05/news-next-door/blob/main/server/services/account.ts): `server/services/account.ts`
- [Process and workers](https://github.com/haixinnn05/news-next-door/blob/main/server/main.ts): `server/main.ts`

### Other components

- **Resident**
- **Review team**
- **Grok**
- **New York Times**
- **ElevenLabs**
- **Photon iMessage**

## Connections

- Resident → Web app routes: browses
- Review team → Team console: reviews drafts
- Web app routes → Resident pages: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Team console: routes to (evidence: `web/src/App.tsx`)
- Resident pages → Web API client: requests data (evidence: `web/src/pages/Proposal.tsx`)
- Team console → Web API client: requests data (evidence: `web/src/admin/ReviewPage.tsx`)
- Web API client → HTTP API: calls
- HTTP API → Document import: imports document (evidence: `server/http/app.ts`)
- HTTP API → Draft extraction: extracts document (evidence: `server/http/app.ts`)
- Draft extraction → Document import: reads pages (evidence: `server/services/extraction.ts`)
- Draft extraction → Grok: requests draft (evidence: `server/services/extraction.ts`)
- Review team → Review and publish: approves publication
- Review and publish → Draft extraction: validates draft (evidence: `server/services/proposals.ts`)
- HTTP API → Review and publish: serves proposals (evidence: `server/http/app.ts`)
- Review and publish → Address coverage: matches locations (evidence: `server/services/proposals.ts`)
- HTTP API → Location lookup: looks up places (evidence: `server/http/app.ts`)
- HTTP API → District boundaries: loads boundary (evidence: `server/http/app.ts`)
- HTTP API → Resident accounts: loads saved proposals (evidence: `server/http/app.ts`)
- HTTP API → Text subscriptions: handles inbound texts (evidence: `server/http/app.ts`)
- Process and workers → HTTP API: starts server (evidence: `server/main.ts`)
- Process and workers → Reminder delivery: runs worker (evidence: `server/main.ts`)
- Process and workers → Application briefings: starts service (evidence: `server/main.ts`)
- Application briefings → Audio generation: generates audio (evidence: `server/services/appBriefings.ts`)
- Application briefings → Grok: generates versions (evidence: `server/services/appBriefings.ts`)
- City briefings → New York Times: gets headlines
- Audio generation → ElevenLabs: narrates and dubs
- Text subscriptions → Reminder delivery: schedules messages (evidence: `server/services/subscriptions.ts`)
- Reminder delivery → Photon iMessage: sends messages
- Document import → SQLite state: stores records (evidence: `server/services/documents.ts`)
- Draft extraction → SQLite state: stores drafts (evidence: `server/services/extraction.ts`)
- Review and publish → SQLite state: stores proposals (evidence: `server/services/proposals.ts`)
