# aqua32a7/sunkguard architecture

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

- Interactive diagram: https://gitdiagram.com/aqua32a7/sunkguard
- Repository: https://github.com/aqua32a7/sunkguard

## Overview

SunkGuard admits and schedules multi-step AI workflows against contended resource capacity, aiming to protect near-complete work from late failure. The principal path is workflow registration, step-admission scoring and resource allocation, execution/usage reporting, then monitoring through the API and dashboard; the Python SDK can initiate the same control-plane operations. The README documents simulation, policy modes, reservations, analytics, demos and Gemini support. Links among engine internals are based on the documented architecture; sampled excerpts do not expose every runtime call. Authentication and offline reconciliation are shown as distinct supporting capabilities.

Main entry points: [`server.py`](https://github.com/aqua32a7/sunkguard/blob/main/server.py) (FastAPI endpoints), [`core/runtime.py`](https://github.com/aqua32a7/sunkguard/blob/main/core/runtime.py) (Control runtime), [`src/App.tsx`](https://github.com/aqua32a7/sunkguard/blob/main/src/App.tsx) (Dashboard application), [`core/controller.py`](https://github.com/aqua32a7/sunkguard/blob/main/core/controller.py) (Admission controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Admission engine"]
  node_workflow["Workflow state<br/>[workflow.py]"]
  node_controller["Admission controller<br/>[controller.py]"]
  node_predictor["Failure predictor<br/>[predictor.py]"]
  node_resources["Resource accounting<br/>[resources.py]"]
  node_simulation["Deterministic simulation<br/>[sim.py]"]
  node_metrics["Metrics and events<br/>[metrics.py]"]
end

subgraph group_control["API control plane"]
  node_api["FastAPI endpoints<br/>[server.py]"]
  node_runtime["Control runtime<br/>[runtime.py]"]
end

subgraph group_integrations["SDK integrations"]
  node_sdk_client["Python SDK client<br/>[client.py]"]
  node_sdk_decorator["Reservation decorators<br/>[decorator.py]"]
  node_gemini["Gemini adapter<br/>[gemini_adapter.py]"]
end

subgraph group_dashboard["Operations dashboard"]
  node_app["Dashboard application<br/>[App.tsx]"]
  node_operations["Workflow and resource views"]
  node_api_service["Frontend API service<br/>[api.ts]"]
  node_static_data["Static demo data<br/>[staticDemoData.ts]"]
end

subgraph group_identity["Identity and resilience"]
  node_auth_ui["Frontend auth<br/>[supabaseAuth.ts]"]
  node_supabase_client["Supabase client<br/>[supabaseClient.ts]"]
  node_auth_manager["OTP and session manager<br/>[auth.py]"]
  node_email["Email delivery<br/>[email_service.py]"]
  node_auth_db[("Auth database<br/>[auth_db.py]")]
  node_connectivity["Connectivity monitor<br/>[connectivity.py]"]
  node_journal[("Offline journal<br/>[offline_journal.py]")]
  node_reconciler["Offline reconciler<br/>[reconciler.py]"]
end

node_engineer(("Workflow engineer"))
node_gemini_service{{"Gemini API"}}
node_supabase{{"Supabase auth"}}

node_engineer -->|"wraps workflow steps"| node_sdk_decorator
node_engineer -->|"registers workflow"| node_sdk_client
node_sdk_decorator -->|"requests reservations"| node_sdk_client
node_sdk_client -->|"sends REST requests"| node_api
node_engineer -->|"monitors operations"| node_app
node_app -->|"loads and updates"| node_api_service
node_api_service -->|"calls endpoints"| node_api
node_app -->|"renders routes"| node_operations
node_app -.->|"loads demo state"| node_static_data
node_api -->|"dispatches requests"| node_runtime
node_runtime -->|"tracks workflow state"| node_workflow
node_runtime -->|"requests admission"| node_controller
node_controller -->|"estimates failure risk"| node_predictor
node_controller -->|"checks and reserves capacity"| node_resources
node_runtime -->|"accounts usage"| node_resources
node_runtime -->|"runs scenarios"| node_simulation
node_runtime -->|"aggregates measurements"| node_metrics
node_api -->|"invokes adapter"| node_gemini
node_gemini -.->|"sends model requests"| node_gemini_service
node_app -->|"handles sign-in"| node_auth_ui
node_auth_ui -->|"uses configured client"| node_supabase_client
node_supabase_client -.->|"authenticates"| node_supabase
node_auth_ui -.->|"uses local OTP fallback"| node_api
node_api -->|"handles OTP requests"| node_auth_manager
node_auth_manager -->|"delivers verification code"| node_email
node_auth_manager -->|"reads and writes accounts"| node_auth_db
node_api -->|"reports connectivity"| node_connectivity
node_connectivity -->|"records offline events"| node_journal
node_api -->|"triggers reconciliation"| node_reconciler
node_reconciler -->|"reads pending events"| node_journal
node_reconciler -->|"replays updates"| node_runtime

click node_sdk_client "https://github.com/aqua32a7/sunkguard/blob/main/sdk/client.py"
click node_sdk_decorator "https://github.com/aqua32a7/sunkguard/blob/main/sdk/decorator.py"
click node_api "https://github.com/aqua32a7/sunkguard/blob/main/server.py"
click node_runtime "https://github.com/aqua32a7/sunkguard/blob/main/core/runtime.py"
click node_workflow "https://github.com/aqua32a7/sunkguard/blob/main/core/workflow.py"
click node_controller "https://github.com/aqua32a7/sunkguard/blob/main/core/controller.py"
click node_predictor "https://github.com/aqua32a7/sunkguard/blob/main/core/predictor.py"
click node_resources "https://github.com/aqua32a7/sunkguard/blob/main/core/resources.py"
click node_simulation "https://github.com/aqua32a7/sunkguard/blob/main/core/sim.py"
click node_metrics "https://github.com/aqua32a7/sunkguard/blob/main/core/metrics.py"
click node_gemini "https://github.com/aqua32a7/sunkguard/blob/main/core/gemini_adapter.py"
click node_app "https://github.com/aqua32a7/sunkguard/blob/main/src/App.tsx"
click node_operations "https://github.com/aqua32a7/sunkguard/blob/main/src/pages/OperationsPages.tsx"
click node_api_service "https://github.com/aqua32a7/sunkguard/blob/main/src/services/api.ts"
click node_static_data "https://github.com/aqua32a7/sunkguard/blob/main/src/services/staticDemoData.ts"
click node_auth_ui "https://github.com/aqua32a7/sunkguard/blob/main/src/services/supabaseAuth.ts"
click node_supabase_client "https://github.com/aqua32a7/sunkguard/blob/main/src/services/supabaseClient.ts"
click node_auth_manager "https://github.com/aqua32a7/sunkguard/blob/main/core/auth.py"
click node_email "https://github.com/aqua32a7/sunkguard/blob/main/core/email_service.py"
click node_auth_db "https://github.com/aqua32a7/sunkguard/blob/main/core/auth_db.py"
click node_connectivity "https://github.com/aqua32a7/sunkguard/blob/main/core/connectivity.py"
click node_journal "https://github.com/aqua32a7/sunkguard/blob/main/core/offline_journal.py"
click node_reconciler "https://github.com/aqua32a7/sunkguard/blob/main/core/reconciler.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_workflow,node_controller,node_predictor,node_resources,node_simulation,node_metrics toneBlue
class node_api,node_runtime toneAmber
class node_sdk_client,node_sdk_decorator,node_gemini,node_gemini_service toneMint
class node_app,node_operations,node_api_service,node_static_data toneRose
class node_auth_ui,node_supabase_client,node_auth_manager,node_email,node_auth_db,node_connectivity,node_journal,node_reconciler,node_engineer,node_supabase toneIndigo
```

## Components

### Admission engine

- [Workflow state](https://github.com/aqua32a7/sunkguard/blob/main/core/workflow.py): `core/workflow.py`
- [Admission controller](https://github.com/aqua32a7/sunkguard/blob/main/core/controller.py): `core/controller.py`
- [Failure predictor](https://github.com/aqua32a7/sunkguard/blob/main/core/predictor.py): `core/predictor.py`
- [Resource accounting](https://github.com/aqua32a7/sunkguard/blob/main/core/resources.py): `core/resources.py`
- [Deterministic simulation](https://github.com/aqua32a7/sunkguard/blob/main/core/sim.py): `core/sim.py`
- [Metrics and events](https://github.com/aqua32a7/sunkguard/blob/main/core/metrics.py): `core/metrics.py`

### API control plane

- [FastAPI endpoints](https://github.com/aqua32a7/sunkguard/blob/main/server.py): `server.py`
- [Control runtime](https://github.com/aqua32a7/sunkguard/blob/main/core/runtime.py): `core/runtime.py`

### SDK integrations

- [Python SDK client](https://github.com/aqua32a7/sunkguard/blob/main/sdk/client.py): `sdk/client.py`
- [Reservation decorators](https://github.com/aqua32a7/sunkguard/blob/main/sdk/decorator.py): `sdk/decorator.py`
- [Gemini adapter](https://github.com/aqua32a7/sunkguard/blob/main/core/gemini_adapter.py): `core/gemini_adapter.py`

### Operations dashboard

- [Dashboard application](https://github.com/aqua32a7/sunkguard/blob/main/src/App.tsx): `src/App.tsx`
- [Workflow and resource views](https://github.com/aqua32a7/sunkguard/blob/main/src/pages/OperationsPages.tsx): `src/pages/OperationsPages.tsx`
- [Frontend API service](https://github.com/aqua32a7/sunkguard/blob/main/src/services/api.ts): `src/services/api.ts`
- [Static demo data](https://github.com/aqua32a7/sunkguard/blob/main/src/services/staticDemoData.ts): `src/services/staticDemoData.ts`

### Identity and resilience

- [Frontend auth](https://github.com/aqua32a7/sunkguard/blob/main/src/services/supabaseAuth.ts): `src/services/supabaseAuth.ts`
- [Supabase client](https://github.com/aqua32a7/sunkguard/blob/main/src/services/supabaseClient.ts): `src/services/supabaseClient.ts`
- [OTP and session manager](https://github.com/aqua32a7/sunkguard/blob/main/core/auth.py): `core/auth.py`
- [Email delivery](https://github.com/aqua32a7/sunkguard/blob/main/core/email_service.py): `core/email_service.py`
- [Auth database](https://github.com/aqua32a7/sunkguard/blob/main/core/auth_db.py): `core/auth_db.py`
- [Connectivity monitor](https://github.com/aqua32a7/sunkguard/blob/main/core/connectivity.py): `core/connectivity.py`
- [Offline journal](https://github.com/aqua32a7/sunkguard/blob/main/core/offline_journal.py): `core/offline_journal.py`
- [Offline reconciler](https://github.com/aqua32a7/sunkguard/blob/main/core/reconciler.py): `core/reconciler.py`

### Other components

- **Workflow engineer**
- **Gemini API**
- **Supabase auth**

## Connections

- Workflow engineer → Reservation decorators: wraps workflow steps
- Workflow engineer → Python SDK client: registers workflow
- Reservation decorators → Python SDK client: requests reservations
- Python SDK client → FastAPI endpoints: sends REST requests
- Workflow engineer → Dashboard application: monitors operations
- Dashboard application → Frontend API service: loads and updates
- Frontend API service → FastAPI endpoints: calls endpoints
- Dashboard application → Workflow and resource views: renders routes
- Dashboard application → Static demo data: loads demo state
- FastAPI endpoints → Control runtime: dispatches requests
- Control runtime → Workflow state: tracks workflow state
- Control runtime → Admission controller: requests admission
- Admission controller → Failure predictor: estimates failure risk
- Admission controller → Resource accounting: checks and reserves capacity
- Control runtime → Resource accounting: accounts usage
- Control runtime → Deterministic simulation: runs scenarios
- Control runtime → Metrics and events: aggregates measurements
- FastAPI endpoints → Gemini adapter: invokes adapter
- Gemini adapter → Gemini API: sends model requests
- Dashboard application → Frontend auth: handles sign-in
- Frontend auth → Supabase client: uses configured client
- Supabase client → Supabase auth: authenticates
- Frontend auth → FastAPI endpoints: uses local OTP fallback
- FastAPI endpoints → OTP and session manager: handles OTP requests
- OTP and session manager → Email delivery: delivers verification code
- OTP and session manager → Auth database: reads and writes accounts
- FastAPI endpoints → Connectivity monitor: reports connectivity
- Connectivity monitor → Offline journal: records offline events
- FastAPI endpoints → Offline reconciler: triggers reconciliation
- Offline reconciler → Offline journal: reads pending events
- Offline reconciler → Control runtime: replays updates