Hellstacks Heaven

A real-time situational intelligence platform for Fort Smith, Arkansas, combining live police scanner audio transcription, traffic alerts, and weather data visualization.

Features

• Live Audio Transcription: Real-time processing of Broadcastify police scanner feeds
• Interactive Map: Mapbox-powered visualization of incidents and alerts
• Traffic Intelligence: Live Waze traffic alerts and road conditions
• Weather Integration: Real-time weather radar and severe weather alerts
• WebSocket Communication: Real-time data streaming to connected clients

Architecture

• Frontend: Next.js with React, TypeScript, and Tailwind CSS
• Backend Gateway: Fastify server with WebSocket support
• Data Processing: Python transcription service with spaCy NLP
• Data Sources: Waze API, OpenWeatherMap API, Broadcastify streams
• Message Queue: Redis for inter-service communication
• Deployment: Docker Compose orchestration

Quick Start

Prerequisites

• Docker and Docker Compose
• Mapbox account and public token (required)
• AssemblyAI API key (optional, for real transcription)
• OpenWeatherMap API key (optional, for weather data)

Installation

1. Clone the repository: ```bash git clone cd hellstacks-heaven ```

2. Configure environment variables: ```bash cp .env.example .env

Edit .env with your API keys

```

3. Important: Set up your Mapbox token in Vercel Project Settings:

   • Go to your Vercel project dashboard
   • Navigate to Settings → Environment Variables
   • Add NEXT_PUBLIC_MAPBOX_TOKEN with your Mapbox public token
   • This token will be visible in client-side code (this is expected and secure when properly configured)

4. Deploy the application: ```bash chmod +x scripts/*.sh ./scripts/deploy.sh ```

5. Access the application:

• Frontend: http://localhost:3002
• API: http://localhost:3000
• WebSocket: ws://localhost:3001

Development Mode

For development, start only Redis and run services individually:

```bash ./scripts/dev.sh

In separate terminals:

cd server && npm run dev cd services/transcription && python transcription_service.py cd services/waze && npm run dev cd services/weather && npm run dev npm run dev ```

API Endpoints

• GET /api/health - Service health check
• POST /api/test-event - Send test event for debugging

Environment Variables

Variable	Required	Location	Description
NEXT_PUBLIC_MAPBOX_TOKEN	Yes	Client & Server	Mapbox public token (client-side usage is expected)
ASSEMBLYAI_API_KEY	No	Server only	AssemblyAI key for real-time transcription
OPENWEATHER_API_KEY	No	Server only	OpenWeatherMap key for weather data

Security Note

The NEXT_PUBLIC_MAPBOX_TOKEN is intentionally exposed to the client-side code. This is the correct implementation for Mapbox GL JS. To secure it:

1. Restrict the token to your domain in the Mapbox dashboard
2. Limit API scopes to only what you need
3. See SECURITY.md for detailed security guidelines

Scripts

• ./scripts/deploy.sh - Full production deployment
• ./scripts/dev.sh - Development environment setup
• ./scripts/test.sh - Run system tests
• ./scripts/logs.sh [service] - View service logs
• ./scripts/cleanup.sh - Clean up containers and volumes

Services

Frontend (Next.js)

• Port: 3002
• Real-time map visualization
• Live event feed
• Audio player integration

Gateway (Fastify)

• Port: 3000 (HTTP), 3001 (WebSocket)
• WebSocket message broadcasting
• Redis subscription management
• API endpoints

Transcription Service (Python)

• Real-time audio processing
• NLP-based incident extraction
• Geocoding integration

Waze Service (Node.js)

• Traffic alert fetching
• Road condition monitoring

Weather Service (Node.js)

• Weather data collection
• Severe weather alerting
• Radar imagery integration

Security

Please review SECURITY.md for important security considerations, especially regarding API key management and Mapbox token configuration.

License

MIT License - see LICENSE file for details.