# woodysc8/media-list-builder architecture

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

- Interactive diagram: https://gitdiagram.com/woodysc8/media-list-builder
- Repository: https://github.com/woodysc8/media-list-builder

## Overview

Media List Builder is an internal application for maintaining a reporter directory and building client media lists from imported or manually entered coverage. Users enter through the browser UI; the server routes work to parsing, ingestion, persistence, reporting, Google Workspace synchronization/export, and optional reporter enrichment. The README documents the major workflows; some subsystem links below rely on its descriptions and the SOURCE INDEX rather than complete route excerpts.

Main entry points: [`src/server.ts`](https://github.com/woodysc8/media-list-builder/blob/main/src/server.ts) (Express API), [`src/enrichment.ts`](https://github.com/woodysc8/media-list-builder/blob/main/src/enrichment.ts) (Reporter enrichment), [`public/app.js`](https://github.com/woodysc8/media-list-builder/blob/main/public/app.js) (Builder UI), [`src/ingestion.ts`](https://github.com/woodysc8/media-list-builder/blob/main/src/ingestion.ts) (Coverage ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_browser["Builder UI<br/>[app.js]"]
  node_server["Express API<br/>[server.ts]"]
end

subgraph group_coverage["Coverage workflow"]
  node_parser["File parser<br/>[parser.ts]"]
  node_ingestion["Coverage ingestion<br/>[ingestion.ts]"]
  node_resolvers["Coverage resolution"]
  node_canonical["Canonical taxonomy<br/>[canonical-beats.js]"]
  node_projections["Coverage projections"]
end

subgraph group_directory["Directory and enrichment"]
  node_directory["Reporter directory"]
  node_preflight["Reporter diagnostics"]
  node_enrichment["Reporter enrichment<br/>[enrichment.ts]"]
  node_urlresolution["Article URL resolution<br/>[url-enrichment.ts]"]
end

subgraph group_integrations["Storage and integrations"]
  node_google["Google Workspace<br/>[google.ts]"]
  node_store[("Structured store<br/>[store.ts]")]
  node_persistent["Persistence adapter"]
  node_blob[("Vercel Blob")]
end

node_operator(("Operator"))
node_googleservices["Google Drive and Sheets"]
node_search["Search and AI providers"]

node_operator -->|"uses"| node_browser
node_browser -->|"calls API"| node_server
node_server -->|"parses imports"| node_parser
node_server -->|"ingests coverage"| node_ingestion
node_ingestion -->|"resolves fields"| node_resolvers
node_ingestion -->|"updates records"| node_store
node_server -->|"loads and saves"| node_store
node_server -->|"builds reports"| node_projections
node_browser -->|"filters by beats"| node_canonical
node_server -->|"loads directory"| node_directory
node_server -->|"runs diagnostics"| node_preflight
node_server -->|"manages proposals"| node_enrichment
node_enrichment -->|"resolves article URLs"| node_urlresolution
node_enrichment -->|"reads and writes state"| node_persistent
node_store -->|"reads and writes"| node_persistent
node_server -->|"routes Workspace operations"| node_google
node_google -->|"reads and updates"| node_googleservices
node_urlresolution -.->|"searches candidates"| node_search
node_enrichment -.->|"researches reporters"| node_search
node_persistent -.->|"persists production state"| node_blob

click node_browser "https://github.com/woodysc8/media-list-builder/blob/main/public/app.js"
click node_server "https://github.com/woodysc8/media-list-builder/blob/main/src/server.ts"
click node_parser "https://github.com/woodysc8/media-list-builder/blob/main/src/parser.ts"
click node_ingestion "https://github.com/woodysc8/media-list-builder/blob/main/src/ingestion.ts"
click node_resolvers "https://github.com/woodysc8/media-list-builder/blob/main/src/coverage-resolvers.ts"
click node_canonical "https://github.com/woodysc8/media-list-builder/blob/main/public/canonical-beats.js"
click node_projections "https://github.com/woodysc8/media-list-builder/blob/main/src/report-projections.ts"
click node_directory "https://github.com/woodysc8/media-list-builder/blob/main/src/reporter-directory-source.ts"
click node_preflight "https://github.com/woodysc8/media-list-builder/blob/main/src/reporter-preflight.ts"
click node_enrichment "https://github.com/woodysc8/media-list-builder/blob/main/src/enrichment.ts"
click node_urlresolution "https://github.com/woodysc8/media-list-builder/blob/main/src/url-enrichment.ts"
click node_google "https://github.com/woodysc8/media-list-builder/blob/main/src/google.ts"
click node_store "https://github.com/woodysc8/media-list-builder/blob/main/src/store.ts"
click node_persistent "https://github.com/woodysc8/media-list-builder/blob/main/src/persistent-files.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_browser,node_server toneBlue
class node_parser,node_ingestion,node_resolvers,node_canonical,node_projections toneAmber
class node_directory,node_preflight,node_enrichment,node_urlresolution toneMint
class node_google,node_store,node_persistent,node_blob toneRose
class node_operator,node_googleservices,node_search toneIndigo
```

## Components

### User experience

- [Builder UI](https://github.com/woodysc8/media-list-builder/blob/main/public/app.js): `public/app.js`
- [Express API](https://github.com/woodysc8/media-list-builder/blob/main/src/server.ts): `src/server.ts`

### Coverage workflow

- [File parser](https://github.com/woodysc8/media-list-builder/blob/main/src/parser.ts): `src/parser.ts`
- [Coverage ingestion](https://github.com/woodysc8/media-list-builder/blob/main/src/ingestion.ts): `src/ingestion.ts`
- [Coverage resolution](https://github.com/woodysc8/media-list-builder/blob/main/src/coverage-resolvers.ts): `src/coverage-resolvers.ts`
- [Canonical taxonomy](https://github.com/woodysc8/media-list-builder/blob/main/public/canonical-beats.js): `public/canonical-beats.js`
- [Coverage projections](https://github.com/woodysc8/media-list-builder/blob/main/src/report-projections.ts): `src/report-projections.ts`

### Directory and enrichment

- [Reporter directory](https://github.com/woodysc8/media-list-builder/blob/main/src/reporter-directory-source.ts): `src/reporter-directory-source.ts`
- [Reporter diagnostics](https://github.com/woodysc8/media-list-builder/blob/main/src/reporter-preflight.ts): `src/reporter-preflight.ts`
- [Reporter enrichment](https://github.com/woodysc8/media-list-builder/blob/main/src/enrichment.ts): `src/enrichment.ts`
- [Article URL resolution](https://github.com/woodysc8/media-list-builder/blob/main/src/url-enrichment.ts): `src/url-enrichment.ts`

### Storage and integrations

- [Google Workspace](https://github.com/woodysc8/media-list-builder/blob/main/src/google.ts): `src/google.ts`
- [Structured store](https://github.com/woodysc8/media-list-builder/blob/main/src/store.ts): `src/store.ts`
- [Persistence adapter](https://github.com/woodysc8/media-list-builder/blob/main/src/persistent-files.ts): `src/persistent-files.ts`
- **Vercel Blob**

### Other components

- **Operator**
- **Google Drive and Sheets**
- **Search and AI providers**

## Connections

- Operator → Builder UI: uses (evidence: `README.md`)
- Builder UI → Express API: calls API (evidence: `README.md`)
- Express API → File parser: parses imports (evidence: `src/server.ts`)
- Express API → Coverage ingestion: ingests coverage (evidence: `src/server.ts`)
- Coverage ingestion → Coverage resolution: resolves fields (evidence: `src/ingestion.ts`)
- Coverage ingestion → Structured store: updates records (evidence: `src/ingestion.ts`)
- Express API → Structured store: loads and saves (evidence: `src/server.ts`)
- Express API → Coverage projections: builds reports (evidence: `src/server.ts`)
- Builder UI → Canonical taxonomy: filters by beats
- Express API → Reporter directory: loads directory (evidence: `src/server.ts`)
- Express API → Reporter diagnostics: runs diagnostics (evidence: `src/server.ts`)
- Express API → Reporter enrichment: manages proposals (evidence: `src/server.ts`)
- Reporter enrichment → Article URL resolution: resolves article URLs (evidence: `src/enrichment.ts`)
- Reporter enrichment → Persistence adapter: reads and writes state (evidence: `src/enrichment.ts`)
- Structured store → Persistence adapter: reads and writes (evidence: `src/store.ts`)
- Express API → Google Workspace: routes Workspace operations (evidence: `src/server.ts`)
- Google Workspace → Google Drive and Sheets: reads and updates (evidence: `src/google.ts`)
- Article URL resolution → Search and AI providers: searches candidates
- Reporter enrichment → Search and AI providers: researches reporters
- Persistence adapter → Vercel Blob: persists production state (evidence: `README.md`)
