A comprehensive command center dashboard for defense intelligence and border surveillance operations.
This document serves as the complete reference guide for the Vigilance platform. It covers architecture, implementation status, setup instructions, and development roadmap.
- Project Overview
- System Architecture
- Technology Stack
- Directory Structure
- Frontend Guide
- Backend Guide
- ML/AI Integration
- Data Flow
- Current Progress
- Remaining Work
- Getting Started
- Deployment
- API Reference
- Code Conventions
- Troubleshooting
Vigilance is an AI-powered autonomous surveillance platform designed for military and border security operations. It combines:
- Real-time sensor fusion from multiple data sources (drones, cameras, radar, motion sensors)
- AI-driven threat classification using computer vision (YOLOv8)
- Predictive analytics for threat pattern recognition
- Unified command dashboard for operators
| Capability | Description | Target Spec |
|---|---|---|
| Threat Classification | AI classifies threats Level 1-5 | 95% accuracy, <5s response |
| Pattern Recognition | Predicts threats 24hrs ahead | 85% accuracy |
| Data Fusion | Combines 1000+ sensor inputs | <100ms latency |
| Real-time Alerts | WebSocket-based notifications | Instant delivery |
- LAC Border Monitoring - High-altitude autonomous surveillance
- Desert Perimeter Security - 500km+ coverage zones
- Coastal Security - Maritime-land coordination
- Counter-Terrorism - Urban surveillance with civilian safety
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β VIGILANCE SYSTEM β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β PRESENTATION LAYER β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββββββββββ β β
β β β Navbar β β Sidebar β β Dashboard β β ThreatMap β β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββββββββββ β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββββββββββ β β
β β β AlertsFeed β β VideoFeed β β Prediction β β StatsCards β β β
β β βββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββββββββββ β β
β β React + Vite + Tailwind β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β API LAYER β β
β β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β β
β β β /threats β β /alerts β β /sensors β β/predict β β /status β β β
β β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β β
β β β β
β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β WebSocket (Socket.io) β β β
β β β Real-time alerts, sensor updates β β β
β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β Express + TypeScript β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β ML/AI LAYER [TODO] β β
β β ββββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββββββ β β
β β β YOLOv8 Object β β LSTM Pattern β β Ensemble Threat β β β
β β β Detection β β Recognition β β Classification β β β
β β ββββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββββββ β β
β β Python + PyTorch/TensorFlow β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β DATA LAYER [TODO] β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β β
β β β PostgreSQL β β Redis β β Kafka β β β
β β β (Alerts DB) β β (Cache) β β (Streaming) β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β SENSOR LAYER [TODO] β β
β β βββββββββ βββββββββ βββββββββ βββββββββ βββββββββ βββββββββ β β
β β β Drone β βCamera β β Radar β βMotion β βThermalβ β Satel β β β
β β βββββββββ βββββββββ βββββββββ βββββββββ βββββββββ βββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Layer | Technology | Status |
|---|---|---|
| Frontend | React 18, Vite, TypeScript | β Complete |
| Styling | Tailwind CSS (custom military theme) | β Complete |
| Maps | Leaflet.js (dark theme) | β Complete |
| Charts | Recharts | β Complete |
| Icons | Lucide React | β Complete |
| Backend | Express.js, TypeScript | β Complete |
| Real-time | Socket.io | β Complete |
| Containerization | Docker, docker-compose | β Complete |
| Layer | Technology | Status |
|---|---|---|
| ML/AI | Python, PyTorch, YOLOv8 | β TODO |
| Database | PostgreSQL | β TODO |
| Cache | Redis | β TODO |
| Message Queue | Apache Kafka | β TODO |
| Auth | JWT, bcrypt | β TODO |
vigilance-dashboard/
β
βββ π Docs/ # Project documentation
β βββ Project Layman.pdf # Non-technical overview
β βββ Vigilance Proto Build Plan.pdf # Technical specifications
β
βββ π frontend/ # React frontend application
β βββ π src/
β β βββ π api/ # API client layer
β β β βββ index.ts # Axios instance + API functions
β β β
β β βββ π components/ # React UI components
β β β βββ AlertsFeed.tsx # Real-time alerts list
β β β βββ Dashboard.tsx # Main dashboard layout
β β β βββ Navbar.tsx # Top navigation bar
β β β βββ PredictionChart.tsx # 24-hour threat forecast
β β β βββ Sidebar.tsx # Left navigation sidebar
β β β βββ StatsCard.tsx # Statistics display card
β β β βββ ThreatMap.tsx # Interactive Leaflet map
β β β βββ VideoFeed.tsx # Simulated camera feed
β β β
β β βββ π hooks/ # Custom React hooks
β β β βββ useAlerts.ts # Alert management hook
β β β
β β βββ π styles/ # CSS and styling
β β β βββ globals.css # Global styles + Tailwind
β β β
β β βββ π types/ # TypeScript definitions
β β β βββ index.ts # All interfaces/types
β β β
β β βββ App.tsx # Root application component
β β βββ main.tsx # React entry point
β β
β βββ index.html # HTML template
β βββ package.json # Dependencies
β βββ tailwind.config.js # Tailwind configuration
β βββ tsconfig.json # TypeScript config
β βββ vite.config.ts # Vite build config
β βββ nginx.conf # Production nginx config
β βββ Dockerfile # Frontend container
β
βββ π backend/ # Express backend API
β βββ π src/
β β βββ π data/ # Data layer
β β β βββ mockData.ts # Demo mock data
β β β
β β βββ π routes/ # API route handlers
β β β βββ alerts.ts # GET/PATCH /api/alerts
β β β βββ health.ts # GET /api/health
β β β βββ predictions.ts # GET /api/predictions
β β β βββ sensors.ts # GET /api/sensors
β β β βββ status.ts # GET /api/status
β β β βββ threats.ts # GET /api/threats
β β β
β β βββ π realtime/ # WebSocket handlers
β β β βββ alertSimulator.ts # Demo alert generator
β β β
β β βββ server.ts # Express app entry point
β β
β βββ package.json # Dependencies
β βββ tsconfig.json # TypeScript config
β βββ Dockerfile # Backend container
β
βββ π ml/ [TODO] # Machine learning models
β βββ π models/ # Trained model files
β β βββ yolov8_threat.pt # Object detection model
β β βββ lstm_pattern.h5 # Pattern recognition
β β βββ ensemble_classifier.pkl # Threat classifier
β β
β βββ π inference/ # Inference servers
β β βββ object_detection.py # YOLOv8 inference API
β β βββ pattern_recognition.py # LSTM inference
β β βββ threat_classifier.py # Ensemble inference
β β
β βββ π training/ # Training scripts
β β βββ train_yolo.py
β β βββ train_lstm.py
β β βββ train_ensemble.py
β β
β βββ requirements.txt # Python dependencies
β βββ Dockerfile # ML container
β
βββ docker-compose.yml # Container orchestration
βββ .env.example # Environment template
βββ .gitignore # Git ignore rules
βββ README.md # This handbook
App.tsx
βββ Navbar.tsx # Fixed top bar
β βββ Logo + Branding
β βββ System Status (OPERATIONAL)
β βββ Clock (real-time)
β βββ Notifications Bell
β βββ User Dropdown
β
βββ Sidebar.tsx # Fixed left navigation
β βββ Navigation Menu (8 items)
β βββ System Status Bars
β
βββ Dashboard.tsx # Main content area
βββ StatsCard.tsx (Γ4) # Top statistics row
β βββ Active Alerts
β βββ Personnel
β βββ Sensors Online
β βββ Global Ops
β
βββ ThreatMap.tsx # Interactive map (left)
β βββ Sensor markers
β βββ Threat zone circles
β βββ Legend overlay
β
βββ VideoFeed.tsx # Camera feed (right)
β βββ Detection boxes
β βββ Threat classification
β βββ Timestamp overlay
β
βββ PredictionChart.tsx # Forecast chart (left)
β βββ 24-hour timeline
β βββ Multi-sector lines
β βββ Risk threshold
β
βββ AlertsFeed.tsx # Alerts list (right)
βββ Priority coloring
βββ Expandable details
βββ Acknowledge button
Defines all TypeScript interfaces:
Threat- Threat classification resultAlert- Security notificationSensor- Sensor device infoPredictionPoint- Forecast data
Axios client for backend communication:
getThreats()- Fetch active threatsgetAlerts()- Fetch alerts (paginated)getSensors()- Fetch sensor statusgetPredictions()- Fetch 24hr forecast
Custom hook for alert management:
- Demo mode with simulated alerts
- Real-time updates (every 20s)
- Acknowledge functionality
Custom military theme:
commandcolors (dark slate)alertcolors (reds)statuscolors (green/yellow/red)- Custom animations (pulse, radar-sweep)
server.ts
βββ Middleware
β βββ helmet (security headers)
β βββ cors (cross-origin)
β βββ express.json (body parsing)
β
βββ Routes
β βββ /api/health β health.ts
β βββ /api/threats β threats.ts
β βββ /api/alerts β alerts.ts
β βββ /api/sensors β sensors.ts
β βββ /api/predictions β predictions.ts
β βββ /api/status β status.ts
β
βββ WebSocket (Socket.io)
β βββ 'connection' event
β βββ 'alert:new' broadcasts
β βββ 'subscribe' for feeds
β
βββ Alert Simulator
βββ Generates demo alerts every 15-45s
Each route file follows the pattern:
// routes/example.ts
import { Router } from 'express';
import { MOCK_DATA } from '../data/mockData.js';
const router = Router();
router.get('/', (req, res) => {
res.json({
success: true,
data: MOCK_DATA,
timestamp: new Date().toISOString(),
});
});
export default router;Contains all demo data:
MOCK_THREATS- 4 sample threatsMOCK_ALERTS- 5 sample alertsMOCK_SENSORS- 12 sensors (cameras, radars, drones, etc.)generatePredictions()- Creates 24hr forecast
π΄ TEAM TODO: Replace this file's exports with database queries.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ML SERVICE (Python) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β OBJECT DETECTION β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β β β YOLOv8 (ultralytics) β β β
β β β - Input: Video frames (640Γ640) β β β
β β β - Output: Bounding boxes + labels β β β
β β β - Classes: person, vehicle, animal β β β
β β β - Target: <100ms inference β β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β PATTERN RECOGNITION β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β β β LSTM Network β β β
β β β - Input: Time-series sensor data β β β
β β β - Window: 48 hours historical β β β
β β β - Output: 24hr threat probability β β β
β β β - Per-sector predictions β β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β THREAT CLASSIFICATION β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β β β Ensemble (CNN + LSTM + RF) β β β
β β β - Combines detection + patterns β β β
β β β - Output: Threat level 1-5 β β β
β β β - Confidence score 0-100% β β β
β β β - Target: 95% accuracy β β β
β β βββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β API Endpoints (FastAPI): β
β POST /detect - Object detection on frame β
β POST /predict - Pattern prediction β
β POST /classify - Threat classification β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Frontend: VideoFeed.tsx
β (captures frame)
Backend: POST /api/ml/detect
β (forwards to ML service)
ML Service: YOLOv8 inference
β (returns detections)
Frontend: Renders bounding boxes
Sensors: Motion, thermal, radar data
β (collected over 48hrs)
Backend: Aggregates time-series
β (sends to ML)
ML Service: LSTM prediction
β (24hr forecast)
Frontend: PredictionChart displays
Detections + Patterns + Context
β (combined features)
ML Service: Ensemble classifier
β (threat level 1-5)
Backend: Creates alert if level β₯ 3
β (WebSocket broadcast)
Frontend: AlertsFeed updates
Create: ml/ directory at project root:
mkdir -p ml/{models,inference,training}
touch ml/requirements.txt
touch ml/Dockerfile
touch ml/inference/object_detection.py
touch ml/inference/pattern_recognition.py
touch ml/inference/threat_classifier.pyRecommended ML requirements.txt:
torch>=2.0.0
ultralytics>=8.0.0 # YOLOv8
tensorflow>=2.13.0 # LSTM
scikit-learn>=1.3.0 # Random Forest
fastapi>=0.100.0 # API server
uvicorn>=0.23.0 # ASGI server
opencv-python>=4.8.0
numpy>=1.24.0
1. Sensor detects anomaly
β
2. ML classifies threat (Level 1-5)
β
3. Backend creates Alert object
β
4. WebSocket broadcasts 'alert:new'
β
5. Frontend useAlerts hook receives
β
6. AlertsFeed re-renders with new alert
β
7. Operator acknowledges via UI
β
8. PATCH /api/alerts/:id/acknowledge
β
9. Alert status updated to 'acknowledged'
ββββββββββββββββββββββββββββββββββββββββββββββ
β Every 5 seconds β
ββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Dashboard.tsx useEffect triggers β
β 2. Simulated stats fluctuation (demo) β
β 3. StatsCards re-render with new values β
ββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββββββββββββββββββββββββββββββββββββ
β Every 20 seconds β
ββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. useAlerts hook generates demo alert β
β 2. AlertsFeed prepends new alert β
β 3. Notification count updates β
ββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββββββββββββββββββββββββββββββββββββ
β WebSocket (real-time) β
ββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Backend alertSimulator fires β
β 2. Socket.io emits 'alert:new' β
β 3. All connected clients receive β
ββββββββββββββββββββββββββββββββββββββββββββββ
| Component | Description | Files |
|---|---|---|
| Project Structure | Monorepo with frontend/backend | All directories |
| Frontend Core | Vite + React + TypeScript | package.json, configs |
| Tailwind Theme | Custom military dark theme | tailwind.config.js |
| Navbar | Top navigation with clock, status | Navbar.tsx |
| Sidebar | Collapsible nav with system status | Sidebar.tsx |
| Dashboard | Main layout composing all widgets | Dashboard.tsx |
| Stats Cards | 4 metric cards with animations | StatsCard.tsx |
| Threat Map | Leaflet map with sensors/threats | ThreatMap.tsx |
| Video Feed | Simulated camera with detections | VideoFeed.tsx |
| Alerts Feed | Real-time alert list | AlertsFeed.tsx |
| Prediction Chart | 24-hour forecast chart | PredictionChart.tsx |
| Type Definitions | All TypeScript interfaces | types/index.ts |
| API Client | Axios with interceptors | api/index.ts |
| Alerts Hook | Real-time alert state | hooks/useAlerts.ts |
| Backend Server | Express with Socket.io | server.ts |
| API Routes | All 6 endpoints | routes/*.ts |
| Mock Data | Demo data for all entities | data/mockData.ts |
| Alert Simulator | WebSocket demo broadcaster | realtime/alertSimulator.ts |
| Docker Setup | Frontend + Backend containers | Dockerfile Γ 2 |
| Docker Compose | Orchestration config | docker-compose.yml |
| Documentation | This handbook | README.md |
| Component | Description | Priority |
|---|---|---|
| Authentication | JWT login system | π΄ High |
| Database | PostgreSQL + Prisma | π΄ High |
| ML Service | Python + YOLOv8 | π΄ High |
| Real Sensors | Actual data sources | π΄ High |
| Pattern LSTM | Time-series prediction | π‘ Medium |
| Ensemble Classifier | Threat level model | π‘ Medium |
| User Management | Roles and permissions | π‘ Medium |
| Audit Logging | Action tracking | π‘ Medium |
| Additional Pages | Threats, Operations, etc. | π’ Low |
| Mobile Responsive | Tablet/phone layouts | π’ Low |
- Node.js 20+ (LTS recommended)
- npm 9+ or yarn
- Docker (for containerized deployment)
- Python 3.10+ (for ML, when implemented)
git clone <repository-url>
cd vigilance-dashboard# Frontend
cd frontend
npm install
# Backend (new terminal)
cd ../backend
npm installTerminal 1 - Backend:
cd backend
npm run dev
# β
Running at http://localhost:3001Terminal 2 - Frontend:
cd frontend
npm run dev
# β
Running at http://localhost:5173Navigate to http://localhost:5173 in your browser.
# Build and start all services
docker-compose up --build
# Access:
# - Frontend: http://localhost:3000
# - Backend: http://localhost:3001# Build frontend
cd frontend
docker build -t vigilance-frontend .
# Build backend
cd ../backend
docker build -t vigilance-backend .
# Run
docker run -p 3000:80 vigilance-frontend
docker run -p 3001:3001 vigilance-backendCopy .env.example to .env:
# Backend
PORT=3001
NODE_ENV=production
CORS_ORIGIN=http://localhost:3000
# Database (TODO)
# DATABASE_URL=postgresql://...
# Auth (TODO)
# JWT_SECRET=your-secret- Development:
http://localhost:3001/api - Production: Configure via environment
GET /api/health
Response: { success: true, data: { status: "healthy" } }
GET /api/threats
GET /api/threats/active
GET /api/threats/:id
Response: { success: true, data: Threat[] }
GET /api/alerts?page=1&limit=20
GET /api/alerts/:id
PATCH /api/alerts/:id/acknowledge
Response: { success: true, data: Alert[], pagination: {...} }
GET /api/sensors
GET /api/sensors/:id
GET /api/sensors/sector/:sector
GET /api/sensors/stats
Response: { success: true, data: Sensor[] }
GET /api/predictions
GET /api/predictions/sector/:sector
Response: { success: true, data: SectorPrediction[] }
GET /api/status
Response: { success: true, data: SystemStatus }
// Client connection
socket.on('connected', (msg) => console.log(msg));
// New alert broadcast
socket.on('alert:new', (alert) => {
// Update UI with new alert
});
// Subscribe to specific feed
socket.emit('subscribe', 'alerts');- Components:
PascalCase.tsx(e.g.,AlertsFeed.tsx) - Hooks:
camelCase.tswithuseprefix (e.g.,useAlerts.ts) - Routes:
lowercase.ts(e.g.,alerts.ts) - Types:
index.tsintypes/directory
/**
* =============================================================================
* VIGILANCE DASHBOARD - Component Name
* =============================================================================
*
* Description of what this component does.
*
* Props:
* - propName: description
*
* TODO: Future improvements
* =============================================================================
*/
import React from 'react';
interface ComponentProps {
// Props interface
}
const Component: React.FC<ComponentProps> = (props) => {
// Implementation
};
export default Component;Use these markers for team handoff:
// TODO: Description of what needs to be done
// TODO: Replace mock data with real API
// TODO: Integrate YOLOv8 classification# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install# Find and kill process on port 3001
lsof -i :3001
kill -9 <PID># Clean Docker cache
docker system prune -a
docker-compose build --no-cache# Restart TypeScript server in VS Code
Cmd+Shift+P β "TypeScript: Restart TS Server"| Role | Responsibility |
|---|---|
| Frontend Lead | Dashboard UI, React components |
| Backend Lead | API routes, WebSocket, database |
| ML Engineer | YOLOv8, LSTM, classification models |
| DevOps | Docker, deployment, CI/CD |
Internal Project - Not for Public Distribution
Built for the Vigilance Team π‘οΈ