How wahid989/falcon works
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: dual_role.py Dual-role runtime · follower.py Follower · manager.py Role manager · commander.py Commander
Components 20
Agent workflow
- Commander
src/agents/commander.py - Follower
src/agents/follower.py - Dual-role runtime
src/agents/dual_role.py - Decision engine
src/decision/engine.py - Follower state
src/state/follower_state.py
Roles and recovery
- Hierarchy
src/agents/hierarchy.py - Role manager
src/roles/manager.py - Heartbeat monitor
src/agents/heartbeat.py - Failover selection
src/roles/failover.py
Protocol and transport
- Message validator
src/schema/validator.py - TCP transport
src/transport/tcp.py - Reconnect transport
src/transport/reconnect.py
Logs and storage
- Exchange logging
src/logging/exchange.py - Log ingestion
storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs - Log parsing
storage/dotnet/src/FalconStorage/Ingestion/LogRecordParser.cs - Ingestion service
storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs - SQL connections
storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs - SQL Server
- Query API
storage/dotnet/src/FalconStorage/Api/ApiEndpoints.cs
Other components
- Command initiator
Connections 25
- Command initiator → Commander: initiates commands
- Commander → Message validator: validates messages
src/agents/commander.py - Commander → TCP transport: sends commands
src/agents/commander.py - TCP transport → Follower: delivers messages
- Follower → Message validator: validates messages
src/agents/follower.py - Follower → Decision engine: evaluates commands
src/agents/follower.py - Follower → Follower state: reads state
src/agents/follower.py - Dual-role runtime → Commander: uses
src/agents/dual_role.py - Dual-role runtime → Follower: uses
src/agents/dual_role.py - Dual-role runtime → Hierarchy: manages chain
src/agents/dual_role.py - Dual-role runtime → Role manager: handles roles
src/agents/dual_role.py - Dual-role runtime → Heartbeat monitor: uses
src/agents/dual_role.py - Dual-role runtime → Exchange logging: records exchanges
src/agents/dual_role.py - Role manager → Hierarchy: updates authority
src/roles/manager.py - Role manager → Failover selection: selects successor
src/roles/manager.py - Role manager → TCP transport: returns messages to runtime
src/roles/manager.py - Heartbeat monitor → Role manager: reports loss
- Reconnect transport → TCP transport: retries connections
src/transport/reconnect.py - Exchange logging → Log ingestion: writes JSONL for ingestion
- Ingestion service → Log ingestion: runs ingestion
storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs - Ingestion service → SQL connections: checks connectivity
storage/dotnet/src/FalconStorage/Ingestion/IngestionBackgroundService.cs - Log ingestion → Log parsing: parses records
storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs - Log ingestion → SQL connections: writes batches
storage/dotnet/src/FalconStorage/Ingestion/LogIngester.cs - SQL connections → SQL Server: opens connections
storage/dotnet/src/FalconStorage/Data/SqlConnectionFactory.cs - Query API → SQL Server: queries logs