# pred-javeriana/pred-platform architecture

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

- Interactive diagram: https://gitdiagram.com/pred-javeriana/pred-platform
- Repository: https://github.com/pred-javeriana/pred-platform

## Overview

PRED is a server-rendered forecasting platform: users upload data, configure a selection and launch a run; an embedded worker orchestrates the external prediction engine, while results are read back through a contract-validated repository and presented in the UI. The graph preserves ingestion, M2 selection, run execution, and M3 published-evidence stages, plus persistence and presentation layers. Relationships for unsampled subsystems are included only where the README or source index supports them; the excerpts do not expose every runtime call.

Main entry points: [`src/pred_platform/data/repository.py`](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/repository.py) (Data repository), [`src/pred_platform/app/main.py`](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/main.py) (FastAPI application), [`src/pred_platform/app/routers/results.py`](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/routers/results.py) (Result routes), [`src/pred_platform/app/ejecucion.py`](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/ejecucion.py) (Run configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_webapp["FastAPI application<br/>[main.py]"]
  node_execution_routes["Execution routes<br/>[execution.py]"]
  node_result_routes["Result routes<br/>[results.py]"]
end

subgraph group_domain["Forecast workflow"]
  node_ingestion_ui["Data ingestion UI<br/>[datos.py]"]
  node_selection_ui["M2 selection<br/>[seleccion.py]"]
  node_run_ui["Run configuration<br/>[ejecucion.py]"]
end

subgraph group_data["Data and contracts"]
  node_repository["Data repository<br/>[repository.py]"]
  node_data_factory["Source selection<br/>[factory.py]"]
  node_query["List query helpers<br/>[query.py]"]
  node_contract_v1["Contract v1 models<br/>[models.py]"]
  node_contract_v2["Contract v2 models<br/>[models_v2.py]"]
  node_dal_reads["DAL read queries<br/>[lectura.py]"]
  node_dal_runs["DAL run writes<br/>[ejecuciones.py]"]
  node_sqlite[("SQLite database")]
end

subgraph group_runtime["Run orchestration"]
  node_worker["Worker service<br/>[service.py]"]
  node_engine_adapter["Engine adapter<br/>[engine.py]"]
  node_engine["Prediction engine"]
end

subgraph group_evidence["Results and errors"]
  node_m3_ui["M3 results<br/>[resultados_m3.py]"]
  node_charts["Charts and result views<br/>[charts.py]"]
  node_evidence_data["Published evidence reads<br/>[m3_query.py]"]
  node_error_presentation["Error presentation<br/>[fallas.py]"]
  node_error_catalog["Error messages<br/>[mensajes.py]"]
end

node_user(("Platform user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"registers routes"| node_execution_routes
node_webapp -->|"registers routes"| node_result_routes
node_execution_routes -->|"delegates to"| node_run_ui
node_result_routes -->|"renders results"| node_m3_ui
node_result_routes -->|"uses views"| node_charts
node_webapp -->|"serves data UI"| node_ingestion_ui
node_ingestion_ui -->|"reads data"| node_repository
node_run_ui -->|"reads run data"| node_repository
node_run_ui -->|"controls runs"| node_worker
node_m3_ui -->|"reads published evidence"| node_repository
node_repository -->|"selects source"| node_data_factory
node_data_factory -->|"reads DAL"| node_dal_reads
node_repository -->|"filters and pages"| node_query
node_repository -->|"validates documents"| node_contract_v1
node_repository -->|"validates M3 documents"| node_contract_v2
node_dal_reads -->|"reads"| node_sqlite
node_dal_runs -->|"writes run state"| node_sqlite
node_worker -->|"runs engine"| node_engine_adapter
node_engine_adapter -->|"launches subprocess"| node_engine
node_worker -->|"persists run state"| node_dal_runs
node_repository -->|"reads M3 evidence"| node_evidence_data
node_evidence_data -->|"queries published data"| node_dal_reads
node_m3_ui -->|"formats failures"| node_error_presentation
node_error_presentation -->|"translates codes"| node_error_catalog

click node_webapp "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/main.py"
click node_execution_routes "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/routers/execution.py"
click node_result_routes "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/routers/results.py"
click node_ingestion_ui "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/datos.py"
click node_selection_ui "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/seleccion.py"
click node_run_ui "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/ejecucion.py"
click node_m3_ui "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/resultados_m3.py"
click node_charts "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/charts.py"
click node_repository "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/repository.py"
click node_data_factory "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/factory.py"
click node_query "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/query.py"
click node_contract_v1 "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/contract/models.py"
click node_contract_v2 "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/contract/models_v2.py"
click node_dal_reads "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/dal/lectura.py"
click node_dal_runs "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/dal/ejecuciones.py"
click node_worker "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/worker/service.py"
click node_engine_adapter "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/worker/engine.py"
click node_evidence_data "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/m3_query.py"
click node_error_presentation "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/fallas.py"
click node_error_catalog "https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/mensajes.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_webapp,node_execution_routes,node_result_routes,node_user toneBlue
class node_ingestion_ui,node_selection_ui,node_run_ui toneAmber
class node_repository,node_data_factory,node_query,node_contract_v1,node_contract_v2,node_dal_reads,node_dal_runs,node_sqlite toneMint
class node_worker,node_engine_adapter,node_engine toneRose
class node_m3_ui,node_charts,node_evidence_data,node_error_presentation,node_error_catalog toneIndigo
```

## Components

### Web interface

- [FastAPI application](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/main.py): `src/pred_platform/app/main.py`
- [Execution routes](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/routers/execution.py): `src/pred_platform/app/routers/execution.py`
- [Result routes](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/routers/results.py): `src/pred_platform/app/routers/results.py`

### Forecast workflow

- [Data ingestion UI](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/datos.py): `src/pred_platform/app/datos.py`
- [M2 selection](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/seleccion.py): `src/pred_platform/app/seleccion.py`
- [Run configuration](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/ejecucion.py): `src/pred_platform/app/ejecucion.py`

### Data and contracts

- [Data repository](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/repository.py): `src/pred_platform/data/repository.py`
- [Source selection](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/factory.py): `src/pred_platform/data/factory.py`
- [List query helpers](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/query.py): `src/pred_platform/data/query.py`
- [Contract v1 models](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/contract/models.py): `src/pred_platform/contract/models.py`
- [Contract v2 models](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/contract/models_v2.py): `src/pred_platform/contract/models_v2.py`
- [DAL read queries](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/dal/lectura.py): `src/pred_platform/dal/lectura.py`
- [DAL run writes](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/dal/ejecuciones.py): `src/pred_platform/dal/ejecuciones.py`
- **SQLite database**

### Run orchestration

- [Worker service](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/worker/service.py): `src/pred_platform/worker/service.py`
- [Engine adapter](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/worker/engine.py): `src/pred_platform/worker/engine.py`
- **Prediction engine**

### Results and errors

- [M3 results](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/resultados_m3.py): `src/pred_platform/app/resultados_m3.py`
- [Charts and result views](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/app/charts.py): `src/pred_platform/app/charts.py`
- [Published evidence reads](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/data/m3_query.py): `src/pred_platform/data/m3_query.py`
- [Error presentation](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/fallas.py): `src/pred_platform/fallas.py`
- [Error messages](https://github.com/pred-javeriana/pred-platform/blob/main/src/pred_platform/mensajes.py): `src/pred_platform/mensajes.py`

### Other components

- **Platform user**

## Connections

- Platform user → FastAPI application: uses
- FastAPI application → Execution routes: registers routes (evidence: `src/pred_platform/app/main.py`)
- FastAPI application → Result routes: registers routes (evidence: `src/pred_platform/app/main.py`)
- Execution routes → Run configuration: delegates to (evidence: `src/pred_platform/app/routers/execution.py`)
- Result routes → M3 results: renders results (evidence: `src/pred_platform/app/routers/results.py`)
- Result routes → Charts and result views: uses views (evidence: `src/pred_platform/app/routers/results.py`)
- FastAPI application → Data ingestion UI: serves data UI (evidence: `src/pred_platform/app/main.py`)
- Data ingestion UI → Data repository: reads data (evidence: `src/pred_platform/app/datos.py`)
- Run configuration → Data repository: reads run data (evidence: `src/pred_platform/app/ejecucion.py`)
- Run configuration → Worker service: controls runs (evidence: `src/pred_platform/app/ejecucion.py`)
- M3 results → Data repository: reads published evidence (evidence: `src/pred_platform/app/resultados_m3.py`)
- Data repository → Source selection: selects source
- Source selection → DAL read queries: reads DAL
- Data repository → List query helpers: filters and pages (evidence: `src/pred_platform/data/query.py`)
- Data repository → Contract v1 models: validates documents (evidence: `src/pred_platform/data/repository.py`)
- Data repository → Contract v2 models: validates M3 documents (evidence: `src/pred_platform/data/repository.py`)
- DAL read queries → SQLite database: reads (evidence: `src/pred_platform/dal/lectura.py`)
- DAL run writes → SQLite database: writes run state
- Worker service → Engine adapter: runs engine (evidence: `src/pred_platform/worker/service.py`)
- Engine adapter → Prediction engine: launches subprocess
- Worker service → DAL run writes: persists run state (evidence: `src/pred_platform/worker/service.py`)
- Data repository → Published evidence reads: reads M3 evidence (evidence: `src/pred_platform/data/repository.py`)
- Published evidence reads → DAL read queries: queries published data (evidence: `src/pred_platform/data/m3_query.py`)
- M3 results → Error presentation: formats failures (evidence: `src/pred_platform/fallas.py`)
- Error presentation → Error messages: translates codes (evidence: `src/pred_platform/fallas.py`)