# sid72020123/earthquake-data-analyzer architecture

> Architecture diagram of the GitHub repository sid72020123/earthquake-data-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sid72020123/earthquake-data-analyzer
- Repository: https://github.com/sid72020123/earthquake-data-analyzer

## Overview

1. **Overall architecture**
   - This repo is a **single-process Streamlit dashboard** backed by **local CSV files**. There is no separate API server, database, or cloud service in the tree.
   - The application is organized as a small pipeline: **CSV data → loading/cleaning → analytics/ML → Streamlit UI rendering**.

2. **Data layer**
   - The `data/` directory is the only persistent data source.
   - It contains:
     - `historical.csv` and `historical_processed.csv` for broader/global analysis,
     - yearly slices `year_2020.csv` through `year_2026.csv` for time-based views and filtering.
   - The app appears to use these files as offline datasets rather than fetching live earthquake feeds.

3. **Application entry point**
   - `main.py` is the dashboard orchestrator.
   - It likely defines the Streamlit layout, tabs, filters, and the order in which data loading, chart generation, mapping, and ML outputs are shown.
   - From the README, the UI is structured around multiple sections such as **Charts**, **Maps**, **Advanced**, **3D & Animation**, and **ML Trend Forecasting**.

4. **Data preparation boundary**
   - `load_data.py` is the ingestion/cleaning boundary between raw CSVs and the rest of the app.
   - Its role is likely to normalize columns, filter by date/country/magnitude, and provide reusable dataframes to the UI and visualization modules.
   - `historical_processed.csv` suggests there is some precomputed or cleaned dataset used to reduce runtime preprocessing.

5. **Visualization subsystem**
   - `visualization.py` is the main chart/map generation module.
   - It likely contains reusable functions for:
     - magnitude distributions,
     - correlation analysis,
     - time trends,
     - categorical summaries,
     - map layers and geographic summaries.
   - `plot.py` appears to be an additional plotting helper layer, probably for specialized figures or shared chart utilities.

6. **Geospatial rendering**
   - The map features are a distinct subsystem built on **Folium** and **streamlit-folium**, with country lookup support via **reverse_geocoder** and **pycountry**.
   - This boundary turns earthquake latitude/longitude data into interactive map outputs such as heatmaps, clustered markers, and magnitude/depth-based styling.
   - The geospatial layer is presentation-oriented; it does not appear to introduce a separate spatial database or GIS service.

7. **Statistical/charting stack**
   - The dashboard uses a mixed plotting stack:
     - **matplotlib** and **seaborn** for classic statistical plots,
     - **plotly** for interactive 3D/animated visuals,
     - likely Streamlit-native widgets for interactivity.
   - This indicates two rendering modes: static analytical charts and richer interactive visualizations.

8. **Machine learning subsystem**
   - `ml_prediction.py` encapsulates the forecasting logic for earthquake frequency trends.
   - The README describes a **moving average**-based approach over **monthly aggregated counts** from historical data, with train/test evaluation and a 12-month forecast.
   - This module is a separate analytical boundary from the dashboard visuals: it consumes the processed time series and emits predictions, error metrics, and forecast series for display in `main.py`.

9. **Model evaluation/testing**
   - `test_model.py` suggests an offline verification or evaluation script for the ML forecasting path.
   - This likely serves as a check on the prediction module rather than part of the interactive dashboard runtime.
   - In architecture terms, it is the validation boundary around the ML subsystem.

10. **Runtime and dependency implications**
   - The project is explicitly designed to run with **Streamlit** via `streamlit run main.py`, so the app is user-driven and executes in a single Python runtime.
   - The dependency set is important architecturally because it explains the output channels:
     - `pandas` for data shaping,
     - `scikit-learn` for ML metrics/utilities,
     - `folium`/`streamlit-folium` for maps,
     - `plotly` for interactive charts,
     - `matplotlib`/`seaborn` for statistical plots.
   - The README notes the ML model uses recent historical data and emphasizes limitations, which means the ML output should be diagrammed as an **auxiliary insight panel**, not as an operational prediction service.

11. **Key data flow to capture in a diagram**
   - A good architecture diagram would show:
     - **Local CSV datasets** feeding `load_data.py`,
     - cleaned/filtered data flowing into `main.py`,
     - branching into `visualization.py` / `plot.py` for charts and maps,
     - branching into `ml_prediction.py` for forecasting,
     - and the rendered results returning to the Streamlit UI.
   - The central boundary is the Streamlit app; the rest of the code is supporting analysis and presentation modules.

