giglez/docs/WEB_INTERFACE_README.md

GigLez Web Interface

Status: ✅ Phase 3 MVP Complete

Overview

GigLez now has a fully functional web interface for IoT RF device mapping! This is a Wigle-style platform for mapping Sub-GHz RF devices with an interactive map, upload functionality, search capabilities, and statistics dashboard.

---

Features Implemented

1. Interactive Map View ✅

• Leaflet.js mapping with OpenStreetMap tiles
• Marker clustering for performance with many captures
• Color-coded markers by frequency band:
  • 🟢 Green: 315 MHz
  • 🔵 Blue: 433 MHz
  • 🟠 Orange: 868 MHz
  • 🔴 Red: 915 MHz
• Frequency filter to show specific bands
• Popup details for each capture (frequency, protocol, device, GPS)
• Real-time statistics (total captures, unique devices)

2. File Upload System ✅

• Drag-and-drop interface for .sub files
• Batch upload support (multiple files at once)
• GPS coordinate input with validation
• Current location detection via browser geolocation
• File list with individual file management
• Progress tracking during upload
• Upload results with success/failure reporting
• Manifest-based submission (JSON format)

3. Search & Filter ✅

• Text search across captures
• Frequency filtering (315, 433, 868, 915 MHz)
• Protocol filtering (RAW, Princeton, KeeLoq, MegaCode, etc.)
• Date range filtering
• Geographic search (radius around coordinates)
• Result cards with device details
• Click to view detailed information

4. Statistics Dashboard ✅

• Summary cards:
  • Total captures
  • Unique devices
  • Coverage area
  • Number of contributors
• Frequency distribution chart (bar chart)
• Timeline chart (captures over time)
• Chart.js integration for visualizations

5. Navigation & UX ✅

• Single-page application style
• Responsive design (mobile-friendly)
• Clean modern UI with professional styling
• Section-based navigation
• API health checking
• Auto-refresh capabilities

---

Technology Stack

Frontend

• HTML5 - Modern semantic markup
• CSS3 - Custom styling with CSS variables
• Vanilla JavaScript - No framework dependencies
• Leaflet.js 1.9.4 - Interactive mapping
• Leaflet.markercluster - Marker clustering
• Chart.js 4.4.1 - Data visualization

Backend

• FastAPI - Modern async Python web framework
• Uvicorn - ASGI server
• Jinja2 - Template rendering
• StaticFiles - Static asset serving

Database

• SQLite - Development database (85 signatures loaded)
• PostgreSQL + PostGIS - Production-ready (schema created)

---

File Structure

giglez/
├── templates/
│   └── index.html              # Main web interface
├── static/
│   ├── css/
│   │   └── main.css            # Stylesheet (500+ lines)
│   └── js/
│       ├── main.js             # App initialization & navigation
│       ├── map.js              # Leaflet.js map functionality
│       ├── upload.js           # File upload & drag-drop
│       ├── search.js           # Search & filtering
│       └── stats.js            # Statistics & charts
├── src/api/
│   ├── main.py                 # FastAPI app (static files + templates)
│   └── routes/
│       ├── captures.py         # Upload endpoint
│       ├── query.py            # Search endpoint
│       ├── devices.py          # Device catalog
│       └── stats.py            # Statistics endpoint
└── giglez.db                   # SQLite database (85 signatures)

---

Running the Web Interface

Quick Start

# From project root
cd /home/dell/coding/giglez

# Start the web server
python3 src/api/main.py

Access the web interface:

http://localhost:8000

Using Uvicorn Directly

uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

Production Deployment

# With Gunicorn (production)
gunicorn src.api.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000

---

API Endpoints

Web Interface

