AeroGuard

Advanced Analyst Decision-Support System with AI-powered triage, real-time incident management, and blockchain-verified audit trails.

Features

• AI-Powered Triage: Gemini/OpenRouter LLM analysis with confidence scoring
• Real-Time Updates: WebSocket streaming for live incident updates
• Audio Alerts: ElevenLabs text-to-speech for critical incidents
• Blockchain Audit: Solana transaction verification
• Vector Search: MongoDB Atlas vector search for semantic incident matching
• Interactive Map: Ottawa-bounded map with incident markers
• Proof System: Verifiable evidence of all advanced features

Quick Start

Prerequisites

• Python 3.9+ with pip
• Node.js 18+ with npm
• MongoDB (local or Atlas)
• API Keys (optional for demo mode):
  • Google Gemini API key
  • ElevenLabs API key (optional)
  • Solana RPC endpoint (optional)

Installation

# Install all dependencies
npm run install:all

# Or manually:
npm install
cd packages/api && pip install -r requirements.txt
cd packages/dashboard && npm install

Configuration

1. Copy environment file:

cd packages/api
cp .env.example .env

2. Edit .env and set your API keys:

# Mode: DEMO or PROD_REALTIME
MODE=DEMO

# Required for PROD_REALTIME mode
GEMINI_API_KEY=your_key_here
MONGODB_URI=your_mongodb_uri
ELEVENLABS_API_KEY=your_key_here

# Or use mock mode for development
USE_MOCK_GEMINI=true
USE_MOCK_MONGODB=true
USE_MOCK_ELEVENLABS=true

Running the Application

Option 1: Using npm scripts (recommended)

# Start both API and UI
npm run dev

Option 2: Using Makefile

# Start both API and UI
make dev

# Or start individually
make dev-api   # API only
make dev-ui    # UI only

Option 3: Manual

# Terminal 1: Start API
cd packages/api
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Linux/Mac
uvicorn main:app --host 127.0.0.1 --port 8000 --reload

# Terminal 2: Start UI
cd packages/dashboard
npm run dev

Access the Application

• UI Dashboard: http://localhost:5173
• API Docs: http://127.0.0.1:8000/docs
• Health Check: http://127.0.0.1:8000/health

Testing

End-to-End Tests

# Install test dependencies (first time only)
npm run test:install

# Run tests
npm run test:e2e

# Or using Makefile
make test-e2e

Full Test Suite

# Check services + run tests
npm run test:all

# Or using Makefile
make test-all

Expected Test Output

========================================
AeroGuard End-to-End Test Suite
========================================

tests/test_e2e.py::test_health_endpoint_performance PASSED
tests/test_e2e.py::test_ready_endpoint_dependency_status PASSED
tests/test_e2e.py::test_create_and_retrieve_incident PASSED
tests/test_e2e.py::test_websocket_real_time_events PASSED
tests/test_e2e.py::test_triage_endpoint_and_audit PASSED
tests/test_e2e.py::test_elevenlabs_audio_endpoint PASSED
tests/test_e2e.py::test_solana_endpoint PASSED

======================== 7 passed in 12.34s ========================

Project Structure

AeroGuard/
├── packages/
│   ├── api/                 # FastAPI backend
│   │   ├── main.py         # Application entry point
│   │   ├── config.py       # Configuration and validation
│   │   ├── routers/        # API endpoints
│   │   ├── services/       # Business logic
│   │   ├── tests/          # End-to-end tests
│   │   └── requirements.txt
│   └── dashboard/          # React frontend
│       ├── src/
│       │   ├── components/ # UI components
│       │   ├── hooks/      # React hooks
│       │   └── lib/        # Utilities
│       └── package.json
├── scripts/                # Build and test scripts
├── Makefile               # Development commands
├── package.json           # Root package configuration
└── README.md

Key Commands Reference

Development

Command	Description
npm run dev	Start API + UI
npm run dev:api	Start API only
npm run dev:dashboard	Start UI only
make dev	Start API + UI (Makefile)

Testing

Command	Description
npm run test:e2e	Run end-to-end tests
npm run test:all	Check services + run tests
npm run test:install	Install test dependencies
make test-e2e	Run tests (Makefile)

Installation

Command	Description
npm run install:all	Install all dependencies
make install	Install all dependencies (Makefile)

Utilities

Command	Description
make help	Show all available commands
make clean	Clean build artifacts

Mode Configuration

DEMO Mode (Default)

• Allows mock services
• Relaxed validation
• Shows seed data
• Good for development

MODE=DEMO
USE_MOCK_GEMINI=true
USE_MOCK_MONGODB=true

PROD_REALTIME Mode

• Requires all real services
• Strict validation
• No mocks allowed
• Server exits if dependencies missing

MODE=PROD_REALTIME
USE_MOCK_GEMINI=false
USE_MOCK_MONGODB=false
GEMINI_API_KEY=your_key
MONGODB_URI=your_uri
ELEVENLABS_API_KEY=your_key

Troubleshooting

API won't start

1. Check Python version: python --version (need 3.9+)
2. Activate virtual environment
3. Install dependencies: pip install -r requirements.txt
4. Check .env file exists and has required keys

Tests fail

1. Ensure API is running: curl http://127.0.0.1:8000/health
2. Install test dependencies: npm run test:install
3. Check MongoDB connection
4. See packages/api/TESTING.md for detailed troubleshooting

UI won't start

1. Check Node version: node --version (need 18+)
2. Install dependencies: cd packages/dashboard && npm install
3. Check if port 5173 is available

Documentation

• API Documentation: http://127.0.0.1:8000/docs (when running)
• Testing Guide: packages/api/TESTING.md
• Environment Variables: packages/api/.env.example

License

MIT

Support

For issues and questions, please check the documentation or create an issue in the repository.