# nostidus4/cordon architecture

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

- Interactive diagram: https://gitdiagram.com/nostidus4/cordon
- Repository: https://github.com/nostidus4/cordon

## Overview

Cordon is a spending-control product that models company spending keys and districts, simulates exposure, and enforces limits and emergency controls through a Guardian chain. Its principal workflow runs from the interactive city and scenario experience through backend policy services to chain checks; policy changes additionally pass through Council approval and execution. The README also documents incident response, read-only AI assistance, and a rebalance agent. Edges use README statements or SOURCE INDEX references; unsampled subsystems are shown without guessed internal call paths.

Main entry points: [`Backend/src/guardian/services/runtime.py`](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/runtime.py) (Runtime coordinator), [`Frontend/src/lib/api/client.ts`](https://github.com/nostidus4/cordon/blob/main/Frontend/src/lib/api/client.ts) (REST client), [`Backend/src/guardian/services/proposal_service.py`](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/proposal_service.py) (Proposal lifecycle), [`Backend/src/guardian/chain/base.py`](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/base.py) (Chain port)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_city["City and scenes<br/>[StagePage.tsx]"]
  node_simulation_ui["Exposure simulation<br/>[SimulatePage.tsx]"]
  node_requests_ui["Policy requests<br/>[RequestsPage.tsx]"]
  node_incident_ui["Incident response<br/>[IncidentPage.tsx]"]
  node_assistant_ui["Assistant panel<br/>[AssistantPanel.tsx]"]
  node_frontend_api["REST client<br/>[client.ts]"]
end

subgraph group_policy["Policy services"]
  node_api["FastAPI routes"]
  node_runtime["Runtime coordinator<br/>[runtime.py]"]
  node_snapshot["Policy snapshot<br/>[snapshot.py]"]
  node_simulation["Graph simulation<br/>[simulate.py]"]
  node_findings["Risk findings<br/>[findings.py]"]
  node_proposal["Proposal lifecycle"]
  node_assistant["Read-only assistant<br/>[service.py]"]
  node_rebalance["Rebalance agent<br/>[runner.py]"]
end

subgraph group_chain["Chain enforcement"]
  node_chain_port["Chain port<br/>[base.py]"]
  node_sim_chain["Simulated chain<br/>[engine.py]"]
  node_l1_chain["Guardian L1 adapter<br/>[startup.py]"]
  node_council["Council and timelock"]
  node_precompile["Tx AllowList<br/>[precompiles.py]"]
end

subgraph group_operations["Indexing and state"]
  node_worker["Chain indexer<br/>[indexer.py]"]
  node_storage[("Postgres stores<br/>[pg.py]")]
end

node_user(("Company operator"))
node_cchain(("Fuji C-Chain"))
node_guardian_l1{{"Guardian L1"}}
node_llm_service(("LLM provider"))

node_user -->|"explores"| node_city
node_user -->|"tests exposure"| node_simulation_ui
node_user -->|"requests policy"| node_requests_ui
node_user -->|"responds to incident"| node_incident_ui
node_city -.->|"loads state"| node_frontend_api
node_simulation_ui -.->|"requests simulation"| node_frontend_api
node_requests_ui -.->|"submits proposal"| node_frontend_api
node_incident_ui -.->|"requests controls"| node_frontend_api
node_assistant_ui -.->|"asks questions"| node_frontend_api
node_frontend_api -->|"REST / SSE"| node_api
node_api -.->|"serves requests"| node_runtime
node_runtime -->|"uses chain"| node_chain_port
node_runtime -->|"reads policy state"| node_snapshot
node_simulation -.->|"simulates changes"| node_snapshot
node_findings -.->|"evaluates risk"| node_snapshot
node_proposal -->|"uses stores and chain"| node_runtime
node_proposal -->|"simulates proposal"| node_simulation
node_proposal -->|"uses findings"| node_findings
node_assistant -->|"reads runtime"| node_runtime
node_assistant -.->|"generates responses"| node_llm_service
node_rebalance -->|"uses runtime"| node_runtime
node_chain_port -->|"implemented by"| node_sim_chain
node_chain_port -.->|"implemented by"| node_l1_chain
node_sim_chain -->|"simulates policies"| node_guardian_l1
node_l1_chain -->|"calls contracts"| node_guardian_l1
node_guardian_l1 -->|"enforces Council"| node_council
node_guardian_l1 -->|"rejects locked keys"| node_precompile
node_worker -->|"indexes events"| node_l1_chain
node_worker -->|"persists events"| node_storage
node_cchain -.->|"provides top-up events"| node_runtime

click node_city "https://github.com/nostidus4/cordon/blob/main/Frontend/src/stage/StagePage.tsx"
click node_simulation_ui "https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/simulate/SimulatePage.tsx"
click node_requests_ui "https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/requests/RequestsPage.tsx"
click node_incident_ui "https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/incident/IncidentPage.tsx"
click node_assistant_ui "https://github.com/nostidus4/cordon/blob/main/Frontend/src/components/assistant/AssistantPanel.tsx"
click node_frontend_api "https://github.com/nostidus4/cordon/blob/main/Frontend/src/lib/api/client.ts"
click node_api "https://github.com/nostidus4/cordon/tree/main/Backend/src/guardian/api/routes"
click node_runtime "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/runtime.py"
click node_snapshot "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/domain/snapshot.py"
click node_simulation "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/graph/simulate.py"
click node_findings "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/graph/findings.py"
click node_proposal "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/proposal_service.py"
click node_assistant "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/assistant/service.py"
click node_rebalance "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/agent_rebalance/runner.py"
click node_chain_port "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/base.py"
click node_sim_chain "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/sim/engine.py"
click node_l1_chain "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/l1/startup.py"
click node_council "https://github.com/nostidus4/cordon/tree/main/Backend/src/guardian/chain"
click node_precompile "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/precompiles.py"
click node_worker "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/workers/indexer.py"
click node_storage "https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/repositories/pg.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_city,node_simulation_ui,node_requests_ui,node_incident_ui,node_assistant_ui,node_frontend_api toneBlue
class node_api,node_runtime,node_snapshot,node_simulation,node_findings,node_proposal,node_assistant,node_rebalance toneAmber
class node_chain_port,node_sim_chain,node_l1_chain,node_council,node_precompile toneMint
class node_worker,node_storage toneRose
class node_user,node_cchain,node_guardian_l1,node_llm_service toneIndigo
```

## Components

### User experience

- [City and scenes](https://github.com/nostidus4/cordon/blob/main/Frontend/src/stage/StagePage.tsx): `Frontend/src/stage/StagePage.tsx`
- [Exposure simulation](https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/simulate/SimulatePage.tsx): `Frontend/src/pages/simulate/SimulatePage.tsx`
- [Policy requests](https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/requests/RequestsPage.tsx): `Frontend/src/pages/requests/RequestsPage.tsx`
- [Incident response](https://github.com/nostidus4/cordon/blob/main/Frontend/src/pages/incident/IncidentPage.tsx): `Frontend/src/pages/incident/IncidentPage.tsx`
- [Assistant panel](https://github.com/nostidus4/cordon/blob/main/Frontend/src/components/assistant/AssistantPanel.tsx): `Frontend/src/components/assistant/AssistantPanel.tsx`
- [REST client](https://github.com/nostidus4/cordon/blob/main/Frontend/src/lib/api/client.ts): `Frontend/src/lib/api/client.ts`

### Policy services

- [FastAPI routes](https://github.com/nostidus4/cordon/tree/main/Backend/src/guardian/api/routes): `Backend/src/guardian/api/routes`
- [Runtime coordinator](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/runtime.py): `Backend/src/guardian/services/runtime.py`
- [Policy snapshot](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/domain/snapshot.py): `Backend/src/guardian/domain/snapshot.py`
- [Graph simulation](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/graph/simulate.py): `Backend/src/guardian/graph/simulate.py`
- [Risk findings](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/graph/findings.py): `Backend/src/guardian/graph/findings.py`
- [Proposal lifecycle](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/services/proposal_service.py): `Backend/src/guardian/services/proposal_service.py`
- [Read-only assistant](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/assistant/service.py): `Backend/src/guardian/assistant/service.py`
- [Rebalance agent](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/agent_rebalance/runner.py): `Backend/src/guardian/agent_rebalance/runner.py`

### Chain enforcement

- [Chain port](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/base.py): `Backend/src/guardian/chain/base.py`
- [Simulated chain](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/sim/engine.py): `Backend/src/guardian/chain/sim/engine.py`
- [Guardian L1 adapter](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/l1/startup.py): `Backend/src/guardian/chain/l1/startup.py`
- [Council and timelock](https://github.com/nostidus4/cordon/tree/main/Backend/src/guardian/chain): `Backend/src/guardian/chain`
- [Tx AllowList](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/chain/precompiles.py): `Backend/src/guardian/chain/precompiles.py`

### Indexing and state

- [Chain indexer](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/workers/indexer.py): `Backend/src/guardian/workers/indexer.py`
- [Postgres stores](https://github.com/nostidus4/cordon/blob/main/Backend/src/guardian/repositories/pg.py): `Backend/src/guardian/repositories/pg.py`

### Other components

- **Company operator**
- **Fuji C-Chain**
- **Guardian L1**
- **LLM provider**

## Connections

- Company operator → City and scenes: explores (evidence: `README.md`)
- Company operator → Exposure simulation: tests exposure (evidence: `README.md`)
- Company operator → Policy requests: requests policy (evidence: `README.md`)
- Company operator → Incident response: responds to incident (evidence: `README.md`)
- City and scenes → REST client: loads state
- Exposure simulation → REST client: requests simulation
- Policy requests → REST client: submits proposal
- Incident response → REST client: requests controls
- Assistant panel → REST client: asks questions
- REST client → FastAPI routes: REST / SSE (evidence: `README.md`)
- FastAPI routes → Runtime coordinator: serves requests
- Runtime coordinator → Chain port: uses chain (evidence: `Backend/src/guardian/services/runtime.py`)
- Runtime coordinator → Policy snapshot: reads policy state (evidence: `Backend/src/guardian/services/runtime.py`)
- Graph simulation → Policy snapshot: simulates changes
- Risk findings → Policy snapshot: evaluates risk
- Proposal lifecycle → Runtime coordinator: uses stores and chain (evidence: `Backend/src/guardian/services/proposal_service.py`)
- Proposal lifecycle → Graph simulation: simulates proposal (evidence: `Backend/src/guardian/services/proposal_service.py`)
- Proposal lifecycle → Risk findings: uses findings (evidence: `Backend/src/guardian/services/proposal_service.py`)
- Read-only assistant → Runtime coordinator: reads runtime (evidence: `Backend/src/guardian/assistant/service.py`)
- Read-only assistant → LLM provider: generates responses
- Rebalance agent → Runtime coordinator: uses runtime (evidence: `Backend/src/guardian/agent_rebalance/main.py`)
- Chain port → Simulated chain: implemented by (evidence: `Backend/src/guardian/chain/sim/engine.py`)
- Chain port → Guardian L1 adapter: implemented by
- Simulated chain → Guardian L1: simulates policies (evidence: `README.md`)
- Guardian L1 adapter → Guardian L1: calls contracts (evidence: `README.md`)
- Guardian L1 → Council and timelock: enforces Council (evidence: `README.md`)
- Guardian L1 → Tx AllowList: rejects locked keys (evidence: `README.md`)
- Chain indexer → Guardian L1 adapter: indexes events (evidence: `Backend/src/guardian/workers/main.py`)
- Chain indexer → Postgres stores: persists events (evidence: `Backend/src/guardian/workers/main.py`)
- Fuji C-Chain → Runtime coordinator: provides top-up events
