How sisig-mayo/acta works
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: app_shell.dart App shell · routes API routes · llm_pipeline.py LLM pipeline · supabase_client.py Supabase client
Components 26
Flutter client
Operator console for simulation setup, dashboards, action plans, and PDF review.
- App entry · Main Flutter application bootstrap.
lib/main.dart - App shell · Shared navigation and app framing.
lib/views/app_shell.dart - Login · User sign-in and session entry.
lib/views/login_screen.dart - Command center · Primary operational dashboard for barangay-focused monitoring.
lib/views/command_center_screen.dart - Sim setup · Collects simulation inputs and parameters.
lib/views/simulation_setup_screen.dart - Run simulation · Triggers simulation execution and result retrieval.
lib/views/run_simulation_screen.dart - Resources · Resource and operational status management.
lib/views/resource_management_screen.dart - AI plan · Displays generated action-plan output.
lib/views/ai_action_plan_screen.dart - Master plan · Reviews exported master action plan documents.
lib/views/master_action_plan_screen.dart - Client models · Shared client state and domain shapes.
lib/models/simulation_models.dart - API config · Central backend endpoint configuration.
lib/config/api_config.dart - Auth storage · Client-side session persistence.
lib/utils/auth_storage.dart - PDF download · Platform-specific PDF download handling.
lib/utils/pdf_download.dart
FastAPI backend
Orchestration layer for auth, routing, simulation, and LLM action plans.
- API app · Python service bootstrap and API assembly.
backend/main.py - API routes · Auth, barangay, routing, and simulation endpoints.
backend/app/routes - Risk pipeline · Coordinates geospatial risk scoring and simulation persistence.
backend/app/services/risk_pipeline.py - LLM pipeline · Builds structured context and requests Gemini-backed action plans.
backend/app/services/llm_pipeline.py - PDF generator · Produces the Master Action Plan PDF.
backend/app/services/pdf_generator.py - Gemini client · Sends structured context to Gemini and parses response.
backend/app/core/gemini.py - Supabase client · Backend persistence access to Supabase/PostgreSQL.
backend/app/core/supabase_client.py - Pydantic models · Simulation and action-plan payload schemas.
backend/app/models
Spatial database
Supabase/PostgreSQL/PostGIS state, routing logic, and geo data.
- Migrations · Extensions, routing logic, risk tables, and LLM columns.
database/migrations - Geo seeds · Barangay boundaries and road network seeding.
database/seed_geojson_handler.py
Data ingestion
Upstream loaders and seeders for geospatial and population data.
- Ingestor · External data preparation and ingestion path.
data_pipeline/ingestor.py
Delivery and docs
CI, deployment manifests, and static documentation site.
- GitHub Actions · Frontend publishing and data pipeline automation.
.github/workflows - MkDocs site · Separate published documentation artifact.
docs/site
Connections 28
- 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.