Last refreshed: 2026-04-24. Reflects the post-merge Commander-Pilot multi-agent architecture, hazard terrain, BRAIN mode toggle, ContractChecker, and cross-mission learning.

1. System Overview

RescueSwarm is a three-component distributed system for autonomous search-and-rescue drone swarm simulation, built for VHack 2026. Five AI-coordinated drones systematically scan a disaster zone, detect survivors via thermal imaging, and report back to a human operator in real time.

Three components (each a separate process):

• Backend — Simulation engine, REST API, WebSocket, and MCP tool server (single Python process, dual-server)
• Agent — Multi-agent LLM orchestrator: one Orchestrator + one Commander + five Pilots, coordinated through a shared Blackboard
• Frontend — Real-time operator dashboard (React + Three.js 3D scene)

What changed since the March revision of this doc:

• The agent evolved from a single ReAct LLM loop into a Commander-Pilot multi-agent system with a lock-protected Blackboard.
• A fifth terrain type (hazard) was introduced — damaged urban cells with the highest survivor-probability weight.
• BRAIN mode toggle (AUTO / CLOUD / EDGE / RULES) lets the operator switch the agent between LLM and deterministic rule-based planning live.
• ContractChecker continuously self-audits the mission and can fire fresh Commander events when priorities drift.
• SessionLog enables cross-mission learning — past mission summaries prime the first Commander brief of the next run.
• Radio Panel accepts both text and voice intel; both feed the same lead_grounded event pipeline.

2. Overall Architecture

2.1 High-Level System Diagram

flowchart TB
    subgraph FRONTEND [" 🖥️  Frontend — React + TypeScript + Three.js (Vite :5173)"]
        direction LR
        UI[Operator Dashboard<br/>3D Map · Mission Log<br/>Radio Panel · Victim Comms<br/>BRAIN mode toggle]
        VOICE[Web Speech API<br/>Voice Capture]
        WS_CLIENT[WebSocket Client<br/>Live Token Stream]
    end

    subgraph BACKEND [" ⚙️  Backend — Python (FastAPI :8000 + FastMCP stdio)"]
        direction TB
        subgraph FASTAPI [FastAPI — Background Thread]
            REST[REST Endpoints<br/>/state · /run-mission<br/>/brain/* · /radio-intel<br/>/voice-command · /import-map<br/>/timeline · /log /log/stream]
            TICK[Simulation Tick Loop<br/>every 0.7s<br/>Movement · Battery · Scan<br/>Probability boost]
            WSSERVER[WebSocket Server<br/>/ws/stream]
            LLM_GW[LLM Gateway<br/>GPT-4o or Gemini<br/>Voice + Triage + Radio parsing]
        end
        subgraph FASTMCP [FastMCP — Main Thread]
            TOOLS[MCP Tool Server<br/>get_idle_drones<br/>assign_scan_zone<br/>investigate_lead · ...]
        end
        SIM[(SimulationState<br/>Singleton<br/>Drones · Zones · Survivors<br/>Leads · probability_map)]
        FASTAPI <--> SIM
        FASTMCP <--> SIM
    end

    subgraph AGENT [" 🤖  SENTINEL Agent — one Python process"]
        direction TB
        ORCH[Orchestrator<br/>asyncio poll loop 0.5s]
        CMD[Commander<br/>strategic LLM]
        PIL[Pilot ×5<br/>tactical LLM]
        BB[(Blackboard<br/>priority_map · posture<br/>urgent_redirect · zone_claims)]
        HELPERS[Helpers<br/>MissionMemory · ContractChecker<br/>ToolHooks · SessionLog<br/>WeightedPlanner]
        ORCH -- event --> CMD
        ORCH -- idle signal --> PIL
        CMD -- write --> BB
        PIL -- read/claim --> BB
        CMD -.-> HELPERS
        PIL -.-> HELPERS
        ORCH -.-> HELPERS
    end

    UI -- "GET /state (poll 800ms)" --> REST
    UI -- "POST /run-mission /reset<br/>/victim-response /guide-victim<br/>/radio-intel /brain/mode" --> REST
    VOICE -- "POST /voice-command" --> REST
    WS_CLIENT -- "WebSocket /ws/stream" --> WSSERVER

    ORCH -- "MCP stdio<br/>tool calls" --> TOOLS
    TOOLS -- "tool results" --> ORCH
    PIL -- "MCP calls" --> TOOLS
    CMD -- "POST /log /timeline /brain/active" --> REST
    PIL -- "POST /log /brain/active" --> REST

    REST --> LLM_GW
    LLM_GW -. "AI triage<br/>voice/radio grounding" .-> SIM
    WSSERVER -- "token chunks" --> WS_CLIENT

    style FRONTEND fill:#dbeafe,stroke:#3b82f6
    style BACKEND fill:#fef3c7,stroke:#d97706
    style AGENT fill:#f3e8ff,stroke:#9333ea
    style FASTAPI fill:#fffbeb,stroke:#f59e0b
    style FASTMCP fill:#fde68a,stroke:#d97706
    style SIM fill:#fee2e2,stroke:#dc2626
    style BB fill:#fce7f3,stroke:#db2777

2.2 Communication Flow