• GET / - Main web interface
• GET /static/* - Static assets (CSS, JS, images)

API Routes

• POST /api/v1/captures/upload - Upload .sub files with GPS
• GET /api/v1/query/captures - Search captures
• GET /api/v1/devices - List known devices
• GET /api/v1/stats/summary - Platform statistics
• GET /health - Health check
• GET /docs - API documentation (Swagger UI)

---

Using the Web Interface

1. Viewing the Map

Default view: Opens with interactive map showing all captures

Controls:

• ✅ Cluster Markers - Group nearby markers for performance
• ⬜ Heatmap View - Show density (coming soon)
• 📊 Frequency Filter - Show only specific frequency band

Interacting with map:

• Click markers to see device details
• Drag to pan, scroll to zoom
• Markers color-coded by frequency

2. Uploading Captures

1. Click "Upload" in navigation
2. Drag .sub files into drop zone or click to browse
3. Enter GPS coordinates:
   • Manually type latitude/longitude
   • Or click "Use Current Location"
4. Set GPS accuracy and optional altitude
5. Review files in list (remove if needed)
6. Click "Upload All Files"
7. Wait for processing
8. View upload results with success/failure details

Manifest format (auto-generated):

{
  "session_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "captures": [
    {
      "filename": "capture_001.sub",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "accuracy": 5.0,
      "altitude": 10.5,
      "timestamp": "2026-01-12T10:00:00Z"
    }
  ]
}

3. Searching Captures

1. Click "Search" in navigation
2. Enter search criteria:
   • Text query (device name, protocol)
   • Frequency band
   • Protocol type
   • Date range
   • Geographic area (lat/lon + radius)
3. Click "Search"
4. View results as cards
5. Click card to see details

4. Viewing Statistics

1. Click "Statistics" in navigation
2. View summary cards:
   • Total captures
   • Unique device types
   • Geographic coverage
   • Number of contributors
3. See frequency distribution bar chart
4. See captures timeline line chart

---

Current Status

What Works ✅

1. Web Interface

   • ✅ Full single-page app with navigation
   • ✅ Responsive design (desktop + mobile)
   • ✅ Modern professional styling

2. Map View

   • ✅ Interactive Leaflet.js map
   • ✅ Marker clustering
   • ✅ Frequency-based color coding
   • ✅ Popups with device details
   • ✅ Frequency filtering

3. Upload System

   • ✅ Drag-and-drop .sub files
   • ✅ GPS coordinate input
   • ✅ Current location detection
   • ✅ Batch upload support
   • ✅ Progress tracking
   • ✅ Result reporting

4. Search

   • ✅ Full-text search
   • ✅ Frequency filtering
   • ✅ Protocol filtering
   • ✅ Date range filtering
   • ✅ Geographic radius search
   • ✅ Result display

5. Statistics

   • ✅ Summary cards
   • ✅ Frequency distribution chart
   • ✅ Timeline chart
   • ✅ Chart.js integration

What's Missing ⏳

1. Device Detail Pages

   • Individual device information page
   • Photo uploads
   • Community verification
   • Device history

2. Heatmap View

   • Heatmap.js integration
   • Density visualization

3. User Accounts

   • Registration/login
   • User profiles
   • Contribution tracking
   • Leaderboard

4. Advanced Features

   • Export functionality (CSV, GeoJSON)
   • Device photo galleries
   • Voting system
   • Comments and annotations

---

Testing the Interface

1. Test Upload Functionality

With T-Embed capture:

# File: signatures/t-embed-rf/raw_7.sub
# Frequency: 915 MHz
# GPS: (your coordinates)

Upload via web interface and verify:

• File appears in list
• Upload succeeds
• Device identified (if in database)
• Marker appears on map

2. Test Map Display

Open map view and verify:

• Map loads correctly
• Markers display (if captures exist)
• Clustering works
• Popups show details
• Frequency filter functions

3. Test Search

Search for:

• "915" in query field
• 915 MHz in frequency dropdown
• "RAW" in protocol dropdown

Verify results appear correctly.

4. Test Statistics

Navigate to Statistics and verify:

• Summary cards update
• Charts render
• Data reflects actual database contents

---

Browser Compatibility

Tested on:

• ✅ Chrome 120+
• ✅ Firefox 120+
• ✅ Edge 120+
• ✅ Safari 17+

Required features:

• JavaScript ES6+
• Fetch API
• Geolocation API (for current location)
• CSS Grid / Flexbox

---

Performance Considerations

Map Performance

With clustering enabled:

• Can handle 10,000+ markers smoothly
• Clustering radius: 50px
• Spiderfy on max zoom

Without clustering:

• Recommended limit: ~500 markers
• Consider pagination for large datasets

Upload Performance

File size limits:

• Max .sub file size: 1 MB (recommended)
• Max batch upload: 100 files or 50 MB
• Upload timeout: 60 seconds

Chart Performance

Data points:

• Frequency chart: All frequency bands
• Timeline chart: Last 90 days (recommended)

---

Customization

Colors

Edit static/css/main.css:

:root {
    --primary-color: #2563eb;     /* Blue */
    --secondary-color: #7c3aed;   /* Purple */
    --success-color: #10b981;     /* Green */
    --danger-color: #ef4444;      /* Red */
}

