# sisig-mayo/acta architecture

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

- Interactive diagram: https://gitdiagram.com/sisig-mayo/acta
- Repository: https://github.com/sisig-mayo/acta

## Overview

1. **Repository shape**
   - This is a three-part monorepo: `lib/` for a Flutter client, `backend/` for a Python FastAPI service, and `database/` for PostgreSQL/PostGIS migrations and seed scripts.
   - The docs site under `docs/` is a separate static MkDocs artifact, not part of runtime behavior.

2. **Frontend boundary: Flutter client**
   - The client is a single Flutter codebase that targets web, mobile, desktop, and GitHub Pages deployment.
   - Core UI entrypoint is `lib/main.dart`; screens are organized in `lib/views/` around operational workflows such as login, command center, simulation setup/run, resource management, AI action plan, and master action plan review.
   - Shared client state and domain shapes live in `lib/models/`, while backend endpoint configuration is centralized in `lib/config/api_config.dart`.

3. **Frontend data flow**
   - The Flutter app is the operator console: it collects simulation inputs, fetches risk/simulation results, renders barangay-focused dashboards, and displays explainability cards and PDF outputs.
   - Local helpers such as `lib/utils/auth_storage.dart` and `lib/utils/pdf_download*.dart` show that auth persistence and PDF handling are client-side concerns, while the actual document generation happens in the backend.

4. **Backend boundary: FastAPI orchestration layer**
   - The backend is a Python 3.11 FastAPI application rooted at `backend/main.py` and organized into `core/`, `models/`, `routes/`, and `services/`.
   - `routes/` exposes API boundaries for auth, barangays, routing, and simulation; `models/` contains Pydantic schemas for simulation and action-plan payloads; `services/` contains the computational pipelines.
   - `backend/Procfile`, `railway.json`, and `vercel.json` indicate deployment support for multiple hosts, with the runtime configured independently of the Flutter client.

5. **Simulation and risk pipeline**
   - The core backend workflow is a background simulation pipeline in `backend/app/services/risk_pipeline.py`.
   - It orchestrates geospatial risk scoring, decay-based task generation, and persistence of simulation status/results.
   - Supporting engines include `gee_engine.py` for spatial risk scoring, `decay_engine.py` for time-sensitive task prioritization, and `dispatch.py` / `bypass_router.py` for operational routing decisions.

6. **LLM/action-plan pipeline**
   - The LLM subsystem is a distinct layer, not just a prompt wrapper.
   - `backend/app/services/llm_pipeline.py` assembles a structured context snapshot from simulation inputs, risk results, infrastructure state, and template tasks.
   - `backend/app/core/gemini.py` sends that context to Gemini and returns a structured `LLMActionPlanResponse`; if Gemini is unavailable, the system falls back to deterministic template output.
   - This is the main “decision-to-action” boundary: simulation output becomes an auditable action plan.

7. **Persistence layer: Supabase PostgreSQL with spatial extensions**
   - The backend persists to Supabase/PostgreSQL through `backend/app/core/supabase_client.py`.
   - Database migrations under `database/migrations/` establish extensions, routing logic, meteorological data, simulation risk tables, optimized routing, barangay GeoJSON RPCs, and LLM-specific columns.
   - The schema is spatially enabled, with PostGIS/pgRouting implied by the migrations and README, so the DB is not just storage but a geospatial compute boundary.

8. **Geospatial and routing domain**
   - Barangay boundaries and road/network data are seeded separately via `database/seed_geojson_handler.py`, `database/seed_roads_handler.py`, and `backend/database/seed_population.py`.
   - Routing and spatial lookups are exposed through backend endpoints and DB functions, enabling flood-aware navigation and barangay-level area queries.
   - The system expects a local Manila GeoJSON dataset, which is treated as external input data rather than source-controlled code.

9. **PDF and action-plan export**
   - `backend/app/services/pdf_generator.py` produces the Master Action Plan PDF that operators can review and dispatch.
   - On the client side, PDF download behavior is abstracted so web and non-web platforms can use different implementations, which matters for the architecture of file export but not the decision logic itself.

