# sebaspalate/firetrack architecture

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

- Interactive diagram: https://gitdiagram.com/sebaspalate/firetrack
- Repository: https://github.com/sebaspalate/firetrack

## Overview

Firetrack turns public NASA FIRMS hotspot observations into a region-clipped, Aqua-referenced activity index, then presents calendars, maps, comparisons, method/validation evidence, and per-sensor CSV exports. The principal path is mirror ingestion → harmonization and processed artifacts → API or exported static data → browser dashboard. The README documents product capabilities and both serving modes; several UI component internals and pipeline modules were not excerpted, so their finer call relationships are not inferred.

Main entry points: [`apps/web/src/components/Dashboard.tsx`](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Dashboard.tsx) (Dashboard), [`apps/web/src/lib/api.ts`](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/api.ts) (Data client), [`services/api/main.py`](https://github.com/sebaspalate/firetrack/blob/main/services/api/main.py) (Read-only API), [`pipeline/export_web.py`](https://github.com/sebaspalate/firetrack/blob/main/pipeline/export_web.py) (Static data export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data pipeline"]
  node_ingest["Detection ingest<br/>[firms.py]"]
  node_regions["Region boundaries<br/>[regions.py]"]
  node_normalize["Sensor normalization<br/>[normalize.py]"]
end

subgraph group_serving["Serving and artifacts"]
  node_processed[("Processed artifacts")]
  node_payloads["Payload formatting<br/>[payloads.py]"]
  node_api["Read-only API<br/>[main.py]"]
  node_export["Static data export<br/>[export_web.py]"]
  node_static[("Browser data files")]
end

subgraph group_web["Web experience"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_api_client["Data client<br/>[api.ts]"]
  node_detections["Detection parser<br/>[detections.ts]"]
  node_calendar["Activity calendar"]
  node_map["Detection map<br/>[MapPanel.tsx]"]
  node_series["Comparison views<br/>[MonthlySeries.tsx]"]
  node_csv["CSV export<br/>[api.ts]"]
end

subgraph group_integrity["Method and evidence"]
  node_harmonize["Calibration and index<br/>[harmonize.py]"]
  node_method["Method and validation<br/>[Validation.tsx]"]
  node_provenance["Provenance details<br/>[Provenance.tsx]"]
end

node_manager(("Fire manager"))
node_firms[("FIRMS mirror")]

node_firms -->|"supplies detections"| node_ingest
node_ingest -->|"clips by region"| node_regions
node_ingest -->|"caches detections"| node_harmonize
node_harmonize -->|"normalizes sensors"| node_normalize
node_harmonize -->|"writes artifacts"| node_processed
node_manager -->|"explores activity"| node_dashboard
node_dashboard -.->|"loads data"| node_api_client
node_api_client -->|"requests payloads"| node_api
node_api_client -->|"reads static files"| node_static
node_api -->|"formats responses"| node_payloads
node_api -->|"queries artifacts"| node_processed
node_export -->|"reads artifacts"| node_processed
node_export -->|"builds shared payloads"| node_payloads
node_export -->|"writes browser files"| node_static
node_dashboard -->|"presents calendar"| node_calendar
node_dashboard -->|"presents map"| node_map
node_dashboard -->|"presents comparisons"| node_series
node_dashboard -->|"shows validation"| node_method
node_dashboard -->|"shows evidence"| node_provenance
node_api_client -->|"provides detection URLs"| node_detections
node_detections -->|"loads yearly CSV"| node_static
node_api_client -->|"downloads detections"| node_csv
node_api -->|"serves detection CSV"| node_csv

click node_ingest "https://github.com/sebaspalate/firetrack/blob/main/pipeline/firms.py"
click node_regions "https://github.com/sebaspalate/firetrack/blob/main/pipeline/regions.py"
click node_harmonize "https://github.com/sebaspalate/firetrack/blob/main/pipeline/harmonize.py"
click node_normalize "https://github.com/sebaspalate/firetrack/blob/main/pipeline/normalize.py"
click node_processed "https://github.com/sebaspalate/firetrack/tree/main/data/processed"
click node_payloads "https://github.com/sebaspalate/firetrack/blob/main/pipeline/payloads.py"
click node_api "https://github.com/sebaspalate/firetrack/blob/main/services/api/main.py"
click node_export "https://github.com/sebaspalate/firetrack/blob/main/pipeline/export_web.py"
click node_static "https://github.com/sebaspalate/firetrack/tree/main/apps/web/public/data"
click node_dashboard "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Dashboard.tsx"
click node_api_client "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/api.ts"
click node_detections "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/detections.ts"
click node_calendar "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/CalendarHeatmap.tsx"
click node_map "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/MapPanel.tsx"
click node_series "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/MonthlySeries.tsx"
click node_method "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Validation.tsx"
click node_provenance "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Provenance.tsx"
click node_csv "https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/api.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_ingest,node_regions,node_normalize toneBlue
class node_processed,node_payloads,node_api,node_export,node_static,node_firms toneAmber
class node_dashboard,node_api_client,node_detections,node_calendar,node_map,node_series,node_csv toneMint
class node_harmonize,node_method,node_provenance toneRose
class node_manager toneIndigo
```

## Components

### Data pipeline

- [Detection ingest](https://github.com/sebaspalate/firetrack/blob/main/pipeline/firms.py): `pipeline/firms.py`
- [Region boundaries](https://github.com/sebaspalate/firetrack/blob/main/pipeline/regions.py): `pipeline/regions.py`
- [Sensor normalization](https://github.com/sebaspalate/firetrack/blob/main/pipeline/normalize.py): `pipeline/normalize.py`

### Serving and artifacts

- [Processed artifacts](https://github.com/sebaspalate/firetrack/tree/main/data/processed): `data/processed`
- [Payload formatting](https://github.com/sebaspalate/firetrack/blob/main/pipeline/payloads.py): `pipeline/payloads.py`
- [Read-only API](https://github.com/sebaspalate/firetrack/blob/main/services/api/main.py): `services/api/main.py`
- [Static data export](https://github.com/sebaspalate/firetrack/blob/main/pipeline/export_web.py): `pipeline/export_web.py`
- [Browser data files](https://github.com/sebaspalate/firetrack/tree/main/apps/web/public/data): `apps/web/public/data`

### Web experience

- [Dashboard](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Dashboard.tsx): `apps/web/src/components/Dashboard.tsx`
- [Data client](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Detection parser](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/detections.ts): `apps/web/src/lib/detections.ts`
- [Activity calendar](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/CalendarHeatmap.tsx): `apps/web/src/components/CalendarHeatmap.tsx`
- [Detection map](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/MapPanel.tsx): `apps/web/src/components/MapPanel.tsx`
- [Comparison views](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/MonthlySeries.tsx): `apps/web/src/components/MonthlySeries.tsx`
- [CSV export](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Method and evidence

- [Calibration and index](https://github.com/sebaspalate/firetrack/blob/main/pipeline/harmonize.py): `pipeline/harmonize.py`
- [Method and validation](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Validation.tsx): `apps/web/src/components/Validation.tsx`
- [Provenance details](https://github.com/sebaspalate/firetrack/blob/main/apps/web/src/components/Provenance.tsx): `apps/web/src/components/Provenance.tsx`

### Other components

- **Fire manager**
- **FIRMS mirror**

## Connections

- FIRMS mirror → Detection ingest: supplies detections (evidence: `pipeline/firms.py`)
- Detection ingest → Region boundaries: clips by region (evidence: `pipeline/firms.py`)
- Detection ingest → Calibration and index: caches detections (evidence: `pipeline/harmonize.py`)
- Calibration and index → Sensor normalization: normalizes sensors (evidence: `pipeline/harmonize.py`)
- Calibration and index → Processed artifacts: writes artifacts (evidence: `pipeline/harmonize.py`)
- Fire manager → Dashboard: explores activity (evidence: `README.md`)
- Dashboard → Data client: loads data
- Data client → Read-only API: requests payloads (evidence: `apps/web/src/lib/api.ts`)
- Data client → Browser data files: reads static files (evidence: `apps/web/src/lib/api.ts`)
- Read-only API → Payload formatting: formats responses (evidence: `services/api/main.py`)
- Read-only API → Processed artifacts: queries artifacts (evidence: `services/api/main.py`)
- Static data export → Processed artifacts: reads artifacts (evidence: `pipeline/export_web.py`)
- Static data export → Payload formatting: builds shared payloads (evidence: `pipeline/export_web.py`)
- Static data export → Browser data files: writes browser files (evidence: `pipeline/export_web.py`)
- Dashboard → Activity calendar: presents calendar (evidence: `README.md`)
- Dashboard → Detection map: presents map (evidence: `README.md`)
- Dashboard → Comparison views: presents comparisons (evidence: `README.md`)
- Dashboard → Method and validation: shows validation (evidence: `README.md`)
- Dashboard → Provenance details: shows evidence (evidence: `README.md`)
- Data client → Detection parser: provides detection URLs (evidence: `apps/web/src/lib/detections.ts`)
- Detection parser → Browser data files: loads yearly CSV (evidence: `apps/web/src/lib/detections.ts`)
- Data client → CSV export: downloads detections (evidence: `apps/web/src/lib/api.ts`)
- Read-only API → CSV export: serves detection CSV (evidence: `services/api/main.py`)
