# baneado85/geopredia architecture

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

- Interactive diagram: https://gitdiagram.com/baneado85/geopredia
- Repository: https://github.com/baneado85/geopredia

## Overview

GeoPredIA is a georisk decision hub: users compare zone evaluations, inspect specialist explanations and evidence, then record a human review. The main runtime is FastAPI with local SQLite; official scoring is documented as a SAC responsibility, while CSV snapshots are imported without recalculation. Telemetry, optional BPA/HANA adapters, and a separate CAP dataset service are additional product branches. Relationships reflect the README and shown source references; several integration connections are explicitly unverified.

Main entry points: [`agents/api.py`](https://github.com/baneado85/geopredia/blob/main/agents/api.py) (FastAPI), [`agents/engine.py`](https://github.com/baneado85/geopredia/blob/main/agents/engine.py) (Agent engine), [`agents/store.py`](https://github.com/baneado85/geopredia/blob/main/agents/store.py) (SQLite records), [`frontend/console/app.js`](https://github.com/baneado85/geopredia/blob/main/frontend/console/app.js) (Web console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_console["Web console<br/>[app.js]"]
  node_api["FastAPI<br/>[api.py]"]
  node_review["Human review<br/>[api.py]"]
end

subgraph group_evaluation["Evaluation and agents"]
  node_csv_import["Snapshot import<br/>[sac.py]"]
  node_engine["Agent engine<br/>[engine.py]"]
  node_specialists["Specialists"]
  node_coordinator["Coordinator"]
end

subgraph group_records["Evidence and records"]
  node_zone_data["Zone data<br/>[data.py]"]
  node_store[("SQLite records<br/>[store.py]")]
  node_audit[("Audit history<br/>[store.py]")]
  node_telemetry["Telemetry intake<br/>[api.py]"]
end

subgraph group_integrations["External integrations"]
  node_sac["SAC scoring"]
  node_llm["Groq LLM"]
  node_bpa_adapter["BPA adapter<br/>[integrations.py]"]
  node_hana_reader["HANA reader<br/>[integrations.py]"]
  node_hana_publisher["HANA publisher<br/>[hana_publish.py]"]
end

subgraph group_dataset["Official dataset service"]
  node_cap_service["CAP OData service"]
  node_cap_db[("CAP SQLite dataset<br/>[schema.cds]")]
end

node_reviewer(("Reviewer"))
node_sensor(("ESP32 / simulator"))
node_bpa["SAP BPA"]
node_hana[("SAP HANA")]

node_reviewer -->|"uses"| node_console
node_console -->|"calls"| node_api
node_sac -->|"exports snapshot"| node_csv_import
node_csv_import -->|"imports evaluations"| node_api
node_api -->|"reads zone data"| node_zone_data
node_api -->|"runs agents"| node_engine
node_engine -.->|"analyzes evidence"| node_specialists
node_engine -->|"optionally requests"| node_llm
node_engine -.->|"coordinates findings"| node_coordinator
node_api -->|"persists records"| node_store
node_reviewer -->|"submits decision"| node_review
node_review -->|"records review"| node_store
node_store -->|"appends events"| node_audit
node_sensor -->|"sends readings"| node_telemetry
node_telemetry -->|"stores readings"| node_store
node_api -->|"starts workflow"| node_bpa_adapter
node_bpa_adapter -->|"starts instance"| node_bpa
node_bpa -->|"sends callback"| node_review
node_api -->|"imports zones"| node_hana_reader
node_hana_reader -->|"reads view"| node_hana
node_api -->|"publishes events"| node_hana_publisher
node_hana_publisher -->|"writes event batch"| node_hana
node_cap_service -.->|"serves dataset"| node_cap_db

click node_console "https://github.com/baneado85/geopredia/blob/main/frontend/console/app.js"
click node_api "https://github.com/baneado85/geopredia/blob/main/agents/api.py"
click node_sac "https://github.com/baneado85/geopredia/tree/main/analytics"
click node_csv_import "https://github.com/baneado85/geopredia/blob/main/agents/sac.py"
click node_zone_data "https://github.com/baneado85/geopredia/blob/main/agents/data.py"
click node_engine "https://github.com/baneado85/geopredia/blob/main/agents/engine.py"
click node_specialists "https://github.com/baneado85/geopredia/tree/main/agents/agents"
click node_coordinator "https://github.com/baneado85/geopredia/blob/main/agents/agents/coordinator_agent.py"
click node_store "https://github.com/baneado85/geopredia/blob/main/agents/store.py"
click node_review "https://github.com/baneado85/geopredia/blob/main/agents/api.py"
click node_audit "https://github.com/baneado85/geopredia/blob/main/agents/store.py"
click node_telemetry "https://github.com/baneado85/geopredia/blob/main/agents/api.py"
click node_bpa_adapter "https://github.com/baneado85/geopredia/blob/main/agents/integrations.py"
click node_hana_reader "https://github.com/baneado85/geopredia/blob/main/agents/integrations.py"
click node_hana_publisher "https://github.com/baneado85/geopredia/blob/main/agents/hana_publish.py"
click node_cap_service "https://github.com/baneado85/geopredia/blob/main/backend/srv/geopredia-service.js"
click node_cap_db "https://github.com/baneado85/geopredia/blob/main/backend/db/schema.cds"

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_console,node_api,node_review,node_reviewer toneBlue
class node_csv_import,node_engine,node_specialists,node_coordinator,node_hana toneAmber
class node_zone_data,node_store,node_audit,node_telemetry toneMint
class node_sac,node_llm,node_bpa_adapter,node_hana_reader,node_hana_publisher toneRose
class node_cap_service,node_cap_db,node_sensor,node_bpa toneIndigo
```

## Components

### User experience

- [Web console](https://github.com/baneado85/geopredia/blob/main/frontend/console/app.js): `frontend/console/app.js`
- [FastAPI](https://github.com/baneado85/geopredia/blob/main/agents/api.py): `agents/api.py`
- [Human review](https://github.com/baneado85/geopredia/blob/main/agents/api.py): `agents/api.py`

### Evaluation and agents

- [Snapshot import](https://github.com/baneado85/geopredia/blob/main/agents/sac.py): `agents/sac.py`
- [Agent engine](https://github.com/baneado85/geopredia/blob/main/agents/engine.py): `agents/engine.py`
- [Specialists](https://github.com/baneado85/geopredia/tree/main/agents/agents): `agents/agents`
- [Coordinator](https://github.com/baneado85/geopredia/blob/main/agents/agents/coordinator_agent.py): `agents/agents/coordinator_agent.py`

### Evidence and records

- [Zone data](https://github.com/baneado85/geopredia/blob/main/agents/data.py): `agents/data.py`
- [SQLite records](https://github.com/baneado85/geopredia/blob/main/agents/store.py): `agents/store.py`
- [Audit history](https://github.com/baneado85/geopredia/blob/main/agents/store.py): `agents/store.py`
- [Telemetry intake](https://github.com/baneado85/geopredia/blob/main/agents/api.py): `agents/api.py`

### External integrations

- [SAC scoring](https://github.com/baneado85/geopredia/tree/main/analytics): `analytics`
- **Groq LLM**
- [BPA adapter](https://github.com/baneado85/geopredia/blob/main/agents/integrations.py): `agents/integrations.py`
- [HANA reader](https://github.com/baneado85/geopredia/blob/main/agents/integrations.py): `agents/integrations.py`
- [HANA publisher](https://github.com/baneado85/geopredia/blob/main/agents/hana_publish.py): `agents/hana_publish.py`

### Official dataset service

- [CAP OData service](https://github.com/baneado85/geopredia/blob/main/backend/srv/geopredia-service.js): `backend/srv/geopredia-service.js`
- [CAP SQLite dataset](https://github.com/baneado85/geopredia/blob/main/backend/db/schema.cds): `backend/db/schema.cds`

### Other components

- **Reviewer**
- **ESP32 / simulator**
- **SAP BPA**
- **SAP HANA**

## Connections

- Reviewer → Web console: uses (evidence: `README.md`)
- Web console → FastAPI: calls (evidence: `README.md`)
- SAC scoring → Snapshot import: exports snapshot (evidence: `README.md`)
- Snapshot import → FastAPI: imports evaluations (evidence: `agents/api.py`)
- FastAPI → Zone data: reads zone data (evidence: `agents/api.py`)
- FastAPI → Agent engine: runs agents (evidence: `agents/api.py`)
- Agent engine → Specialists: analyzes evidence
- Agent engine → Groq LLM: optionally requests (evidence: `agents/engine.py`)
- Agent engine → Coordinator: coordinates findings
- FastAPI → SQLite records: persists records (evidence: `README.md`)
- Reviewer → Human review: submits decision (evidence: `README.md`)
- Human review → SQLite records: records review (evidence: `agents/store.py`)
- SQLite records → Audit history: appends events (evidence: `agents/store.py`)
- ESP32 / simulator → Telemetry intake: sends readings (evidence: `README.md`)
- Telemetry intake → SQLite records: stores readings (evidence: `agents/api.py`)
- FastAPI → BPA adapter: starts workflow (evidence: `agents/api.py`)
- BPA adapter → SAP BPA: starts instance (evidence: `agents/integrations.py`)
- SAP BPA → Human review: sends callback (evidence: `README.md`)
- FastAPI → HANA reader: imports zones (evidence: `agents/api.py`)
- HANA reader → SAP HANA: reads view (evidence: `agents/integrations.py`)
- FastAPI → HANA publisher: publishes events (evidence: `agents/api.py`)
- HANA publisher → SAP HANA: writes event batch (evidence: `agents/hana_publish.py`)
- CAP OData service → CAP SQLite dataset: serves dataset