10. **Data ingestion and external feeds**
   - `data_pipeline/ingestor.py` is a separate ingestion component, likely responsible for bringing external data into the system rather than serving requests.
   - The README and backend file names suggest that meteorological and flood-context data are part of the pipeline, so the architecture includes an upstream data-preparation path feeding the simulation subsystem.

11. **Deployment and delivery**
   - Frontend web deployment is automated through GitHub Actions workflows in `.github/workflows/`, including GitHub Pages publishing.
   - The backend is configured for cloud deployment with separate host manifests, while the docs are built and published as a static MkDocs site under `docs/site/`.

12. **Quality and operational boundaries**
   - Tests are split across backend-focused scripts (`backend/test_backend.py`, `backend/test_decision_engine.py`) and repo-level checks (`test_db.py`, `test_auth.py`, `test_topo.py`), suggesting the core verification concern is backend behavior and spatial correctness.
   - The docs under `docs/docs/reference/` and `docs/docs/development/` are a useful source of intended contracts for API, configuration, data model, and pipeline behavior.

13. **How to diagram the system**
   - Draw the Flutter client as the operator-facing presentation layer.
   - Draw the FastAPI backend as the orchestration layer with separate simulation, routing, and LLM subsystems.
   - Draw Supabase/PostgreSQL/PostGIS as the authoritative state and spatial compute store.
   - Add the ingestion/seed path feeding the database, and the docs/CI/deployment paths as supporting infrastructure rather than runtime data flow.

