# modelearth/community-zipcodes architecture

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

- Interactive diagram: https://gitdiagram.com/modelearth/community-zipcodes
- Repository: https://github.com/modelearth/community-zipcodes

## Overview

This repository publishes ZIP-code economic data by NAICS industry and year. The documented workflow fetches Census data, populates DuckDB tables, and exports state-organized CSVs for users. The active modules cover population, database management, and export/query behavior; the README supplies the broader workflow where source excerpts are incomplete. Deprecated equivalents are shown separately because they are substantial indexed modules, not as part of the active path. Some implementation details and wiring are unsampled, so undocumented links are omitted.

Main entry points: [`industries/naics/duck_zipcode_db/populator/db_zip_populator.py`](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/db_zip_populator.py) (ZIP populator), [`deprecated/populator/db_zip_populator.py`](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/populator/db_zip_populator.py) (Legacy ZIP fetch), [`industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py`](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py) (CSV exporter), [`industries/naics/duck_zipcode_db/populator/database_populator.py`](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/database_populator.py) (Dimension population)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_zip_populator["ZIP populator"]
  node_dim_populator["Dimension population"]
end

subgraph group_storage["DuckDB storage"]
  node_active_db[("DuckDB manager<br/>[duckdb_manager.py]")]
end

subgraph group_exports["CSV access"]
  node_active_exporter["CSV exporter"]
  node_active_query["ZIP query<br/>[query.py]"]
  node_csv_data["Published CSVs"]
end

subgraph group_legacy["Deprecated pipeline"]
  node_legacy_populator["Legacy ZIP fetch"]
  node_legacy_dimensions["Legacy dimensions"]
  node_legacy_manager[("Legacy DB manager<br/>[duckdb_manager.py]")]
  node_legacy_exporter["Legacy exporter<br/>[dataexporter.py]"]
  node_legacy_query["Legacy query<br/>[query.py]"]
  node_legacy_csv["Legacy table exports"]
end

node_developer(("Data developer"))
node_census{{"Census API"}}
node_consumers(("Data users"))

node_developer -.->|"runs ingestion"| node_zip_populator
node_zip_populator -->|"initializes dimensions"| node_dim_populator
node_zip_populator -->|"requests ZIP data"| node_census
node_dim_populator -->|"requests geography"| node_census
node_zip_populator -.->|"writes entries"| node_active_db
node_active_db -.->|"provides stored data"| node_active_exporter
node_active_exporter -->|"filters rows"| node_active_query
node_active_exporter -->|"writes CSVs"| node_csv_data
node_consumers -->|"accesses data"| node_csv_data
node_legacy_populator -->|"initializes dimensions"| node_legacy_dimensions
node_legacy_populator -->|"requests ZIP data"| node_census
node_legacy_populator -.->|"writes entries"| node_legacy_manager
node_legacy_manager -->|"exports tables"| node_legacy_csv
node_legacy_exporter -->|"filters rows"| node_legacy_query

click node_zip_populator "https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/db_zip_populator.py"
click node_dim_populator "https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/database_populator.py"
click node_active_db "https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/zip_data/duck_db_manager/duckdb_manager.py"
click node_active_exporter "https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py"
click node_active_query "https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/exporter/query.py"
click node_csv_data "https://github.com/modelearth/community-zipcodes/tree/main/industries/naics/US/zip"
click node_legacy_populator "https://github.com/modelearth/community-zipcodes/blob/main/deprecated/populator/db_zip_populator.py"
click node_legacy_dimensions "https://github.com/modelearth/community-zipcodes/blob/main/deprecated/populator/database_populator.py"
click node_legacy_manager "https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/duckdb_manager.py"
click node_legacy_exporter "https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/dataexporter.py"
click node_legacy_query "https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/query.py"
click node_legacy_csv "https://github.com/modelearth/community-zipcodes/tree/main/deprecated/zip_data/duck_db_manager/database/exported_tables"

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_zip_populator,node_dim_populator,node_consumers toneBlue
class node_active_db toneAmber
class node_active_exporter,node_active_query,node_csv_data,node_census toneMint
class node_legacy_populator,node_legacy_dimensions,node_legacy_manager,node_legacy_exporter,node_legacy_query,node_legacy_csv toneRose
class node_developer toneIndigo
```

## Components

### Data ingestion

- [ZIP populator](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/db_zip_populator.py): `industries/naics/duck_zipcode_db/populator/db_zip_populator.py`
- [Dimension population](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/populator/database_populator.py): `industries/naics/duck_zipcode_db/populator/database_populator.py`

### DuckDB storage

- [DuckDB manager](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/zip_data/duck_db_manager/duckdb_manager.py): `industries/naics/duck_zipcode_db/zip_data/duck_db_manager/duckdb_manager.py`

### CSV access

- [CSV exporter](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py): `industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py`
- [ZIP query](https://github.com/modelearth/community-zipcodes/blob/main/industries/naics/duck_zipcode_db/exporter/query.py): `industries/naics/duck_zipcode_db/exporter/query.py`
- [Published CSVs](https://github.com/modelearth/community-zipcodes/tree/main/industries/naics/US/zip): `industries/naics/US/zip`

### Deprecated pipeline

- [Legacy ZIP fetch](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/populator/db_zip_populator.py): `deprecated/populator/db_zip_populator.py`
- [Legacy dimensions](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/populator/database_populator.py): `deprecated/populator/database_populator.py`
- [Legacy DB manager](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/duckdb_manager.py): `deprecated/zip_data/duck_db_manager/duckdb_manager.py`
- [Legacy exporter](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/dataexporter.py): `deprecated/zip_data/duck_db_manager/dataexporter.py`
- [Legacy query](https://github.com/modelearth/community-zipcodes/blob/main/deprecated/zip_data/duck_db_manager/query.py): `deprecated/zip_data/duck_db_manager/query.py`
- [Legacy table exports](https://github.com/modelearth/community-zipcodes/tree/main/deprecated/zip_data/duck_db_manager/database/exported_tables): `deprecated/zip_data/duck_db_manager/database/exported_tables`

### Other components

- **Data developer**
- **Census API**
- **Data users**

## Connections

- Data developer → ZIP populator: runs ingestion (evidence: `README.md`)
- ZIP populator → Dimension population: initializes dimensions (evidence: `industries/naics/duck_zipcode_db/populator/db_zip_populator.py`)
- ZIP populator → Census API: requests ZIP data (evidence: `industries/naics/duck_zipcode_db/populator/db_zip_populator.py`)
- Dimension population → Census API: requests geography (evidence: `industries/naics/duck_zipcode_db/populator/database_populator.py`)
- ZIP populator → DuckDB manager: writes entries
- DuckDB manager → CSV exporter: provides stored data
- CSV exporter → ZIP query: filters rows (evidence: `industries/naics/duck_zipcode_db/exporter/duck_db_exporter.py`)
- CSV exporter → Published CSVs: writes CSVs (evidence: `README.md`)
- Data users → Published CSVs: accesses data (evidence: `README.md`)
- Legacy ZIP fetch → Legacy dimensions: initializes dimensions (evidence: `deprecated/populator/db_zip_populator.py`)
- Legacy ZIP fetch → Census API: requests ZIP data (evidence: `deprecated/populator/db_zip_populator.py`)
- Legacy ZIP fetch → Legacy DB manager: writes entries
- Legacy DB manager → Legacy table exports: exports tables (evidence: `deprecated/zip_data/duck_db_manager/duckdb_manager.py`)
- Legacy exporter → Legacy query: filters rows (evidence: `deprecated/zip_data/duck_db_manager/dataexporter.py`)