# chrisscastaneda/wfp-candidate-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/chrisscastaneda/wfp-candidate-dashboard
- Repository: https://github.com/chrisscastaneda/wfp-candidate-dashboard
- Video tour (about a minute): https://gitdiagram.com/chrisscastaneda/wfp-candidate-dashboard/video

## Overview

WFP Candidate Dashboard collects endorsements and election results, reconciles results to endorsed candidates, publishes JSON, then bundles those datasets into a Vue dashboard. Users filter the state tile map and candidate list by office, search, and result status, and expand cards for vote details. The scraper modules are only partly sampled; their broader capabilities and hand-maintained matching workflow are documented in the README, so unsampled implementation links are omitted or marked unverified.

Main entry points: [`src/App.vue`](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/App.vue) (Dashboard filters), [`scrapers/elex/run.py`](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/run.py) (Results runner), [`scrapers/elex`](https://github.com/chrisscastaneda/wfp-candidate-dashboard/tree/main/scrapers/elex) (State and county sources), [`scrapers/elex/match.py`](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/match.py) (Contest matcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Data collection"]
  node_endorsement_scraper["Endorsement scraper"]
  node_election_runner["Results runner<br/>[run.py]"]
  node_registry["Source registry<br/>[registry.py]"]
  node_source_adapters["State and county sources"]
  node_platform_adapters["Feed platform adapters"]
  node_fetcher["Feed fetcher<br/>[fetch.py]"]
end

subgraph group_results["Results processing"]
  node_normalized_model["Normalized contests<br/>[model.py]"]
  node_name_normalization["Name normalization<br/>[names.py]"]
  node_result_store[("Result store<br/>[store.py]")]
  node_endorsements["Endorsement data<br/>[endorsements.py]"]
  node_matcher["Contest matcher<br/>[match.py]"]
  node_manual_entries["Manual race entries<br/>[manual.py]"]
  node_publisher["Dashboard publisher<br/>[publish.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_candidate_data["Candidate data loader<br/>[candidates.ts]"]
  node_result_data["Result data and status<br/>[results.ts]"]
  node_app["Dashboard filters<br/>[App.vue]"]
  node_tile_map["State tile map<br/>[TileMap.vue]"]
  node_category_controls["Office filters"]
  node_status_controls["Status filters<br/>[StatusToggles.vue]"]
  node_candidate_list["Candidate list<br/>[CandidateList.vue]"]
  node_candidate_card["Candidate card<br/>[CandidateCard.vue]"]
  node_result_detail["Expanded result detail<br/>[ResultDetail.vue]"]
end

node_operator(("Scraper operator"))
node_election_sites(("Election offices"))
node_dashboard_user(("Dashboard user"))

node_operator -->|"runs scrape"| node_endorsement_scraper
node_operator -->|"runs results"| node_election_runner
node_election_runner -->|"loads sources"| node_registry
node_registry -.->|"registers sources"| node_source_adapters
node_source_adapters -.->|"uses adapters"| node_platform_adapters
node_source_adapters -.->|"requests feeds"| node_fetcher
node_election_sites -.->|"serves feeds"| node_fetcher
node_fetcher -.->|"normalizes feeds"| node_normalized_model
node_election_runner -->|"stores snapshots"| node_result_store
node_election_runner -->|"loads endorsements"| node_endorsements
node_election_runner -->|"matches races"| node_matcher
node_matcher -->|"normalizes names"| node_name_normalization
node_matcher -.->|"uses manual races"| node_manual_entries
node_election_runner -->|"publishes results"| node_publisher
node_endorsement_scraper -->|"produces candidate data"| node_candidate_data
node_publisher -->|"produces dashboard results"| node_result_data
node_candidate_data -->|"provides candidates"| node_app
node_result_data -->|"provides statuses"| node_app
node_app -.->|"renders map"| node_tile_map
node_app -->|"renders controls"| node_category_controls
node_app -->|"renders controls"| node_status_controls
node_app -->|"renders filtered candidates"| node_candidate_list
node_candidate_list -->|"renders cards"| node_candidate_card
node_candidate_card -->|"looks up results"| node_result_data
node_candidate_card -->|"expands details"| node_result_detail
node_dashboard_user -->|"filters and searches"| node_app

click node_endorsement_scraper "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/scrape_wfp_candidates.py"
click node_election_runner "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/run.py"
click node_registry "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/registry.py"
click node_source_adapters "https://github.com/chrisscastaneda/wfp-candidate-dashboard/tree/main/scrapers/elex"
click node_platform_adapters "https://github.com/chrisscastaneda/wfp-candidate-dashboard/tree/main/scrapers/elex/platforms"
click node_fetcher "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/fetch.py"
click node_normalized_model "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/model.py"
click node_name_normalization "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/names.py"
click node_result_store "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/store.py"
click node_endorsements "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/endorsements.py"
click node_matcher "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/match.py"
click node_manual_entries "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/states/manual.py"
click node_publisher "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/publish.py"
click node_candidate_data "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/data/candidates.ts"
click node_result_data "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/data/results.ts"
click node_app "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/App.vue"
click node_tile_map "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/TileMap.vue"
click node_category_controls "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CategoryToggles.vue"
click node_status_controls "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/StatusToggles.vue"
click node_candidate_list "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CandidateList.vue"
click node_candidate_card "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CandidateCard.vue"
click node_result_detail "https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/ResultDetail.vue"

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_endorsement_scraper,node_election_runner,node_registry,node_source_adapters,node_platform_adapters,node_fetcher,node_dashboard_user toneBlue
class node_normalized_model,node_name_normalization,node_result_store,node_endorsements,node_matcher,node_manual_entries,node_publisher toneAmber
class node_candidate_data,node_result_data,node_app,node_tile_map,node_category_controls,node_status_controls,node_candidate_list,node_candidate_card,node_result_detail toneMint
class node_operator,node_election_sites toneIndigo
```

## Components

### Data collection

- [Endorsement scraper](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/scrape_wfp_candidates.py): `scrapers/scrape_wfp_candidates.py`
- [Results runner](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/run.py): `scrapers/elex/run.py`
- [Source registry](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/registry.py): `scrapers/elex/registry.py`
- [State and county sources](https://github.com/chrisscastaneda/wfp-candidate-dashboard/tree/main/scrapers/elex): `scrapers/elex`
- [Feed platform adapters](https://github.com/chrisscastaneda/wfp-candidate-dashboard/tree/main/scrapers/elex/platforms): `scrapers/elex/platforms`
- [Feed fetcher](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/fetch.py): `scrapers/elex/fetch.py`

### Results processing

- [Normalized contests](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/model.py): `scrapers/elex/model.py`
- [Name normalization](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/names.py): `scrapers/elex/names.py`
- [Result store](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/store.py): `scrapers/elex/store.py`
- [Endorsement data](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/endorsements.py): `scrapers/elex/endorsements.py`
- [Contest matcher](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/match.py): `scrapers/elex/match.py`
- [Manual race entries](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/states/manual.py): `scrapers/elex/states/manual.py`
- [Dashboard publisher](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/scrapers/elex/publish.py): `scrapers/elex/publish.py`

### Dashboard

- [Candidate data loader](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/data/candidates.ts): `src/data/candidates.ts`
- [Result data and status](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/data/results.ts): `src/data/results.ts`
- [Dashboard filters](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/App.vue): `src/App.vue`
- [State tile map](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/TileMap.vue): `src/components/TileMap.vue`
- [Office filters](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CategoryToggles.vue): `src/components/CategoryToggles.vue`
- [Status filters](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/StatusToggles.vue): `src/components/StatusToggles.vue`
- [Candidate list](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CandidateList.vue): `src/components/CandidateList.vue`
- [Candidate card](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/CandidateCard.vue): `src/components/CandidateCard.vue`
- [Expanded result detail](https://github.com/chrisscastaneda/wfp-candidate-dashboard/blob/main/src/components/ResultDetail.vue): `src/components/ResultDetail.vue`

### Other components

- **Scraper operator**
- **Election offices**
- **Dashboard user**

## Connections

- Scraper operator → Endorsement scraper: runs scrape
- Scraper operator → Results runner: runs results
- Results runner → Source registry: loads sources (evidence: `scrapers/elex/run.py`)
- Source registry → State and county sources: registers sources (evidence: `scrapers/elex/run.py`)
- State and county sources → Feed platform adapters: uses adapters (evidence: `scrapers/elex/counties/ny.py`)
- State and county sources → Feed fetcher: requests feeds (evidence: `scrapers/elex/source.py`)
- Election offices → Feed fetcher: serves feeds
- Feed fetcher → Normalized contests: normalizes feeds
- Results runner → Result store: stores snapshots (evidence: `scrapers/elex/run.py`)
- Results runner → Endorsement data: loads endorsements (evidence: `scrapers/elex/run.py`)
- Results runner → Contest matcher: matches races (evidence: `scrapers/elex/run.py`)
- Contest matcher → Name normalization: normalizes names (evidence: `scrapers/elex/match.py`)
- Contest matcher → Manual race entries: uses manual races
- Results runner → Dashboard publisher: publishes results (evidence: `scrapers/elex/run.py`)
- Endorsement scraper → Candidate data loader: produces candidate data
- Dashboard publisher → Result data and status: produces dashboard results
- Candidate data loader → Dashboard filters: provides candidates (evidence: `src/App.vue`)
- Result data and status → Dashboard filters: provides statuses (evidence: `src/App.vue`)
- Dashboard filters → State tile map: renders map (evidence: `src/App.vue`)
- Dashboard filters → Office filters: renders controls (evidence: `src/App.vue`)
- Dashboard filters → Status filters: renders controls (evidence: `src/App.vue`)
- Dashboard filters → Candidate list: renders filtered candidates (evidence: `src/App.vue`)
- Candidate list → Candidate card: renders cards (evidence: `src/components/CandidateList.vue`)
- Candidate card → Result data and status: looks up results (evidence: `src/components/CandidateCard.vue`)
- Candidate card → Expanded result detail: expands details (evidence: `src/components/CandidateCard.vue`)
- Dashboard user → Dashboard filters: filters and searches
