🎯 Heimdall - Real-Time Radio Source Localization

AI-powered platform for locating radio transmissions using distributed WebSDR receivers.

---

⚡ Quick Facts

• Accuracy: ±30m (68% confidence)
• Latency: <500ms processing
• Network: 7 distributed WebSDR receivers (Italian 2m/70cm bands)
• Status: Phase 7 in progress (Frontend development)

---

🚀 Quick Start (5 minutes)

# Clone repository
git clone https://github.com/fulgidus/heimdall.git
cd heimdall

# Configure environment
cp .env.example .env

# Start all services (Docker required)
docker-compose up -d

# Verify health
make health-check

Done! Open http://localhost:3000

→ Full Installation Guide

---

🏗️ Architecture

| Component | Technology | Purpose | | ------------------ | --------------------------- | -------------------- | | Backend | Python (FastAPI + Celery) | Microservices | | ML Pipeline | PyTorch Lightning + MLflow | Training & Inference | | Frontend | React + TypeScript + Mapbox | Web UI | | Storage | PostgreSQL + TimescaleDB | Time-series data | | Queue | RabbitMQ | Task orchestration | | Object Storage | MinIO (S3-compatible) | IQ data & models | | Deployment | Kubernetes + Helm | Production |

→ Architecture Deep-Dive

---

📚 Documentation

Getting Started:

• Quick Start - Setup in 5 minutes
• Development Guide - Contributing and local setup
• FAQ - Common questions

Reference:

• API Reference - REST endpoints
• Architecture - System design
• Health Checks - Service health monitoring
• Deployment - Production setup

Project:

• Contributing - How to contribute
• Roadmap - Development phases
• Changelog - Version history

→ Full Documentation Index

---

📊 Development Status

Phase Progress (6/11 complete):

✅ Phases 0-6: Infrastructure, Services, ML Pipeline, Inference
🟡 Phase 7: Frontend (In Progress)
⏳ Phases 8-10: Kubernetes, QA, Release

→ Detailed Roadmap

Performance Metrics (validated in Phase 4):

• API latency: 52ms average (P95: 52.81ms)
• Concurrent capacity: 50 simultaneous tasks
• Success rate: 100%
• Container memory: 100-300MB per service

→ Performance Report

---

🌍 Use Cases

Amateur Radio:

• DX station localization
• Interference source tracking
• Contest verification

Emergency Services:

• Search and rescue beacon location
• First responder coordination

Research:

• Radio propagation studies
• Spectrum management
• Educational demonstrations

---

🧪 Testing

# Backend tests
make test

# Frontend tests
cd frontend && pnpm test

# E2E tests (real backend integration)
./scripts/run-e2e-tests.sh

Coverage: >80% across all services
E2E Tests: 42 tests, 100% real HTTP calls

→ Testing Guide

---

🤝 Contributing

We welcome contributions! See Contributing Guidelines for details.

Quick Steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Submit a pull request

→ Development Setup

---

📜 License

CC Non-Commercial - Developed by fulgidus for the amateur radio community.

See LICENSE for full details.

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: alessio.corsi@gmail.com

---

🌟 Mission

Heimdall's mission is to democratize radio source localization, making it accessible to everyone while advancing radio science and emergency communications.

We believe that radio waves belong to everyone, and everyone should have the tools to understand and explore them.

---

Ready to see the invisible? → Start Your Journey