# koutammoulaye/geoport-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/koutammoulaye/geoport-intelligence
- Repository: https://github.com/koutammoulaye/geoport-intelligence

## Overview

GeoPort Intelligence combines geopolitical, port, trade, and macroeconomic data to assess maritime risk and predict container throughput. Its main user workflow is to explore live indicators and submit risk or TEU scenarios through the dashboard or REST API, then inspect predictions and model comparisons. Internally, the documented pipeline prepares features for classification and regression; model training and evaluation produce artifacts and comparison results. The README also describes SHAP interpretability and live market/GDELT indicators. Some subsystem links are documented rather than visible in sampled runtime code.

Main entry points: [`src/data_pipeline.py`](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/data_pipeline.py) (Feature pipeline), [`dashboard/app.py`](https://github.com/koutammoulaye/geoport-intelligence/blob/main/dashboard/app.py) (Interactive dashboard), [`data/processed`](https://github.com/koutammoulaye/geoport-intelligence/tree/main/data/processed) (Processed datasets), [`models_saved`](https://github.com/koutammoulaye/geoport-intelligence/tree/main/models_saved) (Model artifacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_gdelt_ingest["GDELT ingestion<br/>[fetch_gdelt.py]"]
  node_feature_pipeline["Feature pipeline<br/>[data_pipeline.py]"]
  node_realtime["Live indicators<br/>[realtime_apis.py]"]
end

subgraph group_analytics["Modeling and evaluation"]
  node_clf_training["Risk classifier<br/>[classification.py]"]
  node_reg_training["TEU regression<br/>[regression.py]"]
  node_dl_training["Keras models<br/>[deep_learning.py]"]
  node_evaluation["Model comparison<br/>[evaluation.py]"]
end

subgraph group_serving["Prediction services"]
  node_api["REST prediction API<br/>[main.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_experience["User experience"]
  node_dashboard["Interactive dashboard<br/>[app.py]"]
  node_shap["SHAP explanations<br/>[app.py]"]
end

subgraph group_state["Persisted artifacts"]
  node_model_artifacts[("Model artifacts")]
  node_processed_data[("Processed datasets")]
  node_comparison_results["Evaluation results"]
end

node_analyst(("Analyst"))
node_gdelt_source(("GDELT events"))
node_ucdp_source(("UCDP conflicts"))
node_port_source(("Port index"))
node_unctad_source(("UNCTAD traffic"))
node_wb_source(("World Bank GDP"))
node_ais_source(("AIS positions"))
node_market_source(("Market data"))
node_gdelt_live(("Live GDELT"))

node_gdelt_source -->|"provides events"| node_gdelt_ingest
node_gdelt_ingest -->|"writes events"| node_processed_data
node_gdelt_source -->|"provides features"| node_feature_pipeline
node_ucdp_source -->|"provides conflicts"| node_feature_pipeline
node_port_source -->|"provides port data"| node_feature_pipeline
node_unctad_source -->|"provides traffic"| node_feature_pipeline
node_wb_source -->|"provides GDP"| node_feature_pipeline
node_ais_source -->|"provides positions"| node_feature_pipeline
node_feature_pipeline -->|"builds datasets"| node_processed_data
node_processed_data -->|"loads training data"| node_clf_training
node_clf_training -->|"saves model"| node_model_artifacts
node_processed_data -.->|"prepares regression"| node_reg_training
node_reg_training -.->|"saves model"| node_model_artifacts
node_processed_data -.->|"trains MLPs"| node_dl_training
node_dl_training -->|"saves models"| node_model_artifacts
node_clf_training -.->|"reports metrics"| node_evaluation
node_reg_training -.->|"reports metrics"| node_evaluation
node_dl_training -->|"contributes results"| node_evaluation
node_evaluation -->|"exports results"| node_comparison_results
node_analyst -->|"explores"| node_dashboard
node_analyst -->|"submits requests"| node_api
node_dashboard -->|"fetches indicators"| node_realtime
node_market_source -->|"supplies prices"| node_realtime
node_gdelt_live -->|"supplies articles"| node_realtime
node_api -->|"validates input"| node_schemas
node_api -.->|"loads models"| node_model_artifacts
node_api -->|"reads results"| node_comparison_results
node_dashboard -.->|"uses predictors"| node_model_artifacts
node_dashboard -.->|"shows comparisons"| node_comparison_results
node_dashboard -.->|"renders explanations"| node_shap

click node_gdelt_ingest "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/fetch_gdelt.py"
click node_feature_pipeline "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/data_pipeline.py"
click node_realtime "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/realtime_apis.py"
click node_clf_training "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/classification.py"
click node_reg_training "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/regression.py"
click node_dl_training "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/deep_learning.py"
click node_evaluation "https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/evaluation.py"
click node_api "https://github.com/koutammoulaye/geoport-intelligence/blob/main/api/main.py"
click node_schemas "https://github.com/koutammoulaye/geoport-intelligence/blob/main/api/schemas.py"
click node_dashboard "https://github.com/koutammoulaye/geoport-intelligence/blob/main/dashboard/app.py"
click node_shap "https://github.com/koutammoulaye/geoport-intelligence/blob/main/dashboard/app.py"
click node_model_artifacts "https://github.com/koutammoulaye/geoport-intelligence/tree/main/models_saved"
click node_processed_data "https://github.com/koutammoulaye/geoport-intelligence/tree/main/data/processed"
click node_comparison_results "https://github.com/koutammoulaye/geoport-intelligence/tree/main/data/processed"

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_gdelt_ingest,node_feature_pipeline,node_realtime toneBlue
class node_clf_training,node_reg_training,node_dl_training,node_evaluation toneAmber
class node_api,node_schemas toneMint
class node_dashboard,node_shap toneRose
class node_model_artifacts,node_processed_data,node_comparison_results,node_analyst,node_gdelt_source,node_ucdp_source,node_port_source,node_unctad_source,node_wb_source,node_ais_source,node_market_source,node_gdelt_live toneIndigo
```

## Components

### Data ingestion

- [GDELT ingestion](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/fetch_gdelt.py): `src/fetch_gdelt.py`
- [Feature pipeline](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/data_pipeline.py): `src/data_pipeline.py`
- [Live indicators](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/realtime_apis.py): `src/realtime_apis.py`

### Modeling and evaluation

- [Risk classifier](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/classification.py): `src/models/classification.py`
- [TEU regression](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/regression.py): `src/models/regression.py`
- [Keras models](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/models/deep_learning.py): `src/models/deep_learning.py`
- [Model comparison](https://github.com/koutammoulaye/geoport-intelligence/blob/main/src/evaluation.py): `src/evaluation.py`

### Prediction services

- [REST prediction API](https://github.com/koutammoulaye/geoport-intelligence/blob/main/api/main.py): `api/main.py`
- [Request schemas](https://github.com/koutammoulaye/geoport-intelligence/blob/main/api/schemas.py): `api/schemas.py`

### User experience

- [Interactive dashboard](https://github.com/koutammoulaye/geoport-intelligence/blob/main/dashboard/app.py): `dashboard/app.py`
- [SHAP explanations](https://github.com/koutammoulaye/geoport-intelligence/blob/main/dashboard/app.py): `dashboard/app.py`

### Persisted artifacts

- [Model artifacts](https://github.com/koutammoulaye/geoport-intelligence/tree/main/models_saved): `models_saved`
- [Processed datasets](https://github.com/koutammoulaye/geoport-intelligence/tree/main/data/processed): `data/processed`
- [Evaluation results](https://github.com/koutammoulaye/geoport-intelligence/tree/main/data/processed): `data/processed`

### Other components

- **Analyst**
- **GDELT events**
- **UCDP conflicts**
- **Port index**
- **UNCTAD traffic**
- **World Bank GDP**
- **AIS positions**
- **Market data**
- **Live GDELT**

## Connections

- GDELT events → GDELT ingestion: provides events (evidence: `README.md`)
- GDELT ingestion → Processed datasets: writes events (evidence: `src/fetch_gdelt.py`)
- GDELT events → Feature pipeline: provides features (evidence: `README.md`)
- UCDP conflicts → Feature pipeline: provides conflicts (evidence: `README.md`)
- Port index → Feature pipeline: provides port data (evidence: `README.md`)
- UNCTAD traffic → Feature pipeline: provides traffic (evidence: `README.md`)
- World Bank GDP → Feature pipeline: provides GDP (evidence: `README.md`)
- AIS positions → Feature pipeline: provides positions (evidence: `README.md`)
- Feature pipeline → Processed datasets: builds datasets (evidence: `README.md`)
- Processed datasets → Risk classifier: loads training data (evidence: `src/models/classification.py`)
- Risk classifier → Model artifacts: saves model (evidence: `README.md`)
- Processed datasets → TEU regression: prepares regression (evidence: `README.md`)
- TEU regression → Model artifacts: saves model (evidence: `README.md`)
- Processed datasets → Keras models: trains MLPs (evidence: `README.md`)
- Keras models → Model artifacts: saves models (evidence: `src/models/deep_learning.py`)
- Risk classifier → Model comparison: reports metrics (evidence: `README.md`)
- TEU regression → Model comparison: reports metrics (evidence: `README.md`)
- Keras models → Model comparison: contributes results (evidence: `src/evaluation.py`)
- Model comparison → Evaluation results: exports results (evidence: `src/evaluation.py`)
- Analyst → Interactive dashboard: explores (evidence: `README.md`)
- Analyst → REST prediction API: submits requests (evidence: `README.md`)
- Interactive dashboard → Live indicators: fetches indicators (evidence: `dashboard/app.py`)
- Market data → Live indicators: supplies prices (evidence: `src/realtime_apis.py`)
- Live GDELT → Live indicators: supplies articles (evidence: `src/realtime_apis.py`)
- REST prediction API → Request schemas: validates input (evidence: `api/main.py`)
- REST prediction API → Model artifacts: loads models (evidence: `README.md`)
- REST prediction API → Evaluation results: reads results (evidence: `api/main.py`)
- Interactive dashboard → Model artifacts: uses predictors (evidence: `README.md`)
- Interactive dashboard → Evaluation results: shows comparisons (evidence: `README.md`)
- Interactive dashboard → SHAP explanations: renders explanations (evidence: `README.md`)