Content
# Nexus Earth: Autonomous Multi-Agent Disaster Intelligence Platform
An enterprise-grade, multi-agent disaster coordination and situational awareness platform standardizing crisis response workflows.
---
## Problem Statement
During environmental disasters (wildfires, flooding, earthquakes), every second determines the scale of structural loss and civilian casualties. However, standard emergency command centers suffer from data fragmentation across disconnected platforms (weather monitoring, GIS maps, hospital capacity, fleet logs).
Furthermore, dispatch operators face intense cognitive load trying to manually evaluate telemetry, verify routes, redirect ambulances, and draft incident sitreps under high-stress conditions.
## Why It Matters
Traditional response systems are reactive and siloed, leading to high operational latency. By introducing an orchestrated **Autonomous Agent Swarm** coupled with decoupled **Model Context Protocol (MCP)** microservices, Nexus Earth automates the analytical path from raw environmental data to coordinated action—saving up to 70% in response times while enforcing absolute human oversight.
---
## Solution Overview
Nexus Earth bridges the gap between threat detection and emergency response:
1. **Dual-Mode Interface Profile:**
* **Command Center View (Default):** A simplified, cockpit dashboard answering 4 core questions: *What happened? What is the AI doing? What should we do? What outcome is expected?*
* **Advanced Engineering View:** A high-density telemetry console representing uvicorn/Next.js node health, Swarm DAG graph consoles, and real-time MCP server tables.
2. **Autonomous Agent Swarm:** Executes a dependency chain of 10 specialized agents organized as a Directed Acyclic Graph (DAG) task scheduling engine.
3. **Human-in-the-Loop (HITL) Safety Gates:** Suspends execution on high-impact steps (e.g., evacuation warnings and triage redirection), requiring explicit dispatcher approval or parameter overrides.
4. **Decoupled MCP Layer:** Integrates standardized JSON-RPC 2.0 tool services (Maps, Weather, Search, Resource DB, Emergency Services, Knowledge Base).
5. **Secure Cryptographic Audit Trail:** Chained SHA-256 block ledger logs preventing database tampering.
---
## System Architecture Diagram
```mermaid
flowchart TB
%% Entities
Operator["Operator (Web Portal)"]
Frontend["Next.js Frontend (Zustand, React 19)"]
Backend["FastAPI Backend (Uvicorn)"]
Redis["Redis Pub/Sub (Event Bus)"]
DB[("Database (PostgreSQL/SQLite)")]
subgraph CoreBackend ["FastAPI Core Services"]
Security["Security Layer\n- JWT Authentication\n- RBAC Middleware\n- Prompt Injection Filter\n- Rate Limiting (60 r/m)"]
Orchestrator["DAG Orchestrator\n(MasterOrchestrator)"]
AuditService["Cryptographic Audit Trail\n(SHA-256 Chaining)"]
end
subgraph AgentMAS ["10 Specialized LLM Responders"]
AgentDA["1. Disaster Analysis"]
AgentWI["2. Weather Intelligence"]
AgentP["3. Prediction"]
AgentRP["4. Resource Planning"]
AgentMR["5. Medical Response (HITL)"]
AgentE["6. Evacuation (HITL)"]
AgentC["7. Communication"]
AgentSR["8. Situation Report"]
AgentNI["9. News Intelligence"]
AgentSS["10. Social Signal"]
end
subgraph MCPSubsystem ["Model Context Protocol (JSON-RPC 2.0)"]
Registry["MCP Registry"]
MCPMaps["Maps Server"]
MCPWeather["Weather Server"]
MCPSearch["Search Server"]
MCPResource["Resource DB Server"]
MCPEmergency["Emergency Services"]
MCPKB["Knowledge Base"]
end
%% Interactions
Operator -- "Renders Dashboard / Submits HITL Decisions" --> Frontend
Frontend -- "REST API (Auth, Incidents, Resources)" --> Security
Frontend -- "WebSockets (Incident Room)" --> Backend
Security --> Backend
Backend --> Orchestrator
Orchestrator -- "1. Spawns DAG workflow" --> AgentMAS
Orchestrator -- "2. Streams runtime traces" --> Redis
Redis -- "3. Forwards trace updates" --> Backend
Backend -- "4. Streams events to client" --> Frontend
AgentMR & AgentE -- "HITL Suspend Gate" --> Orchestrator
Operator -- "POST /resume (Approve/Override)" --> Orchestrator
AgentMAS -- "Query tools / Read resources" --> Registry
Registry --> MCPMaps & MCPWeather & MCPSearch & MCPResource & MCPEmergency & MCPKB
MCPResource & MCPEmergency & Orchestrator --> DB
DB --> AuditService
```
For a comprehensive explanation of our sub-systems and context listeners, see [ARCHITECTURE.md](docs/ARCHITECTURE.md).
---
## AI Agent System & MCP Integrations
### 10 Specialized Agents
Nexus Earth coordinates specialized agents to analyze and react to incoming incidents:
1. **DisasterAnalysisAgent:** Maps structural telemetry and satellite scanners.
2. **NewsIntelligenceAgent:** Extracts warning broadcasts and news alerts.
3. **SocialSignalAgent:** Evaluates local social panic and geolocation spikes.
4. **WeatherIntelligenceAgent:** Fetches microclimates and road constraints.
5. **PredictionAgent:** Models flame and flood propagation vectors.
6. **ResourcePlanningAgent:** Dispatches fleet assets and coordinates bypass routes.
7. **MedicalResponseAgent:** Maps casualty hotspots and red-alerts ICU occupancy. (HITL)
8. **EvacuationAgent:** Computes population egress corridors. (HITL)
9. **CommunicationAgent:** Formulates public broadcast advisories and SMS alerts.
10. **SituationReportAgent:** Generates federal FEMA Form 209 briefs.
### 6 Model Context Protocol (MCP) Servers
Decouples LLM code from external queries conforming to JSON-RPC 2.0 specs:
* `MapsMCPServer`: Routing buffers and spatial geo-fencing.
* `WeatherMCPServer`: Meteorology constraints and forecasts.
* `SearchMCPServer`: Local web and index scraping.
* `ResourceDBMCPServer`: SQLite database fleet and supply lookups.
* `EmergencyServicesMCPServer`: Relational incident registry additions.
* `KnowledgeBaseMCPServer`: SOP guidelines mapping.
---
## Repository Structure
```text
nexus-earth/
├── docker-compose.yml # Multi-container production setup
├── LICENSE # MIT Open Source License
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Release milestones
├── SECURITY.md # Vulnerability reporting protocol
├── CODE_OF_CONDUCT.md # Contributor Covenant CoC
├── ROADMAP.md # Future project direction
├── SUBMISSION.md # Hackathon Submission Pack
├── .env.example # Environment variable templates
├── run.bat # Windows execution batch script
├── stop.bat # Windows termination batch script
├── healthcheck.bat # Windows service validator script
│
├── backend/ # FastAPI Asynchronous Service
│ ├── Dockerfile
│ ├── requirements.txt # Python packages
│ ├── pyproject.toml # Ruff and lint configs
│ ├── scripts/
│ │ └── startup_validator.py # Env & database validator
│ └── app/ # Application Source Code
│ ├── main.py # FastAPI setup & middlewares
│ ├── core/ # Security, DB connections & seeders
│ ├── models/ # Relational tables schemas
│ ├── repository/ # Generic generic repositories
│ ├── routers/ # REST endpoints & websockets
│ ├── services/ # Orchestrator & agent scripts
│ └── tests/ # Automated unit test suite
│
├── frontend/ # Next.js 16 (React 19) Dashboard Web App
│ ├── Dockerfile
│ ├── package.json
│ ├── tsconfig.json
│ └── src/
│ ├── app/ # Next.js router pages & views
│ ├── components/ # CommandCenter & Advanced HUD layouts
│ ├── hooks/ # WebSocket connection utilities
│ └── lib/ # Zustand stores & configurations
│
└── docs/ # Architectural Documentation
├── ARCHITECTURE.md # Systems design blueprint
└── proposals/ # Archive of historical RFC designs
```
---
## Screenshots
Visual dashboard captures are stored inside `assets/screenshots/` (mock placeholders provided for release):
* **Command Center UI:** `assets/screenshots/dashboard.png` (RealTimeMap, timeline step tracker, recommendations).
* **Judge View:** `assets/screenshots/judge_view.png` (Single-screen layout summarizing impact indexes, timeline status, and briefing cards).
* **Simulation Mode:** `assets/screenshots/simulation.png` (Active incident logs and agent sequences).
---
## Installation & Quick Start
### Windows (Single-Command Setup)
Simply run `run.bat` at the repository root.
The script will automatically:
1. Verify system prerequisites (Python 3.11+, Node.js, npm, Git).
2. Build a Python virtual environment (`backend/venv`) and install dependencies.
3. Install React npm dependencies if `node_modules` is missing.
4. Generate missing `.env` (backend) and `.env.local` (frontend) files automatically.
5. Launch database schema setup and seed mock data (`backend/nexus_earth.db`).
6. Start uvicorn (port 8000) and Next.js (port 3000) background services.
7. Run automatic endpoint validations.
8. Open your default browser to `http://localhost:3000`.
To stop the services, run `stop.bat` or close the command line window.
---
## Technical Stack
| Tier | Technology | Description |
| --- | --- | --- |
| **Frontend** | Next.js 16 / React 19 | Responsive UI presentation rendering SVG nodes and maps |
| | Zustand | Client state management and WebSocket subscribers |
| | Tailwind CSS | Styling framework for HUD theme configurations |
| **Backend** | FastAPI | Asynchronous REST and WebSocket route delivery |
| | SQLAlchemy 2.0 | Dialect-agnostic generic generic CRUD layers |
| | SQLite / PostGIS | Dev relational storage (spatial and vector fallbacks) |
| | Redis | Optional pub/sub event bus caching |
| **Swarm** | Gemini LLM | Schema-compliant agent intelligence reasoning |
---
## Future Roadmap
Detailed targets are defined in [ROADMAP.md](ROADMAP.md). Highlights include:
* Multi-modal photo/drone telemetry ingestion.
* CesiumJS 3D terrain elevation map rendering.
* Hardened offline edge orchestration for remote communication trucks.
---
## Contributors
Nexus Earth is maintained by the Open Source Community. For instructions on branching, commits, and pull requests, review [CONTRIBUTING.md](CONTRIBUTING.md).
---
## License
Licensed under the [MIT License](LICENSE).