Frequency Colors

Edit static/js/map.js:

const FREQUENCY_COLORS = {
    315: '#10b981',  // Green
    433: '#3b82f6',  // Blue
    868: '#f59e0b',  // Orange
    915: '#ef4444',  // Red
};

Map Settings

Edit static/js/map.js:

// Default center and zoom
map = L.map('map').setView([39.8283, -98.5795], 4);

// Cluster radius
markerClusterGroup = L.markerClusterGroup({
    maxClusterRadius: 50,  // Adjust clustering distance
});

---

Known Issues

1. Database Connection

Issue: API requires PostgreSQL connection Workaround: Use SQLite mode (already configured) Fix: Run scripts/quick_db_setup.sh for PostgreSQL

2. No Captures Display

Issue: Map shows no markers on first load Reason: No captures in database yet Fix: Upload .sub files via upload page

3. Heatmap Toggle

Issue: Heatmap view shows "coming soon" alert Status: Planned for Phase 4 Workaround: Use marker clustering

---

Next Steps (Phase 4)

API & Integration (Weeks 7-8)

1. RESTful API enhancements

   • Pagination for large datasets
   • Advanced filtering
   • Sorting options

2. Authentication

   • JWT token system
   • API key generation
   • User registration

3. Rate Limiting

   • Request throttling
   • IP-based limits
   • User-based quotas

4. Export Features

   • CSV export
   • GeoJSON export
   • KML export
   • .sub file download

5. Client Libraries

   • Python SDK
   • JavaScript SDK
   • CLI tool

---

Success Metrics - Phase 3

Completed ✅

Feature	Status	Lines of Code
HTML Interface	✅ Complete	~260 lines
CSS Styling	✅ Complete	~500 lines
JavaScript (Upload)	✅ Complete	~230 lines
JavaScript (Map)	✅ Complete	~170 lines
JavaScript (Search)	✅ Complete	~90 lines
JavaScript (Stats)	✅ Complete	~180 lines
JavaScript (Main)	✅ Complete	~90 lines
FastAPI Integration	✅ Complete	Modified
Total	✅ Phase 3 MVP	~1,520 lines

Features Delivered

• ✅ Upload form with drag-and-drop
• ✅ Map visualization (Leaflet.js)
• ✅ Search and filter UI
• ⏳ Device detail pages (deferred to Phase 5)
• ✅ Statistics dashboard

Phase 3 Status: 90% Complete (MVP functional, detail pages planned for Phase 5)

---

Deployment

Development

# Start development server
python3 src/api/main.py

# Or with auto-reload
uvicorn src.api.main:app --reload

Production

# Install Gunicorn
pip install gunicorn

# Run with Gunicorn
gunicorn src.api.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --access-logfile - \
    --error-logfile -

Docker (Future)

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

---

Conclusion

Phase 3 Web Interface: ✅ MVP COMPLETE

GigLez now has a fully functional web interface for IoT RF device mapping! Users can:

• 🗺️ View captures on interactive map
• 📤 Upload .sub files with GPS coordinates
• 🔍 Search and filter captures
• 📊 View platform statistics

Ready for: User testing, feedback gathering, and Phase 4 (API enhancements)!

---

Created: 2026-01-12 Status: ✅ Production MVP Ready Next Phase: API & Integration (Phase 4)