Creating a common operating picture through real-time sensor intelligence
When crisis strikes, information is survival. First responders need a unified view of the operational environment—sensor data, environmental readings, threat assessments—all in real-time, all in one place.
Black Relay was born from a hackathon organized by Arrowhead Research, an organization dedicated to bridging intelligence, special operations expertise, and corporate leadership. Leveraging methodologies from former intelligence and special operations professionals, our mission is to aggregate IoT sensor data from edge devices and transform it into actionable intelligence for emergency coordinators.
Whether it's a natural disaster, hazmat situation, or tactical operation, Black Relay creates a common operating picture that helps responders make informed decisions when every second counts.
- MQTT-based data ingestion from edge compute sensors
- Supports multiple sensor types: temperature, motion, air quality, gas detection, WiFi reconnaissance, and more
- Automatic event storage and categorization
- Four-tier escalation system: DETECT → ALERT → ALARM → THREAT
- Event acknowledgment tracking
- Historical event querying with timestamp filters
- Flexible JSON payloads for diverse sensor data
- Interactive maps powered by Leaflet.js and OpenStreetMap
- Real-time sensor location tracking
- Situational awareness through geographic context
- Admin and analyst user roles
- Session-based authentication with JWT
- Secure, httpOnly cookie implementation
- Backend: Node.js/Express with MongoDB
- Frontend: React 19 with TypeScript, Vite, and Tailwind CSS
- Infrastructure: Dockerized microservices, MQTT broker (Mosquitto), Caddy reverse proxy
- Maps: Self-hosted OpenStreetMap tile server
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Edge │ │ MQTT │ │ Express │
│ Sensors │────────▶│ Broker │────────▶│ API │
│ │ MQTT │ (Mosquitto) │ Sub │ │
└─────────────┘ └──────────────┘ └──────┬──────┘
│
│ REST API
▼
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ React │ │ MongoDB │ │ OSM │
│ Dashboard │◀────────│ Database │ │ Tile Server │
│ (Leaflet) │ Query │ (Events) │ │ (Maps) │
└─────────────┘ └──────────────┘ └─────────────┘
Data Flow:
- Edge sensors publish JSON data to MQTT topics
- Backend subscribes to topics and listens for messages
- Incoming messages automatically stored as events in MongoDB
- Frontend queries events via REST API
- Dashboard displays events with geographic context
- Docker & Docker Compose
- Node.js 20+ (for local development)
- npm or yarn
# Clone the repository
git clone https://github.com/Black-Relay/web-app
cd web-app/docker-compose/dev
# Start all services
docker compose up -d
# Access the application
# Frontend: http://localhost:5173
# API: http://localhost:3001
# API Docs: http://localhost:3001/docsDefault Login Credentials:
- Username:
admin - Password:
admin
cd api
npm run seed# Python script (requires paho-mqtt)
pip install paho-mqtt
python3 scripts/send_sensor_data.py -b mqtt://localhost:1883 -t environment_sensor| Document | Description |
|---|---|
| Backend Architecture | API design, database schemas, ERD |
| Development Guide | Setup instructions, workflows, commands |
| Session Fix | Authentication persistence implementation |
| Nginx SPA Fix | React Router production routing solution |
| MQTT Sender Tool | Testing tool for sensor data simulation |
| Registry Setup | GitHub Container Registry configuration |
| Topic | Description | Use Case |
|---|---|---|
digital_temp |
Temperature monitoring | Environmental conditions |
motion |
Motion detection events | Perimeter security |
accelerometer |
Vibration/acceleration data | Structural monitoring |
air_quality |
PPM readings | Hazmat situations |
gas |
CO2/VOC detection | Atmospheric hazards |
optical_distance |
Proximity measurements | Object detection |
proximity_light |
Light sensor data | Visibility assessment |
kismet |
WiFi packet capture | Network reconnaissance |
# View MongoDB data
docker exec -it mongodb mongosh -u admin -p password
# Subscribe to MQTT topic (verify data flow)
mosquitto_sub -h localhost -p 1883 -t {topic} -v
# Run dummy data generators
cd api && npm run dummy
# Cleanup environment
docker compose down --rmi local && docker volume rm api_mongodb_data|
Backend
|
Frontend
|
|
Infrastructure
|
Services
|
- Real-time MQTT sensor integration
- Event escalation system (DETECT → ALERT → ALARM → THREAT)
- Geographic visualization with maps
- Role-based access control
- Session persistence
- Data visualization dashboards
- CSV/JSON data exports
- Historical trend analysis
- Advanced filtering and search
- Mobile responsiveness optimization
- Automated testing suite
Black Relay was created during an Arrowhead Research hackathon and is actively being developed. Contributions are welcome!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- [Arrowhead Research) - For organizing the hackathon that brought this project to life
- Code Metal - For sponsoring the project
- Open Source Community - For the amazing tools and libraries that made this possible
When crisis strikes, every second counts. Black Relay delivers the intelligence you need, when you need it.