Main entry points: [`main.py`](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/main.py) (Dashboard), [`load_data.py`](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/load_data.py) (Loader), [`ml_prediction.py`](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/ml_prediction.py) (Forecasting), [`visualization.py`](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/visualization.py) (Charts & maps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data"]
  node_csv_data[("CSV data<br/>dataset")]
  node_historical_raw["Historical<br/>csv<br/>[historical.csv]"]
  node_historical_processed["Processed hist.<br/>csv"]
  node_time_slices["Year slices<br/>csv set"]
end

subgraph group_app["Application"]
  node_main_app["Dashboard<br/>Streamlit app<br/>[main.py]"]
  node_streamlit_ui["UI render<br/>presentation layer"]
end

subgraph group_analytics["Analytics"]
  node_load_data["Loader<br/>ingestion<br/>[load_data.py]"]
  node_visualization["Charts & maps<br/>viz engine<br/>[visualization.py]"]
  node_plot_utils["Plot helpers<br/>[plot.py]"]
  node_ml_prediction["Forecasting<br/>ML analysis<br/>[ml_prediction.py]"]
  node_test_model["Model test<br/>evaluation script<br/>[test_model.py]"]
end

node_csv_data -->|"source"| node_load_data
node_historical_raw -->|"historical input"| node_load_data
node_historical_processed -->|"clean input"| node_load_data
node_time_slices -->|"time views"| node_load_data
node_load_data -->|"prepared data"| node_main_app
node_main_app -->|"charts/maps"| node_visualization
node_main_app -->|"plot support"| node_plot_utils
node_main_app -->|"forecast panel"| node_ml_prediction
node_visualization -->|"render"| node_streamlit_ui
node_plot_utils -->|"render"| node_streamlit_ui
node_ml_prediction -->|"forecast output"| node_streamlit_ui
node_main_app -->|"orchestrates"| node_streamlit_ui
node_test_model -.->|"verify"| node_ml_prediction

click node_csv_data "https://github.com/sid72020123/earthquake-data-analyzer/tree/main/data"
click node_historical_raw "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/data/historical.csv"
click node_historical_processed "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/data/historical_processed.csv"
click node_main_app "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/main.py"
click node_load_data "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/load_data.py"
click node_visualization "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/visualization.py"
click node_plot_utils "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/plot.py"
click node_ml_prediction "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/ml_prediction.py"
click node_test_model "https://github.com/sid72020123/earthquake-data-analyzer/blob/main/test_model.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_csv_data,node_historical_raw,node_historical_processed,node_time_slices toneBlue
class node_main_app,node_streamlit_ui toneAmber
class node_load_data,node_visualization,node_plot_utils,node_ml_prediction,node_test_model toneMint
```

## Components

### Data

Local CSV datasets used by the dashboard

- [CSV data](https://github.com/sid72020123/earthquake-data-analyzer/tree/main/data): dataset · Local offline earthquake datasets stored under data/ · `data`
- [Historical](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/data/historical.csv): csv · Broad historical earthquake dataset · `data/historical.csv`
- [Processed hist.](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/data/historical_processed.csv): csv · Pre-cleaned historical dataset for faster analysis · `data/historical_processed.csv`
- **Year slices**: csv set · Yearly partitioned datasets used for time-based views

### Application

Streamlit entry point and UI orchestration

- [Dashboard](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/main.py): Streamlit app · Single-process dashboard entry point and orchestration layer · `main.py`
- **UI render**: presentation layer · Rendered Streamlit tabs, filters, charts, maps, and forecasts

### Analytics

Loading, visualization, and forecasting modules

- [Loader](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/load_data.py): ingestion · Boundary for CSV loading, cleaning, and filtering · `load_data.py`
- [Charts & maps](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/visualization.py): viz engine · Reusable analytical charts, summaries, and geographic views · `visualization.py`
- [Plot helpers](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/plot.py): plot helper · Supplementary plotting utilities for specialized figures · `plot.py`
- [Forecasting](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/ml_prediction.py): ML analysis · Monthly trend forecasting and evaluation logic · `ml_prediction.py`
- [Model test](https://github.com/sid72020123/earthquake-data-analyzer/blob/main/test_model.py): evaluation script · Offline verification of the forecasting path · `test_model.py`

## Connections

- CSV data → Loader: source · Raw datasets are ingested and normalized
- Historical → Loader: historical input · Main historical dataset feeds cleaning and aggregation
- Processed hist. → Loader: clean input · Preprocessed historical data can bypass repeated cleaning
- Year slices → Loader: time views · Yearly slices support filtering and segmented analysis
- Loader → Dashboard: prepared data · Cleaned dataframes flow into the dashboard orchestrator
- Dashboard → Charts & maps: charts/maps · Dashboard requests analytical plots and map views
- Dashboard → Plot helpers: plot support · Specialized figures use shared plotting helpers
- Dashboard → Forecasting: forecast panel · Dashboard invokes the forecasting module for trend insight
- Charts & maps → UI render: render · Charts and geographic summaries are presented in the UI
- Plot helpers → UI render: render · Supplementary plots are displayed in the dashboard
- Forecasting → UI render: forecast output · Predictions, metrics, and forecast series are surfaced to users
- Dashboard → UI render: orchestrates · Main.py composes the Streamlit layout and user flow
- Model test → Forecasting: verify · Offline checks exercise the forecasting logic
