# franco7scala/disasterchain architecture

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

## Overview

DisasterChain builds a global disaster-event dataset from EM-DAT and GDIS, enriching events with resolved locations, weather, news-derived narratives and satellite observations before exporting a portable JSON/image package. The principal workflow is launched through `src/main.py` and planned or executed by `src/run_release_pipeline.py`. The graph preserves the documented stages and major product branches; some stage links are documented at pipeline level because the corresponding implementation was not sampled. `src/main.py` also contains weather-fetching behavior, while reusable engines and record-building layers are shown separately.

Main entry points: [`src/run_release_pipeline.py`](https://github.com/franco7scala/disasterchain/blob/main/src/run_release_pipeline.py) (Release pipeline), [`src/fetch_multimodal_satellite_batch.py`](https://github.com/franco7scala/disasterchain/blob/main/src/fetch_multimodal_satellite_batch.py) (Satellite batch retrieval), [`src/export_final_event_dataset.py`](https://github.com/franco7scala/disasterchain/blob/main/src/export_final_event_dataset.py) (Final dataset export), [`src/main.py`](https://github.com/franco7scala/disasterchain/blob/main/src/main.py) (CLI entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Release orchestration"]
  node_entrypoint["CLI entry point<br/>[main.py]"]
  node_pipeline["Release pipeline"]
end

subgraph group_events["Event data and geocoding"]
  node_merge["Base event merge"]
  node_location_clean["LLM location cleaning"]
  node_query_prep["Geocoding query prep"]
  node_geocoding["Geocoding resolution"]
  node_text_geocoding["Text query geocoding"]
end

subgraph group_context["Weather and narratives"]
  node_weather["Weather enrichment"]
  node_weather_engine["Weather normalization<br/>[weather_data.py]"]
  node_news["News collection"]
  node_news_engine["News retrieval engine<br/>[news_engine.py]"]
  node_summaries["Event news summaries"]
  node_causal["Causal chain generation"]
  node_reasoner["Local LLM reasoner<br/>[reasoner.py]"]
end

subgraph group_observation["Satellite observations"]
  node_satellite_batch["Satellite batch retrieval"]
  node_satellite_engine["Satellite processing engine"]
  node_satellite_selection["Satellite event selection"]
end

subgraph group_publication["Dataset assembly"]
  node_assembly["Final event assembly"]
  node_records["Public record builder"]
  node_export["Final dataset export"]
end

node_user(("Dataset operator"))
node_rawdata["EM-DAT and GDIS"]
node_sentinel["Copernicus Sentinel Hub"]
node_package["JSON and image package"]

node_user -->|"runs"| node_entrypoint
node_entrypoint -->|"launches"| node_pipeline
node_rawdata -->|"supplies inputs"| node_merge
node_pipeline -->|"runs merge"| node_merge
node_pipeline -->|"runs cleaning"| node_location_clean
node_pipeline -->|"runs query prep"| node_query_prep
node_pipeline -->|"runs resolution"| node_geocoding
node_pipeline -->|"runs geocoding"| node_text_geocoding
node_pipeline -->|"runs enrichment"| node_weather
node_pipeline -->|"runs collection"| node_news
node_pipeline -->|"runs summaries"| node_summaries
node_pipeline -->|"runs reasoning"| node_causal
node_pipeline -->|"runs retrieval"| node_satellite_batch
node_pipeline -->|"runs export"| node_export
node_location_clean -->|"prepares queries"| node_query_prep
node_weather -->|"normalizes data"| node_weather_engine
node_news -->|"retrieves articles"| node_news_engine
node_summaries -->|"generates summaries"| node_reasoner
node_causal -->|"generates chains"| node_reasoner
node_satellite_batch -->|"processes scenes"| node_satellite_engine
node_satellite_engine -->|"requests imagery"| node_sentinel
node_satellite_batch -->|"selects events"| node_satellite_selection
node_assembly -->|"builds records"| node_records
node_export -->|"formats records"| node_records
node_export -->|"writes package"| node_package

click node_entrypoint "https://github.com/franco7scala/disasterchain/blob/main/src/main.py"
click node_pipeline "https://github.com/franco7scala/disasterchain/blob/main/src/run_release_pipeline.py"
click node_merge "https://github.com/franco7scala/disasterchain/blob/main/src/build_base_dataset.py"
click node_location_clean "https://github.com/franco7scala/disasterchain/blob/main/src/clean_emdat_locations_with_llm.py"
click node_query_prep "https://github.com/franco7scala/disasterchain/blob/main/src/prepare_llm_location_nominatim_queries.py"
click node_geocoding "https://github.com/franco7scala/disasterchain/blob/main/src/resolve_final_geocoding.py"
click node_text_geocoding "https://github.com/franco7scala/disasterchain/blob/main/src/geocode_text_queries.py"
click node_weather "https://github.com/franco7scala/disasterchain/blob/main/src/fetch_weather_batch.py"
click node_weather_engine "https://github.com/franco7scala/disasterchain/blob/main/src/support/weather_data.py"
click node_news "https://github.com/franco7scala/disasterchain/blob/main/src/build_news_dataset_from_geocoded_events.py"
click node_news_engine "https://github.com/franco7scala/disasterchain/blob/main/src/support/news_engine.py"
click node_summaries "https://github.com/franco7scala/disasterchain/blob/main/src/generate_event_news_summaries.py"
click node_causal "https://github.com/franco7scala/disasterchain/blob/main/src/generate_event_causal_chains.py"
click node_reasoner "https://github.com/franco7scala/disasterchain/blob/main/src/support/reasoner.py"
click node_satellite_batch "https://github.com/franco7scala/disasterchain/blob/main/src/fetch_multimodal_satellite_batch.py"
click node_satellite_engine "https://github.com/franco7scala/disasterchain/blob/main/src/support/multimodal_satellite_engine.py"
click node_satellite_selection "https://github.com/franco7scala/disasterchain/blob/main/src/support/satellite_selection.py"
click node_assembly "https://github.com/franco7scala/disasterchain/blob/main/src/assemble_final_event_dataset.py"
click node_records "https://github.com/franco7scala/disasterchain/blob/main/src/support/final_dataset_records.py"
click node_export "https://github.com/franco7scala/disasterchain/blob/main/src/export_final_event_dataset.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_entrypoint,node_pipeline toneBlue
class node_merge,node_location_clean,node_query_prep,node_geocoding,node_text_geocoding toneAmber
class node_weather,node_weather_engine,node_news,node_news_engine,node_summaries,node_causal,node_reasoner toneMint
class node_satellite_batch,node_satellite_engine,node_satellite_selection toneRose
class node_assembly,node_records,node_export,node_user,node_rawdata,node_sentinel,node_package toneIndigo
```

## Components

### Release orchestration

- [CLI entry point](https://github.com/franco7scala/disasterchain/blob/main/src/main.py): `src/main.py`
- [Release pipeline](https://github.com/franco7scala/disasterchain/blob/main/src/run_release_pipeline.py): `src/run_release_pipeline.py`

### Event data and geocoding

- [Base event merge](https://github.com/franco7scala/disasterchain/blob/main/src/build_base_dataset.py): `src/build_base_dataset.py`
- [LLM location cleaning](https://github.com/franco7scala/disasterchain/blob/main/src/clean_emdat_locations_with_llm.py): `src/clean_emdat_locations_with_llm.py`
- [Geocoding query prep](https://github.com/franco7scala/disasterchain/blob/main/src/prepare_llm_location_nominatim_queries.py): `src/prepare_llm_location_nominatim_queries.py`
- [Geocoding resolution](https://github.com/franco7scala/disasterchain/blob/main/src/resolve_final_geocoding.py): `src/resolve_final_geocoding.py`
- [Text query geocoding](https://github.com/franco7scala/disasterchain/blob/main/src/geocode_text_queries.py): `src/geocode_text_queries.py`

### Weather and narratives

- [Weather enrichment](https://github.com/franco7scala/disasterchain/blob/main/src/fetch_weather_batch.py): `src/fetch_weather_batch.py`
- [Weather normalization](https://github.com/franco7scala/disasterchain/blob/main/src/support/weather_data.py): `src/support/weather_data.py`
- [News collection](https://github.com/franco7scala/disasterchain/blob/main/src/build_news_dataset_from_geocoded_events.py): `src/build_news_dataset_from_geocoded_events.py`
- [News retrieval engine](https://github.com/franco7scala/disasterchain/blob/main/src/support/news_engine.py): `src/support/news_engine.py`
- [Event news summaries](https://github.com/franco7scala/disasterchain/blob/main/src/generate_event_news_summaries.py): `src/generate_event_news_summaries.py`
- [Causal chain generation](https://github.com/franco7scala/disasterchain/blob/main/src/generate_event_causal_chains.py): `src/generate_event_causal_chains.py`
- [Local LLM reasoner](https://github.com/franco7scala/disasterchain/blob/main/src/support/reasoner.py): `src/support/reasoner.py`

### Satellite observations

- [Satellite batch retrieval](https://github.com/franco7scala/disasterchain/blob/main/src/fetch_multimodal_satellite_batch.py): `src/fetch_multimodal_satellite_batch.py`
- [Satellite processing engine](https://github.com/franco7scala/disasterchain/blob/main/src/support/multimodal_satellite_engine.py): `src/support/multimodal_satellite_engine.py`
- [Satellite event selection](https://github.com/franco7scala/disasterchain/blob/main/src/support/satellite_selection.py): `src/support/satellite_selection.py`

### Dataset assembly

- [Final event assembly](https://github.com/franco7scala/disasterchain/blob/main/src/assemble_final_event_dataset.py): `src/assemble_final_event_dataset.py`
- [Public record builder](https://github.com/franco7scala/disasterchain/blob/main/src/support/final_dataset_records.py): `src/support/final_dataset_records.py`
- [Final dataset export](https://github.com/franco7scala/disasterchain/blob/main/src/export_final_event_dataset.py): `src/export_final_event_dataset.py`

### Other components

- **Dataset operator**
- **EM-DAT and GDIS**
- **Copernicus Sentinel Hub**
- **JSON and image package**

## Connections

- Dataset operator → CLI entry point: runs
- CLI entry point → Release pipeline: launches (evidence: `src/main.py`)
- EM-DAT and GDIS → Base event merge: supplies inputs
- Release pipeline → Base event merge: runs merge (evidence: `src/run_release_pipeline.py`)
- Release pipeline → LLM location cleaning: runs cleaning
- Release pipeline → Geocoding query prep: runs query prep
- Release pipeline → Geocoding resolution: runs resolution
- Release pipeline → Text query geocoding: runs geocoding
- Release pipeline → Weather enrichment: runs enrichment
- Release pipeline → News collection: runs collection
- Release pipeline → Event news summaries: runs summaries
- Release pipeline → Causal chain generation: runs reasoning
- Release pipeline → Satellite batch retrieval: runs retrieval
- Release pipeline → Final dataset export: runs export (evidence: `src/export_final_event_dataset.py`)
- LLM location cleaning → Geocoding query prep: prepares queries (evidence: `src/prepare_llm_location_nominatim_queries.py`)
- Weather enrichment → Weather normalization: normalizes data (evidence: `src/support/weather_data.py`)
- News collection → News retrieval engine: retrieves articles (evidence: `src/build_news_dataset_from_geocoded_events.py`)
- Event news summaries → Local LLM reasoner: generates summaries (evidence: `src/generate_event_news_summaries.py`)
- Causal chain generation → Local LLM reasoner: generates chains (evidence: `src/generate_event_causal_chains.py`)
- Satellite batch retrieval → Satellite processing engine: processes scenes (evidence: `src/fetch_multimodal_satellite_batch.py`)
- Satellite processing engine → Copernicus Sentinel Hub: requests imagery
- Satellite batch retrieval → Satellite event selection: selects events (evidence: `src/fetch_multimodal_satellite_batch.py`)
- Final event assembly → Public record builder: builds records (evidence: `src/assemble_final_event_dataset.py`)
- Final dataset export → Public record builder: formats records (evidence: `src/export_final_event_dataset.py`)
- Final dataset export → JSON and image package: writes package
