# cosmosnehu77/charmy architecture

> Architecture diagram of the GitHub repository cosmosnehu77/charmy, 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/cosmosnehu77/charmy
- Repository: https://github.com/cosmosnehu77/charmy

## Overview

Charmy harmonizes satellite fire detections into a long-running record, serves maps, calendars, live reports and forecasts through an API, and presents them in a public/expert web app. The principal user flow is selecting an area and dates, requesting observations and calendar summaries, and viewing results on the map; documented branches add forecasts, live-fire context, alerts, CSV export and the Brigade learning game. Edges reflect shown imports/calls or README descriptions; unsampled subsystem wiring is left out or marked unverified.

Main entry points: [`services/api/src/api/main.py`](https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/main.py) (REST API), [`apps/app/src/App.tsx`](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/App.tsx) (Charmy app), [`apps/app/src/calendario/grilla.ts`](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/calendario/grilla.ts) (Burn calendar), [`apps/app/src/consulta/useFocos.ts`](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/consulta/useFocos.ts) (Focus queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_app["Charmy app<br/>[App.tsx]"]
  node_area["Area selection"]
  node_map["Relief map<br/>[MapaRelieve.tsx]"]
  node_calendar["Burn calendar<br/>[grilla.ts]"]
  node_foci["Focus queries<br/>[useFocos.ts]"]
  node_context["Place context<br/>[PanelContexto.tsx]"]
  node_reports["Live reporting<br/>[FormReporte.tsx]"]
  node_mascot["Charmy artwork<br/>[dibujo.ts]"]
end

subgraph group_api["API and context"]
  node_api["REST API<br/>[main.py]"]
  node_hotspots["Hotspot routes<br/>[hotspots.py]"]
  node_calendarapi["Calendar routes<br/>[calendario.py]"]
  node_liveapi["Live routes<br/>[vivo.py]"]
  node_imagery["Satellite imagery<br/>[imagen.py]"]
  node_weather["Weather context<br/>[tiempo.py]"]
end

subgraph group_data["Fire data"]
  node_harmonize["Sensor harmonization<br/>[armonizacion.py]"]
  node_pipeline["Data preparation"]
  node_worker["Live verification<br/>[verificacion.py]"]
end

subgraph group_prediction["Forecasting"]
  node_forecast["Fire forecasting<br/>[servir.py]"]
end

subgraph group_outreach["Alerts and learning"]
  node_alertservice["Alert delivery<br/>[cliente.py]"]
  node_telegram["Telegram"]
  node_game["Brigade game<br/>[juego.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"uses"| node_app
node_app -->|"offers"| node_area
node_app -->|"renders"| node_map
node_app -->|"shows"| node_calendar
node_app -->|"queries"| node_foci
node_app -->|"shows"| node_context
node_app -->|"offers"| node_reports
node_foci -.->|"requests data"| node_api
node_calendar -.->|"requests calendar"| node_api
node_api -->|"registers route"| node_hotspots
node_api -->|"registers route"| node_calendarapi
node_api -->|"registers route"| node_liveapi
node_api -->|"imports"| node_imagery
node_api -->|"imports"| node_weather
node_pipeline -->|"harmonizes detections"| node_harmonize
node_harmonize -.->|"supplies series"| node_api
node_api -->|"serves forecasts"| node_forecast
node_api -.->|"provides live data"| node_worker
node_api -.->|"supports alerts"| node_alertservice
node_alertservice -.->|"delivers alerts"| node_telegram
node_visitor -->|"plays"| node_game
node_app -->|"uses mascot"| node_mascot

click node_app "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/App.tsx"
click node_area "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/novato/BuscarLocalidad.tsx"
click node_map "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/relieve/MapaRelieve.tsx"
click node_calendar "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/calendario/grilla.ts"
click node_foci "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/consulta/useFocos.ts"
click node_context "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/contexto/PanelContexto.tsx"
click node_reports "https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/vivo/FormReporte.tsx"
click node_api "https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/main.py"
click node_hotspots "https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/hotspots.py"
click node_calendarapi "https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/calendario.py"
click node_liveapi "https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/vivo.py"
click node_imagery "https://github.com/cosmosnehu77/charmy/blob/main/services/contexto/src/contexto/imagen.py"
click node_weather "https://github.com/cosmosnehu77/charmy/blob/main/services/contexto/src/contexto/tiempo.py"
click node_harmonize "https://github.com/cosmosnehu77/charmy/blob/main/services/pipeline/src/pipeline/armonizacion.py"
click node_pipeline "https://github.com/cosmosnehu77/charmy/tree/main/services/pipeline/src/pipeline"
click node_worker "https://github.com/cosmosnehu77/charmy/blob/main/services/worker/src/worker/verificacion.py"
click node_forecast "https://github.com/cosmosnehu77/charmy/blob/main/services/prediccion/src/prediccion/servir.py"
click node_alertservice "https://github.com/cosmosnehu77/charmy/blob/main/services/alertas/src/alertas/cliente.py"
click node_game "https://github.com/cosmosnehu77/charmy/blob/main/apps/juego/src/juego.js"
click node_mascot "https://github.com/cosmosnehu77/charmy/blob/main/packages/charmy/src/dibujo.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_app,node_area,node_map,node_calendar,node_foci,node_context,node_reports,node_mascot toneBlue
class node_api,node_hotspots,node_calendarapi,node_liveapi,node_imagery,node_weather toneAmber
class node_harmonize,node_pipeline,node_worker toneMint
class node_forecast toneRose
class node_alertservice,node_telegram,node_game,node_visitor toneIndigo
```

## Components

### Web experience

- [Charmy app](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/App.tsx): `apps/app/src/App.tsx`
- [Area selection](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/novato/BuscarLocalidad.tsx): `apps/app/src/novato/BuscarLocalidad.tsx`
- [Relief map](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/relieve/MapaRelieve.tsx): `apps/app/src/relieve/MapaRelieve.tsx`
- [Burn calendar](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/calendario/grilla.ts): `apps/app/src/calendario/grilla.ts`
- [Focus queries](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/consulta/useFocos.ts): `apps/app/src/consulta/useFocos.ts`
- [Place context](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/contexto/PanelContexto.tsx): `apps/app/src/contexto/PanelContexto.tsx`
- [Live reporting](https://github.com/cosmosnehu77/charmy/blob/main/apps/app/src/vivo/FormReporte.tsx): `apps/app/src/vivo/FormReporte.tsx`
- [Charmy artwork](https://github.com/cosmosnehu77/charmy/blob/main/packages/charmy/src/dibujo.ts): `packages/charmy/src/dibujo.ts`

### API and context

- [REST API](https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/main.py): `services/api/src/api/main.py`
- [Hotspot routes](https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/hotspots.py): `services/api/src/api/hotspots.py`
- [Calendar routes](https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/calendario.py): `services/api/src/api/calendario.py`
- [Live routes](https://github.com/cosmosnehu77/charmy/blob/main/services/api/src/api/vivo.py): `services/api/src/api/vivo.py`
- [Satellite imagery](https://github.com/cosmosnehu77/charmy/blob/main/services/contexto/src/contexto/imagen.py): `services/contexto/src/contexto/imagen.py`
- [Weather context](https://github.com/cosmosnehu77/charmy/blob/main/services/contexto/src/contexto/tiempo.py): `services/contexto/src/contexto/tiempo.py`

### Fire data

- [Sensor harmonization](https://github.com/cosmosnehu77/charmy/blob/main/services/pipeline/src/pipeline/armonizacion.py): `services/pipeline/src/pipeline/armonizacion.py`
- [Data preparation](https://github.com/cosmosnehu77/charmy/tree/main/services/pipeline/src/pipeline): `services/pipeline/src/pipeline`
- [Live verification](https://github.com/cosmosnehu77/charmy/blob/main/services/worker/src/worker/verificacion.py): `services/worker/src/worker/verificacion.py`

### Forecasting

- [Fire forecasting](https://github.com/cosmosnehu77/charmy/blob/main/services/prediccion/src/prediccion/servir.py): `services/prediccion/src/prediccion/servir.py`

### Alerts and learning

- [Alert delivery](https://github.com/cosmosnehu77/charmy/blob/main/services/alertas/src/alertas/cliente.py): `services/alertas/src/alertas/cliente.py`
- **Telegram**
- [Brigade game](https://github.com/cosmosnehu77/charmy/blob/main/apps/juego/src/juego.js): `apps/juego/src/juego.js`

### Other components

- **Visitor**

## Connections

- Visitor → Charmy app: uses (evidence: `README.md`)
- Charmy app → Area selection: offers (evidence: `README.md`)
- Charmy app → Relief map: renders (evidence: `README.md`)
- Charmy app → Burn calendar: shows (evidence: `README.md`)
- Charmy app → Focus queries: queries (evidence: `apps/app/src/consulta/useFocos.ts`)
- Charmy app → Place context: shows (evidence: `README.md`)
- Charmy app → Live reporting: offers (evidence: `README.md`)
- Focus queries → REST API: requests data
- Burn calendar → REST API: requests calendar
- REST API → Hotspot routes: registers route (evidence: `services/api/src/api/main.py`)
- REST API → Calendar routes: registers route (evidence: `services/api/src/api/main.py`)
- REST API → Live routes: registers route (evidence: `services/api/src/api/main.py`)
- REST API → Satellite imagery: imports (evidence: `services/api/src/api/main.py`)
- REST API → Weather context: imports (evidence: `services/api/src/api/main.py`)
- Data preparation → Sensor harmonization: harmonizes detections (evidence: `services/pipeline/src/pipeline/armonizacion.py`)
- Sensor harmonization → REST API: supplies series
- REST API → Fire forecasting: serves forecasts (evidence: `services/api/src/api/main.py`)
- REST API → Live verification: provides live data
- REST API → Alert delivery: supports alerts
- Alert delivery → Telegram: delivers alerts
- Visitor → Brigade game: plays (evidence: `README.md`)
- Charmy app → Charmy artwork: uses mascot (evidence: `README.md`)
