# jjrodriguezz/newyork-brain architecture

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

- Interactive diagram: https://gitdiagram.com/jjrodriguezz/newyork-brain
- Repository: https://github.com/jjrodriguezz/newyork-brain

## Overview

Cerebro NYC is a browser-based territorial data twin for comparing New York’s 55 PUMA districts and boroughs. Users explore its thematic sections, ranked atlas, correlations, and 3D map to investigate quality of life, housing, safety, mobility, environment, and outside interest; figures carry source and data-quality status. A companion pipeline fetches public APIs into a traceable local data lake, with a dictionary and verification rule supporting data governance. The excerpts establish startup-to-map wiring and parts of the data-building pipeline; other UI wiring is not shown, so those links are omitted.

Main entry points: [`scripts/construir_lago.py`](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/construir_lago.py) (API lake builder), [`scripts/verificar_lago.py`](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/verificar_lago.py) (Lake field verification), [`js/app.js`](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/app.js) (Site startup), [`lago/lago.js`](https://github.com/jjrodriguezz/newyork-brain/blob/main/lago/lago.js) (Offline lake package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser experience"]
  node_startup["Site startup<br/>[app.js]"]
  node_thematic["Thematic sections<br/>[secciones.js]"]
  node_diagnostic["District diagnosis<br/>[diagnostico.js]"]
  node_correlations["Correlations<br/>[correlaciones.js]"]
  node_map["3D territorial twin<br/>[mapa.js]"]
  node_charts["SVG chart primitives<br/>[graficos.js]"]
end

subgraph group_lake["Data lake"]
  node_lake_bundle["Offline lake package<br/>[lago.js]"]
  node_lake_topics[("Topic data")]
  node_geometries["Territorial geometries"]
end

subgraph group_pipeline["Data pipeline"]
  node_builder["API lake builder<br/>[construir_lago.py]"]
  node_shared["API and geometry utilities<br/>[comun.py]"]
end

subgraph group_governance["Data governance"]
  node_catalog["Source catalog<br/>[catalogo.py]"]
  node_dictionary["Field dictionary<br/>[diccionario.py]"]
  node_verification["Lake field verification<br/>[verificar_lago.py]"]
end

node_user(("City analyst"))

node_user -->|"opens site"| node_startup
node_startup -->|"initializes with lake"| node_map
node_startup -->|"loads when available"| node_lake_bundle
node_builder -->|"uses utilities"| node_shared
node_builder -->|"uses source catalog"| node_catalog
node_builder -->|"writes topic data"| node_lake_topics
node_builder -->|"writes offline package"| node_lake_bundle
node_verification -->|"imports lake paths"| node_shared
node_verification -->|"checks documented fields"| node_dictionary
node_verification -->|"scans JSON fields"| node_lake_topics
node_verification -->|"scans GeoJSON fields"| node_geometries

click node_startup "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/app.js"
click node_thematic "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/secciones.js"
click node_diagnostic "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/diagnostico.js"
click node_correlations "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/correlaciones.js"
click node_map "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/mapa.js"
click node_charts "https://github.com/jjrodriguezz/newyork-brain/blob/main/js/graficos.js"
click node_lake_bundle "https://github.com/jjrodriguezz/newyork-brain/blob/main/lago/lago.js"
click node_lake_topics "https://github.com/jjrodriguezz/newyork-brain/tree/main/lago"
click node_geometries "https://github.com/jjrodriguezz/newyork-brain/tree/main/lago/geo"
click node_builder "https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/construir_lago.py"
click node_shared "https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/comun.py"
click node_catalog "https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/catalogo.py"
click node_dictionary "https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/diccionario.py"
click node_verification "https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/verificar_lago.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_startup,node_thematic,node_diagnostic,node_correlations,node_map,node_charts toneBlue
class node_lake_bundle,node_lake_topics,node_geometries toneAmber
class node_builder,node_shared toneMint
class node_catalog,node_dictionary,node_verification toneRose
class node_user toneIndigo
```

## Components

### Browser experience

- [Site startup](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/app.js): `js/app.js`
- [Thematic sections](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/secciones.js): `js/secciones.js`
- [District diagnosis](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/diagnostico.js): `js/diagnostico.js`
- [Correlations](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/correlaciones.js): `js/correlaciones.js`
- [3D territorial twin](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/mapa.js): `js/mapa.js`
- [SVG chart primitives](https://github.com/jjrodriguezz/newyork-brain/blob/main/js/graficos.js): `js/graficos.js`

### Data lake

- [Offline lake package](https://github.com/jjrodriguezz/newyork-brain/blob/main/lago/lago.js): `lago/lago.js`
- [Topic data](https://github.com/jjrodriguezz/newyork-brain/tree/main/lago): `lago`
- [Territorial geometries](https://github.com/jjrodriguezz/newyork-brain/tree/main/lago/geo): `lago/geo`

### Data pipeline

- [API lake builder](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/construir_lago.py): `scripts/construir_lago.py`
- [API and geometry utilities](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/comun.py): `scripts/comun.py`

### Data governance

- [Source catalog](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/catalogo.py): `scripts/catalogo.py`
- [Field dictionary](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/diccionario.py): `scripts/diccionario.py`
- [Lake field verification](https://github.com/jjrodriguezz/newyork-brain/blob/main/scripts/verificar_lago.py): `scripts/verificar_lago.py`

### Other components

- **City analyst**

## Connections

- City analyst → Site startup: opens site (evidence: `README.md`)
- Site startup → 3D territorial twin: initializes with lake (evidence: `js/app.js`)
- Site startup → Offline lake package: loads when available (evidence: `js/app.js`)
- API lake builder → API and geometry utilities: uses utilities (evidence: `scripts/construir_lago.py`)
- API lake builder → Source catalog: uses source catalog (evidence: `scripts/construir_lago.py`)
- API lake builder → Topic data: writes topic data (evidence: `scripts/construir_lago.py`)
- API lake builder → Offline lake package: writes offline package (evidence: `scripts/construir_lago.py`)
- Lake field verification → API and geometry utilities: imports lake paths (evidence: `scripts/verificar_lago.py`)
- Lake field verification → Field dictionary: checks documented fields (evidence: `scripts/verificar_lago.py`)
- Lake field verification → Topic data: scans JSON fields (evidence: `scripts/verificar_lago.py`)
- Lake field verification → Territorial geometries: scans GeoJSON fields (evidence: `scripts/verificar_lago.py`)