Main entry points: [`lib/views/app_shell.dart`](https://github.com/sisig-mayo/acta/blob/main/lib/views/app_shell.dart) (App shell), [`backend/app/routes`](https://github.com/sisig-mayo/acta/tree/main/backend/app/routes) (API routes), [`backend/app/services/llm_pipeline.py`](https://github.com/sisig-mayo/acta/blob/main/backend/app/services/llm_pipeline.py) (LLM pipeline), [`backend/app/core/supabase_client.py`](https://github.com/sisig-mayo/acta/blob/main/backend/app/core/supabase_client.py) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Flutter client"]
  node_lib_main["App entry<br/>Flutter entrypoint<br/>[main.dart]"]
  node_lib_shell["App shell<br/>Flutter UI shell<br/>[app_shell.dart]"]
  node_lib_login["Login<br/>auth screen<br/>[login_screen.dart]"]
  node_lib_command["Command center<br/>operator dashboard"]
  node_lib_setup["Sim setup<br/>workflow screen"]
  node_lib_run["Run simulation<br/>workflow screen"]
  node_lib_resources["Resources<br/>management screen"]
  node_lib_ai["AI plan<br/>LLM screen"]
  node_lib_master["Master plan<br/>PDF review screen"]
  node_lib_models["Client models<br/>state models"]
  node_lib_api["API config<br/>endpoint config<br/>[api_config.dart]"]
  node_lib_auth["Auth storage<br/>client utility<br/>[auth_storage.dart]"]
  node_lib_pdf["PDF download<br/>client utility<br/>[pdf_download.dart]"]
end

subgraph group_backend["FastAPI backend"]
  node_backend_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_routes["API routes<br/>HTTP boundaries"]
  node_backend_sim["Risk pipeline<br/>simulation pipeline<br/>[risk_pipeline.py]"]
  node_backend_llm["LLM pipeline<br/>action-plan pipeline<br/>[llm_pipeline.py]"]
  node_backend_pdf["PDF generator<br/>document service<br/>[pdf_generator.py]"]
  node_backend_gemini["Gemini client<br/>LLM adapter<br/>[gemini.py]"]
  node_backend_supabase[("Supabase client<br/>database adapter<br/>[supabase_client.py]")]
  node_backend_models["Pydantic models<br/>schema layer"]
end

subgraph group_database["Spatial database"]
  node_db_migrations["Migrations<br/>SQL schema"]
  node_db_seed["Geo seeds<br/>spatial seed scripts"]
end

subgraph group_ingestion["Data ingestion"]
  node_ingestor["Ingestor<br/>data pipeline<br/>[ingestor.py]"]
end

subgraph group_support["Delivery and docs"]
  node_github_actions["GitHub Actions<br/>CI/CD workflows<br/>[workflows]"]
  node_docs_site["MkDocs site<br/>static docs"]
end

node_lib_main -->|"boots"| node_lib_shell
node_lib_shell -->|"routes to"| node_lib_login
node_lib_shell -->|"shows"| node_lib_command
node_lib_shell -->|"opens"| node_lib_setup
node_lib_shell -->|"opens"| node_lib_run
node_lib_shell -->|"opens"| node_lib_resources
node_lib_shell -->|"opens"| node_lib_ai
node_lib_shell -->|"opens"| node_lib_master
node_lib_command -->|"uses"| node_lib_models
node_lib_setup -->|"calls"| node_lib_api
node_lib_run -->|"calls"| node_lib_api
node_lib_login -->|"persists"| node_lib_auth
node_lib_ai -->|"downloads"| node_lib_pdf
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"invokes"| node_backend_sim
node_backend_routes -->|"invokes"| node_backend_llm
node_backend_routes -->|"reads/writes"| node_backend_supabase
node_backend_sim -->|"persists"| node_backend_supabase
node_backend_sim -->|"depends on"| node_db_migrations
node_backend_llm -->|"calls"| node_backend_gemini
node_backend_llm -->|"shapes"| node_backend_models
node_backend_llm -->|"exports"| node_backend_pdf
node_backend_gemini -->|"reads context"| node_backend_supabase
node_backend_supabase -->|"uses schema"| node_db_migrations
node_db_seed -->|"feeds"| node_db_migrations
node_ingestor -->|"loads"| node_db_seed
node_github_actions -->|"publishes"| node_docs_site
node_github_actions -->|"deploys"| node_lib_main

click node_lib_main "https://github.com/sisig-mayo/acta/blob/main/lib/main.dart"
click node_lib_shell "https://github.com/sisig-mayo/acta/blob/main/lib/views/app_shell.dart"
click node_lib_login "https://github.com/sisig-mayo/acta/blob/main/lib/views/login_screen.dart"
click node_lib_command "https://github.com/sisig-mayo/acta/blob/main/lib/views/command_center_screen.dart"
click node_lib_setup "https://github.com/sisig-mayo/acta/blob/main/lib/views/simulation_setup_screen.dart"
click node_lib_run "https://github.com/sisig-mayo/acta/blob/main/lib/views/run_simulation_screen.dart"
click node_lib_resources "https://github.com/sisig-mayo/acta/blob/main/lib/views/resource_management_screen.dart"
click node_lib_ai "https://github.com/sisig-mayo/acta/blob/main/lib/views/ai_action_plan_screen.dart"
click node_lib_master "https://github.com/sisig-mayo/acta/blob/main/lib/views/master_action_plan_screen.dart"
click node_lib_models "https://github.com/sisig-mayo/acta/blob/main/lib/models/simulation_models.dart"
click node_lib_api "https://github.com/sisig-mayo/acta/blob/main/lib/config/api_config.dart"
click node_lib_auth "https://github.com/sisig-mayo/acta/blob/main/lib/utils/auth_storage.dart"
click node_lib_pdf "https://github.com/sisig-mayo/acta/blob/main/lib/utils/pdf_download.dart"
click node_backend_main "https://github.com/sisig-mayo/acta/blob/main/backend/main.py"
click node_backend_routes "https://github.com/sisig-mayo/acta/tree/main/backend/app/routes"
click node_backend_sim "https://github.com/sisig-mayo/acta/blob/main/backend/app/services/risk_pipeline.py"
click node_backend_llm "https://github.com/sisig-mayo/acta/blob/main/backend/app/services/llm_pipeline.py"
click node_backend_pdf "https://github.com/sisig-mayo/acta/blob/main/backend/app/services/pdf_generator.py"
click node_backend_gemini "https://github.com/sisig-mayo/acta/blob/main/backend/app/core/gemini.py"
click node_backend_supabase "https://github.com/sisig-mayo/acta/blob/main/backend/app/core/supabase_client.py"
click node_backend_models "https://github.com/sisig-mayo/acta/tree/main/backend/app/models"
click node_db_migrations "https://github.com/sisig-mayo/acta/tree/main/database/migrations"
click node_db_seed "https://github.com/sisig-mayo/acta/blob/main/database/seed_geojson_handler.py"
click node_ingestor "https://github.com/sisig-mayo/acta/blob/main/data_pipeline/ingestor.py"
click node_github_actions "https://github.com/sisig-mayo/acta/blob/main/.github/workflows"
click node_docs_site "https://github.com/sisig-mayo/acta/tree/main/docs/site"

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_lib_main,node_lib_shell,node_lib_login,node_lib_command,node_lib_setup,node_lib_run,node_lib_resources,node_lib_ai,node_lib_master,node_lib_models,node_lib_api,node_lib_auth,node_lib_pdf toneBlue
class node_backend_main,node_backend_routes,node_backend_sim,node_backend_llm,node_backend_pdf,node_backend_gemini,node_backend_supabase,node_backend_models toneAmber
class node_db_migrations,node_db_seed toneMint
class node_ingestor toneRose
class node_github_actions,node_docs_site toneIndigo
```

## Components

### Flutter client

Operator console for simulation setup, dashboards, action plans, and PDF review.

- [App entry](https://github.com/sisig-mayo/acta/blob/main/lib/main.dart): Flutter entrypoint · Main Flutter application bootstrap. · `lib/main.dart`
- [App shell](https://github.com/sisig-mayo/acta/blob/main/lib/views/app_shell.dart): Flutter UI shell · Shared navigation and app framing. · `lib/views/app_shell.dart`
- [Login](https://github.com/sisig-mayo/acta/blob/main/lib/views/login_screen.dart): auth screen · User sign-in and session entry. · `lib/views/login_screen.dart`
- [Command center](https://github.com/sisig-mayo/acta/blob/main/lib/views/command_center_screen.dart): operator dashboard · Primary operational dashboard for barangay-focused monitoring. · `lib/views/command_center_screen.dart`
- [Sim setup](https://github.com/sisig-mayo/acta/blob/main/lib/views/simulation_setup_screen.dart): workflow screen · Collects simulation inputs and parameters. · `lib/views/simulation_setup_screen.dart`
- [Run simulation](https://github.com/sisig-mayo/acta/blob/main/lib/views/run_simulation_screen.dart): workflow screen · Triggers simulation execution and result retrieval. · `lib/views/run_simulation_screen.dart`
- [Resources](https://github.com/sisig-mayo/acta/blob/main/lib/views/resource_management_screen.dart): management screen · Resource and operational status management. · `lib/views/resource_management_screen.dart`
- [AI plan](https://github.com/sisig-mayo/acta/blob/main/lib/views/ai_action_plan_screen.dart): LLM screen · Displays generated action-plan output. · `lib/views/ai_action_plan_screen.dart`
- [Master plan](https://github.com/sisig-mayo/acta/blob/main/lib/views/master_action_plan_screen.dart): PDF review screen · Reviews exported master action plan documents. · `lib/views/master_action_plan_screen.dart`
- [Client models](https://github.com/sisig-mayo/acta/blob/main/lib/models/simulation_models.dart): state models · Shared client state and domain shapes. · `lib/models/simulation_models.dart`
- [API config](https://github.com/sisig-mayo/acta/blob/main/lib/config/api_config.dart): endpoint config · Central backend endpoint configuration. · `lib/config/api_config.dart`
- [Auth storage](https://github.com/sisig-mayo/acta/blob/main/lib/utils/auth_storage.dart): client utility · Client-side session persistence. · `lib/utils/auth_storage.dart`
- [PDF download](https://github.com/sisig-mayo/acta/blob/main/lib/utils/pdf_download.dart): client utility · Platform-specific PDF download handling. · `lib/utils/pdf_download.dart`

### FastAPI backend

Orchestration layer for auth, routing, simulation, and LLM action plans.

- [API app](https://github.com/sisig-mayo/acta/blob/main/backend/main.py): FastAPI entrypoint · Python service bootstrap and API assembly. · `backend/main.py`
- [API routes](https://github.com/sisig-mayo/acta/tree/main/backend/app/routes): HTTP boundaries · Auth, barangay, routing, and simulation endpoints. · `backend/app/routes`
- [Risk pipeline](https://github.com/sisig-mayo/acta/blob/main/backend/app/services/risk_pipeline.py): simulation pipeline · Coordinates geospatial risk scoring and simulation persistence. · `backend/app/services/risk_pipeline.py`
- [LLM pipeline](https://github.com/sisig-mayo/acta/blob/main/backend/app/services/llm_pipeline.py): action-plan pipeline · Builds structured context and requests Gemini-backed action plans. · `backend/app/services/llm_pipeline.py`
- [PDF generator](https://github.com/sisig-mayo/acta/blob/main/backend/app/services/pdf_generator.py): document service · Produces the Master Action Plan PDF. · `backend/app/services/pdf_generator.py`
- [Gemini client](https://github.com/sisig-mayo/acta/blob/main/backend/app/core/gemini.py): LLM adapter · Sends structured context to Gemini and parses response. · `backend/app/core/gemini.py`
- [Supabase client](https://github.com/sisig-mayo/acta/blob/main/backend/app/core/supabase_client.py): database adapter · Backend persistence access to Supabase/PostgreSQL. · `backend/app/core/supabase_client.py`
- [Pydantic models](https://github.com/sisig-mayo/acta/tree/main/backend/app/models): schema layer · Simulation and action-plan payload schemas. · `backend/app/models`

### Spatial database

Supabase/PostgreSQL/PostGIS state, routing logic, and geo data.

- [Migrations](https://github.com/sisig-mayo/acta/tree/main/database/migrations): SQL schema · Extensions, routing logic, risk tables, and LLM columns. · `database/migrations`
- [Geo seeds](https://github.com/sisig-mayo/acta/blob/main/database/seed_geojson_handler.py): spatial seed scripts · Barangay boundaries and road network seeding. · `database/seed_geojson_handler.py`

### Data ingestion

Upstream loaders and seeders for geospatial and population data.

- [Ingestor](https://github.com/sisig-mayo/acta/blob/main/data_pipeline/ingestor.py): data pipeline · External data preparation and ingestion path. · `data_pipeline/ingestor.py`

### Delivery and docs

CI, deployment manifests, and static documentation site.

- [GitHub Actions](https://github.com/sisig-mayo/acta/blob/main/.github/workflows): CI/CD workflows · Frontend publishing and data pipeline automation. · `.github/workflows`
- [MkDocs site](https://github.com/sisig-mayo/acta/tree/main/docs/site): static docs · Separate published documentation artifact. · `docs/site`

## Connections

- App entry → App shell: boots · App entry initializes the shared shell.
- App shell → Login: routes to · Shell presents authentication flow.
- App shell → Command center: shows · Primary operator dashboard.
- App shell → Sim setup: opens · Simulation setup workflow.
- App shell → Run simulation: opens · Simulation execution workflow.
- App shell → Resources: opens · Resource management workflow.
- App shell → AI plan: opens · AI action-plan review.
- App shell → Master plan: opens · Master plan review and export.
- Command center → Client models: uses · Dashboard binds shared state models.
- Sim setup → API config: calls · Uses backend endpoint configuration.
- Run simulation → API config: calls · Requests simulation and results APIs.
- Login → Auth storage: persists · Stores session data locally.
- AI plan → PDF download: downloads · Client handles PDF retrieval.
- API app → API routes: mounts · API entry exposes route modules.
- API routes → Risk pipeline: invokes · Simulation endpoints trigger the risk pipeline.
- API routes → LLM pipeline: invokes · Action-plan endpoints trigger LLM orchestration.
- API routes → Supabase client: reads/writes · Routes persist and fetch state through Supabase.
- Risk pipeline → Supabase client: persists · Simulation status and results are stored.
- Risk pipeline → Migrations: depends on · Uses risk, routing, and geo schema.
- LLM pipeline → Gemini client: calls · LLM pipeline delegates to Gemini adapter.
- LLM pipeline → Pydantic models: shapes · Produces structured action-plan payloads.
- LLM pipeline → PDF generator: exports · Generates master action-plan PDF output.
- Gemini client → Supabase client: reads context · LLM context pulls simulation and spatial state.
- Supabase client → Migrations: uses schema · Backend persistence targets migrated tables and functions.
- Geo seeds → Migrations: feeds · Seed data populates geospatial tables.
- Ingestor → Geo seeds: loads · Ingestion prepares external datasets for database seeding.
- GitHub Actions → MkDocs site: publishes · CI builds and publishes static documentation.
- GitHub Actions → App entry: deploys · Frontend web deployment targets the Flutter client.