# wahid989/falcon architecture

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

- Interactive diagram: https://gitdiagram.com/wahid989/falcon
- Repository: https://github.com/wahid989/falcon

## Overview

FALCON runs an offline JSON-over-TCP command/response protocol across a dynamic hierarchy of dual-role agents. A commander sends a validated command to a follower; the follower evaluates it against simulated state and returns compliance or a decline. Role changes and heartbeat-driven recovery maintain authority, while JSONL exchange logs can optionally be ingested into SQL Server and queried through a REST API. The graph reflects README claims and indexed imports; unsampled wiring, especially around agent runners and storage startup, is shown only where documented or directly referenced.

Main entry points: [`src/agents/dual_role.py`](https://github.com/wahid989/falcon/blob/main/src/agents/dual_role.py) (Dual-role runtime), [`src/agents/follower.py`](https://github.com/wahid989/falcon/blob/main/src/agents/follower.py) (Follower), [`src/roles/manager.py`](https://github.com/wahid989/falcon/blob/main/src/roles/manager.py) (Role manager), [`src/agents/commander.py`](https://github.com/wahid989/falcon/blob/main/src/agents/commander.py) (Commander)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent workflow"]
  node_commander["Commander<br/>[commander.py]"]
  node_follower["Follower<br/>[follower.py]"]
  node_dual_role["Dual-role runtime<br/>[dual_role.py]"]
  node_decision["Decision engine<br/>[engine.py]"]
  node_follower_state["Follower state<br/>[follower_state.py]"]
end

subgraph group_authority["Roles and recovery"]
  node_hierarchy["Hierarchy<br/>[hierarchy.py]"]
  node_role_manager["Role manager<br/>[manager.py]"]
  node_heartbeat["Heartbeat monitor<br/>[heartbeat.py]"]
  node_failover["Failover selection<br/>[failover.py]"]
end

subgraph group_protocol["Protocol and transport"]
  node_validator["Message validator<br/>[validator.py]"]
  node_transport["TCP transport<br/>[tcp.py]"]
  node_reconnect["Reconnect transport<br/>[reconnect.py]"]
end

subgraph group_observability["Logs and storage"]
  node_exchange_log["Exchange logging<br/>[exchange.py]"]
  node_storage_ingest["Log ingestion<br/>[LogIngester.cs]"]
  node_line_parser["Log parsing<br/>[LogRecordParser.cs]"]
  node_storage_service["Ingestion service"]
  node_sql_factory["SQL connections"]
  node_database[("SQL Server")]
  node_query_api["Query API<br/>[ApiEndpoints.cs]"]
end

node_operator(("Command initiator"))

node_operator -->|"initiates commands"| node_commander
node_commander -->|"validates messages"| node_validator
node_commander -->|"sends commands"| node_transport
node_transport -.->|"delivers messages"| node_follower
node_follower -->|"validates messages"| node_validator
node_follower -->|"evaluates commands"| node_decision
node_follower -->|"reads state"| node_follower_state
node_dual_role -->|"uses"| node_commander
node_dual_role -->|"uses"| node_follower
node_dual_role -->|"manages chain"| node_hierarchy
node_dual_role -->|"handles roles"| node_role_manager
node_dual_role -->|"uses"| node_heartbeat
node_dual_role -->|"records exchanges"| node_exchange_log
node_role_manager -->|"updates authority"| node_hierarchy
node_role_manager -->|"selects successor"| node_failover
node_role_manager -->|"returns messages to runtime"| node_transport
node_heartbeat -.->|"reports loss"| node_role_manager
node_reconnect -->|"retries connections"| node_transport
node_exchange_log -.->|"writes JSONL for ingestion"| node_storage_ingest
node_storage_service -->|"runs ingestion"| node_storage_ingest
node_storage_service -->|"checks connectivity"| node_sql_factory
node_storage_ingest -->|"parses records"| node_line_parser
node_storage_ingest -->|"writes batches"| node_sql_factory
node_sql_factory -->|"opens connections"| node_database
node_query_api -->|"queries logs"| node_database

click node_commander "https://github.com/wahid989/falcon/blob/main/src/agents/commander.py"
click node_follower "https://github.com/wahid989/falcon/blob/main/src/agents/follower.py"
click node_dual_role "https://github.com/wahid989/falcon/blob/main/src/agents/dual_role.py"
click node_decision "https://github.com/wahid989/falcon/blob/main/src/decision/engine.py"
click node_follower_state "https://github.com/wahid989/falcon/blob/main/src/state/follower_state.py"
click node_hierarchy "https://github.com/wahid989/falcon/blob/main/src/agents/hierarchy.py"
click node_role_manager "https://github.com/wahid989/falcon/blob/main/src/roles/manager.py"
click node_heartbeat "https://github.com/wahid989/falcon/blob/main/src/agents/heartbeat.py"
click node_failover "https://github.com/wahid989/falcon/blob/main/src/roles/failover.py"
click node_validator "https://github.com/wahid989/falcon/blob/main/src/schema/validator.py"
click node_transport "https://github.com/wahid989/falcon/blob/main/src/transport/tcp.py"
click node_reconnect "https://github.com/wahid989/falcon/blob/main/src/transport/reconnect.py"
click node_exchange_log "https://github.com/wahid989/falcon/blob/main/src/logging/exchange.py"
click node_storage_ingest "https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs"
click node_line_parser "https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/LogRecordParser.cs"
click node_storage_service "https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs"
click node_sql_factory "https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs"
click node_query_api "https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Api/ApiEndpoints.cs"

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_commander,node_follower,node_dual_role,node_decision,node_follower_state toneBlue
class node_hierarchy,node_role_manager,node_heartbeat,node_failover toneAmber
class node_validator,node_transport,node_reconnect toneMint
class node_exchange_log,node_storage_ingest,node_line_parser,node_storage_service,node_sql_factory,node_database,node_query_api toneRose
class node_operator toneIndigo
```

## Components

### Agent workflow

- [Commander](https://github.com/wahid989/falcon/blob/main/src/agents/commander.py): `src/agents/commander.py`
- [Follower](https://github.com/wahid989/falcon/blob/main/src/agents/follower.py): `src/agents/follower.py`
- [Dual-role runtime](https://github.com/wahid989/falcon/blob/main/src/agents/dual_role.py): `src/agents/dual_role.py`
- [Decision engine](https://github.com/wahid989/falcon/blob/main/src/decision/engine.py): `src/decision/engine.py`
- [Follower state](https://github.com/wahid989/falcon/blob/main/src/state/follower_state.py): `src/state/follower_state.py`

### Roles and recovery

- [Hierarchy](https://github.com/wahid989/falcon/blob/main/src/agents/hierarchy.py): `src/agents/hierarchy.py`
- [Role manager](https://github.com/wahid989/falcon/blob/main/src/roles/manager.py): `src/roles/manager.py`
- [Heartbeat monitor](https://github.com/wahid989/falcon/blob/main/src/agents/heartbeat.py): `src/agents/heartbeat.py`
- [Failover selection](https://github.com/wahid989/falcon/blob/main/src/roles/failover.py): `src/roles/failover.py`

### Protocol and transport

- [Message validator](https://github.com/wahid989/falcon/blob/main/src/schema/validator.py): `src/schema/validator.py`
- [TCP transport](https://github.com/wahid989/falcon/blob/main/src/transport/tcp.py): `src/transport/tcp.py`
- [Reconnect transport](https://github.com/wahid989/falcon/blob/main/src/transport/reconnect.py): `src/transport/reconnect.py`

### Logs and storage

- [Exchange logging](https://github.com/wahid989/falcon/blob/main/src/logging/exchange.py): `src/logging/exchange.py`
- [Log ingestion](https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs): `storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs`
- [Log parsing](https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/LogRecordParser.cs): `storage/dotnet/src/FalconStorage/Ingestion/LogRecordParser.cs`
- [Ingestion service](https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs): `storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs`
- [SQL connections](https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs): `storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs`
- **SQL Server**
- [Query API](https://github.com/wahid989/falcon/blob/main/storage/dotnet/src/FalconStorage/Api/ApiEndpoints.cs): `storage/dotnet/src/FalconStorage/Api/ApiEndpoints.cs`

### Other components

- **Command initiator**

## Connections

- Command initiator → Commander: initiates commands
- Commander → Message validator: validates messages (evidence: `src/agents/commander.py`)
- Commander → TCP transport: sends commands (evidence: `src/agents/commander.py`)
- TCP transport → Follower: delivers messages
- Follower → Message validator: validates messages (evidence: `src/agents/follower.py`)
- Follower → Decision engine: evaluates commands (evidence: `src/agents/follower.py`)
- Follower → Follower state: reads state (evidence: `src/agents/follower.py`)
- Dual-role runtime → Commander: uses (evidence: `src/agents/dual_role.py`)
- Dual-role runtime → Follower: uses (evidence: `src/agents/dual_role.py`)
- Dual-role runtime → Hierarchy: manages chain (evidence: `src/agents/dual_role.py`)
- Dual-role runtime → Role manager: handles roles (evidence: `src/agents/dual_role.py`)
- Dual-role runtime → Heartbeat monitor: uses (evidence: `src/agents/dual_role.py`)
- Dual-role runtime → Exchange logging: records exchanges (evidence: `src/agents/dual_role.py`)
- Role manager → Hierarchy: updates authority (evidence: `src/roles/manager.py`)
- Role manager → Failover selection: selects successor (evidence: `src/roles/manager.py`)
- Role manager → TCP transport: returns messages to runtime (evidence: `src/roles/manager.py`)
- Heartbeat monitor → Role manager: reports loss
- Reconnect transport → TCP transport: retries connections (evidence: `src/transport/reconnect.py`)
- Exchange logging → Log ingestion: writes JSONL for ingestion
- Ingestion service → Log ingestion: runs ingestion (evidence: `storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs`)
- Ingestion service → SQL connections: checks connectivity (evidence: `storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs`)
- Log ingestion → Log parsing: parses records (evidence: `storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs`)
- Log ingestion → SQL connections: writes batches (evidence: `storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs`)
- SQL connections → SQL Server: opens connections (evidence: `storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs`)
- Query API → SQL Server: queries logs
