# paulinotech1/flock-off architecture

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

- Interactive diagram: https://gitdiagram.com/paulinotech1/flock-off
- Repository: https://github.com/paulinotech1/flock-off

## Overview

Flock-Off is a public tracker for Flock Safety ALPR contracts, renewals, costs, cancellations, and their sources. Its principal user workflow is to search and filter the agency dataset, inspect contract history and citations, and use the resulting renewal or cancellation information for civic research. Separate branches provide map, learning, and ecosystem tools, plus a quarantined tip-submission and human-review flow. The maintenance tooling validates source identity and evidence, monitors records, and archives source snapshots. Some subsystem links are based on README descriptions; unsampled implementation details are left unconnected.

Main entry points: [`scripts/flockoff.py`](https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff.py) (Maintenance commands), [`scripts/source_fingerprints.py`](https://github.com/paulinotech1/flock-off/blob/main/scripts/source_fingerprints.py) (Source fingerprints), [`api/report.js`](https://github.com/paulinotech1/flock-off/blob/main/api/report.js) (Tip intake), [`api/promote.js`](https://github.com/paulinotech1/flock-off/blob/main/api/promote.js) (Human review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public tracker"]
  node_tracker["Contract tracker<br/>[tracker.js]"]
  node_agencydata[("Agency contracts<br/>[agencies.json]")]
  node_webapp["Page navigation<br/>[app.js]"]
  node_map["Camera map<br/>[sources.js]"]
  node_civictools["Civic resources<br/>[index.html]"]
end

subgraph group_research["Evidence research"]
  node_evidence["Evidence tiers<br/>[evidence.py]"]
  node_classification["Source classification"]
  node_sourcekeys["Citation identity<br/>[source_keys.py]"]
  node_fingerprints["Source fingerprints"]
  node_snapshotarchive[("Snapshot archive<br/>[blob_archive.py]")]
  node_sourcearchive["Archived source data"]
end

subgraph group_tips["Tip review"]
  node_report["Tip intake<br/>[report.js]"]
  node_signals["Privacy signals<br/>[_signals.js]"]
  node_pending["Pending queue<br/>[pending.js]"]
  node_promotion["Human review<br/>[promote.js]"]
  node_history["Approved history<br/>[history.js]"]
  node_apierrors["API error codes<br/>[_errors.js]"]
end

subgraph group_maintenance["Maintenance tooling"]
  node_monitor["Weekly review<br/>[weekly_monitor.py]"]
  node_cli["Maintenance commands<br/>[flockoff.py]"]
  node_config["Pipeline configuration<br/>[flockoff_config.py]"]
  node_signing["Manifest signing<br/>[sign_manifest.py]"]
  node_buildvalidation["Build evidence checks<br/>[vercel_build.py]"]
  node_pipelineerrors["Pipeline error codes<br/>[flockoff_errors.py]"]
end

node_visitor(("Public visitor"))
node_mapservices["Map services"]
node_blobstore[("Vercel Blob")]

node_visitor -->|"opens"| node_webapp
node_webapp -->|"shows"| node_tracker
node_tracker -->|"reads"| node_agencydata
node_visitor -->|"opens"| node_map
node_map -->|"fetches map data"| node_mapservices
node_visitor -->|"uses"| node_civictools
node_cli -->|"dispatches"| node_sourcekeys
node_cli -->|"dispatches"| node_fingerprints
node_cli -->|"dispatches"| node_classification
node_cli -->|"dispatches"| node_monitor
node_cli -->|"retrieves snapshots"| node_snapshotarchive
node_fingerprints -->|"uses"| node_sourcekeys
node_fingerprints -->|"uses"| node_snapshotarchive
node_classification -->|"loads settings"| node_config
node_sourcekeys -->|"loads settings"| node_config
node_monitor -->|"loads settings"| node_config
node_monitor -->|"checks dataset"| node_agencydata
node_buildvalidation -->|"uses"| node_evidence
node_visitor -.->|"submits tip"| node_report
node_report -->|"computes signals"| node_signals
node_report -->|"writes pending tip"| node_blobstore
node_visitor -.->|"requests queue"| node_pending
node_pending -.->|"lists pending tips"| node_blobstore
node_visitor -.->|"reviews tip"| node_promotion
node_promotion -->|"moves reviewed tip"| node_blobstore
node_promotion -->|"updates decisions"| node_signals
node_visitor -.->|"views reports"| node_history
node_history -.->|"reads approved reports"| node_blobstore
node_report -->|"returns errors"| node_apierrors
node_promotion -->|"returns errors"| node_apierrors
node_cli -.->|"dispatches"| node_signing
node_fingerprints -.->|"archives snapshots"| node_sourcearchive

click node_tracker "https://github.com/paulinotech1/flock-off/blob/main/js/tracker.js"
click node_agencydata "https://github.com/paulinotech1/flock-off/blob/main/data/agencies.json"
click node_webapp "https://github.com/paulinotech1/flock-off/blob/main/js/app.js"
click node_map "https://github.com/paulinotech1/flock-off/blob/main/js/sources.js"
click node_civictools "https://github.com/paulinotech1/flock-off/blob/main/index.html"
click node_evidence "https://github.com/paulinotech1/flock-off/blob/main/scripts/evidence.py"
click node_classification "https://github.com/paulinotech1/flock-off/blob/main/scripts/classify_sources.py"
click node_sourcekeys "https://github.com/paulinotech1/flock-off/blob/main/scripts/source_keys.py"
click node_fingerprints "https://github.com/paulinotech1/flock-off/blob/main/scripts/source_fingerprints.py"
click node_snapshotarchive "https://github.com/paulinotech1/flock-off/blob/main/scripts/blob_archive.py"
click node_sourcearchive "https://github.com/paulinotech1/flock-off/tree/main/data/source_archive"
click node_monitor "https://github.com/paulinotech1/flock-off/blob/main/scripts/weekly_monitor.py"
click node_cli "https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff.py"
click node_config "https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff_config.py"
click node_signing "https://github.com/paulinotech1/flock-off/blob/main/scripts/sign_manifest.py"
click node_buildvalidation "https://github.com/paulinotech1/flock-off/blob/main/scripts/vercel_build.py"
click node_report "https://github.com/paulinotech1/flock-off/blob/main/api/report.js"
click node_signals "https://github.com/paulinotech1/flock-off/blob/main/api/_signals.js"
click node_pending "https://github.com/paulinotech1/flock-off/blob/main/api/pending.js"
click node_promotion "https://github.com/paulinotech1/flock-off/blob/main/api/promote.js"
click node_history "https://github.com/paulinotech1/flock-off/blob/main/api/history.js"
click node_apierrors "https://github.com/paulinotech1/flock-off/blob/main/api/_errors.js"
click node_pipelineerrors "https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff_errors.py"

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_tracker,node_agencydata,node_webapp,node_map,node_civictools toneBlue
class node_evidence,node_classification,node_sourcekeys,node_fingerprints,node_snapshotarchive,node_sourcearchive,node_blobstore toneAmber
class node_report,node_signals,node_pending,node_promotion,node_history,node_apierrors toneMint
class node_monitor,node_cli,node_config,node_signing,node_buildvalidation,node_pipelineerrors toneRose
class node_visitor,node_mapservices toneIndigo
```

## Components

### Public tracker

- [Contract tracker](https://github.com/paulinotech1/flock-off/blob/main/js/tracker.js): `js/tracker.js`
- [Agency contracts](https://github.com/paulinotech1/flock-off/blob/main/data/agencies.json): `data/agencies.json`
- [Page navigation](https://github.com/paulinotech1/flock-off/blob/main/js/app.js): `js/app.js`
- [Camera map](https://github.com/paulinotech1/flock-off/blob/main/js/sources.js): `js/sources.js`
- [Civic resources](https://github.com/paulinotech1/flock-off/blob/main/index.html): `index.html`

### Evidence research

- [Evidence tiers](https://github.com/paulinotech1/flock-off/blob/main/scripts/evidence.py): `scripts/evidence.py`
- [Source classification](https://github.com/paulinotech1/flock-off/blob/main/scripts/classify_sources.py): `scripts/classify_sources.py`
- [Citation identity](https://github.com/paulinotech1/flock-off/blob/main/scripts/source_keys.py): `scripts/source_keys.py`
- [Source fingerprints](https://github.com/paulinotech1/flock-off/blob/main/scripts/source_fingerprints.py): `scripts/source_fingerprints.py`
- [Snapshot archive](https://github.com/paulinotech1/flock-off/blob/main/scripts/blob_archive.py): `scripts/blob_archive.py`
- [Archived source data](https://github.com/paulinotech1/flock-off/tree/main/data/source_archive): `data/source_archive`

### Tip review

- [Tip intake](https://github.com/paulinotech1/flock-off/blob/main/api/report.js): `api/report.js`
- [Privacy signals](https://github.com/paulinotech1/flock-off/blob/main/api/_signals.js): `api/_signals.js`
- [Pending queue](https://github.com/paulinotech1/flock-off/blob/main/api/pending.js): `api/pending.js`
- [Human review](https://github.com/paulinotech1/flock-off/blob/main/api/promote.js): `api/promote.js`
- [Approved history](https://github.com/paulinotech1/flock-off/blob/main/api/history.js): `api/history.js`
- [API error codes](https://github.com/paulinotech1/flock-off/blob/main/api/_errors.js): `api/_errors.js`

### Maintenance tooling

- [Weekly review](https://github.com/paulinotech1/flock-off/blob/main/scripts/weekly_monitor.py): `scripts/weekly_monitor.py`
- [Maintenance commands](https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff.py): `scripts/flockoff.py`
- [Pipeline configuration](https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff_config.py): `scripts/flockoff_config.py`
- [Manifest signing](https://github.com/paulinotech1/flock-off/blob/main/scripts/sign_manifest.py): `scripts/sign_manifest.py`
- [Build evidence checks](https://github.com/paulinotech1/flock-off/blob/main/scripts/vercel_build.py): `scripts/vercel_build.py`
- [Pipeline error codes](https://github.com/paulinotech1/flock-off/blob/main/scripts/flockoff_errors.py): `scripts/flockoff_errors.py`

### Other components

- **Public visitor**
- **Map services**
- **Vercel Blob**

## Connections

- Public visitor → Page navigation: opens (evidence: `README.md`)
- Page navigation → Contract tracker: shows (evidence: `README.md`)
- Contract tracker → Agency contracts: reads (evidence: `README.md`)
- Public visitor → Camera map: opens (evidence: `README.md`)
- Camera map → Map services: fetches map data (evidence: `README.md`)
- Public visitor → Civic resources: uses (evidence: `README.md`)
- Maintenance commands → Citation identity: dispatches (evidence: `scripts/flockoff.py`)
- Maintenance commands → Source fingerprints: dispatches (evidence: `scripts/flockoff.py`)
- Maintenance commands → Source classification: dispatches (evidence: `scripts/flockoff.py`)
- Maintenance commands → Weekly review: dispatches (evidence: `scripts/flockoff.py`)
- Maintenance commands → Snapshot archive: retrieves snapshots (evidence: `scripts/flockoff.py`)
- Source fingerprints → Citation identity: uses (evidence: `scripts/source_fingerprints.py`)
- Source fingerprints → Snapshot archive: uses (evidence: `scripts/source_fingerprints.py`)
- Source classification → Pipeline configuration: loads settings (evidence: `scripts/classify_sources.py`)
- Citation identity → Pipeline configuration: loads settings (evidence: `scripts/source_keys.py`)
- Weekly review → Pipeline configuration: loads settings (evidence: `scripts/weekly_monitor.py`)
- Weekly review → Agency contracts: checks dataset (evidence: `scripts/weekly_monitor.py`)
- Build evidence checks → Evidence tiers: uses (evidence: `scripts/vercel_build.py`)
- Public visitor → Tip intake: submits tip (evidence: `README.md`)
- Tip intake → Privacy signals: computes signals (evidence: `api/report.js`)
- Tip intake → Vercel Blob: writes pending tip (evidence: `api/report.js`)
- Public visitor → Pending queue: requests queue (evidence: `README.md`)
- Pending queue → Vercel Blob: lists pending tips (evidence: `README.md`)
- Public visitor → Human review: reviews tip (evidence: `README.md`)
- Human review → Vercel Blob: moves reviewed tip (evidence: `api/promote.js`)
- Human review → Privacy signals: updates decisions (evidence: `api/_signals.js`)
- Public visitor → Approved history: views reports (evidence: `README.md`)
- Approved history → Vercel Blob: reads approved reports (evidence: `README.md`)
- Tip intake → API error codes: returns errors (evidence: `api/report.js`)
- Human review → API error codes: returns errors (evidence: `api/promote.js`)
- Maintenance commands → Manifest signing: dispatches (evidence: `scripts/flockoff.py`)
- Source fingerprints → Archived source data: archives snapshots
