Hackomania-2026 🚑

Emergency Response System - Real-time monitoring dashboard + Personal alert button with AI-powered triage

---

👥 Team - HackIT Team 24h

Built during Hackomania 2026 - 24-hour hackathon | March 2026

Name	Email	Role
Chuong	chuongpqvn@gmail.com	Frontend Development, UI/UX Design
Tuan Le	leducanhtuan3006@gmail.com	Full-stack Development, API Integration
Samuel	SamLee347@hotmail.com	Backend Architecture, Database Design
Yan	chooyanprogramming@gmail.com	Designer, Product Owner, Critical thinking

---

🔗 Quick Links

Resource	Link
🎨 Dashboard Demo	https://hackomania-2026.vercel.app/
📱 Mobile App Demo	https://hackomania-2026.vercel.app/user.html
📊 Presentation	Google Slides
🏗️ Architecture	Lucidchart Diagram
🚀 Deployment Guide	DEPLOY_QUICK.md
📖 API Docs	Swagger UI

---

📑 Table of Contents

• What is This?
• Screenshots
• Project Overview
• Key Features
• Quick Start - Deployment
• Local Development
• Project Structure
• Technology Stack
• Deployment
• Development Tips
• Mobile Installation
• Troubleshooting
• Feature Checklist
• System Capabilities
• Future Enhancements
• License
• Acknowledgments

---

🎯 What is This?

A complete emergency response system built in 24 hours combining:

1. Real-time Emergency Dashboard - Monitor and respond to emergency alerts instantly
2. Personal Alert Button App - One-tap SOS with voice recording
3. AI-Powered Triage - Intelligent emergency assessment and prioritization

Perfect for: Elderly care facilities, medical response teams, personal safety devices, smart home integration

Key Highlights:

• ⚡ Real-time updates every 5 seconds
• 🗺️ Live location tracking on interactive maps
• 🎤 Voice-to-text transcription of emergency calls
• 📱 Mobile-first PWA (works offline, installable)
• 🤖 AI reasoning for emergency prioritization
• 👥 Integrated emergency contact management

---

📸 Screenshots

Emergency Response Dashboard

Real-time monitoring with live alerts, interactive map, and AI triage reasoning

System Architecture

Complete system design showing data flow and integrations

Note: Screenshots show the actual production deployment running on Vercel + Google Cloud

---

📋 Project Overview

This project consists of a comprehensive emergency response system with:

🎯 PAB Dashboard (Emergency Response Command Center)

Real-time monitoring dashboard for emergency medical services featuring:

• Live Alerts Panel: Real-time emergency alerts with auto-refresh (5-second polling)
• Interactive Map: Location tracking with risk-based markers
• AI Triage Reasoning: AI-powered emergency assessment and prioritization
• Audio Transcripts: Real-time transcription of emergency calls
• Statistical Overview: Active alerts, risk levels, and system status
• Emergency Contacts: Integrated contact management with patient information
• Action Controls: One-click alert resolution and dispatch management

📱 User Audio App (Personal Alert Button - PAB)

Voice-enabled emergency alert interface for end-users:

• Emergency Voice Recording: One-tap SOS with automatic voice message recording
• Hotline Support: Long-press (5 seconds) to connect to emergency hotline
• Fullscreen Mode: Distraction-free interface optimized for emergencies
• Mobile-First Design: PWA support with iOS/Android standalone mode
• Real-time Status: Visual feedback for recording, processing, and success states
• Offline Capability: Fallback silent alert when microphone unavailable

🔧 Backend API (FastAPI)

Python-based REST API for data management:

• Real-time voice info storage and retrieval
• Emergency alert processing
• Contact management
• Device tracking and management
• Audio file handling with transcription integration

Tech Stack: FastAPI, Python 3.10+, PostgreSQL/ClickHouse, Azure Speech Services

✨ Key Features

Real-Time Data Integration

• Auto-Refresh: Dashboard polls API every 5 seconds for live updates
• API Endpoint: https://hackit-api-111308238154.asia-southeast1.run.app/db/voice_infos
• Null-Safe Processing: Defensive data transformation with optional chaining
• State Management: React hooks for efficient real-time updates

Emergency Alert Actions

• Resolve Endpoint: POST /db/voice_info/resolve?device_id={id}
• Loading States: Visual feedback during API operations
• Error Handling: Graceful fallbacks and retry mechanisms

Personal Contacts Integration

• Dynamic Contact Fetching: Loads family/emergency contacts per device
• Contact API: Nested contacts array within voice info response
• Relationship Mapping: Father, Sister, and custom relationships

Mobile Optimizations

• PWA Support: Installable as standalone app on iOS/Android
• Fullscreen API: Cross-browser fullscreen with vendor prefixes
• Safe Area Support: Respects notches and status bars (env(safe-area-inset-*))
• Touch-Optimized: Long-press detection, haptic-like feedback
• Viewport Heights: Uses -webkit-fill-available for iOS compatibility

🚀 Quick Start - Deployment

Deploy both frontends to a single domain:

# Quick deploy to Vercel
vercel --prod

Access URLs after deployment:

• Main Dashboard: https://yourdomain.com
• User Audio: https://yourdomain.com/user.html

📖 Detailed deployment guide: See DEPLOY_QUICK.md or DEPLOYMENT.md

🛠️ Local Development

Prerequisites

• Node.js 16+ (for frontends)
• Python 3.10+ (for backend)
• npm or yarn (package manager)

Frontend - PAB Dashboard

cd front-end/pab-dashboard
npm install
npm run dev
# Runs on http://localhost:5173

Features:

• Vite dev server with HMR
• Real-time API integration
• Responsive layout testing

Frontend - User Audio

cd front-end/user-audio
npm install
npm start
# Runs on http://localhost:3000

Environment Variables (optional):

• REACT_APP_API_URL: Backend API endpoint (default: production API)
• REACT_APP_DEVICE_ID: Device identifier (default: PAB-00083912)

Features:

• Create React App with hot reload
• Microphone permission testing
• PWA manifest for mobile testing

Backend

cd backend
python3 -m venv venv
source venv/bin/activate  # or: venv\Scripts\activate on Windows
pip install -r requirements.txt
uvicorn app.main:app --reload
# Runs on http://127.0.0.1:8000

Environment Variables (.env):

APP_NAME=Hackomania API
APP_VERSION=0.1.0
DEBUG=true
DATABASE_URL=your_database_url
AZURE_SPEECH_KEY=your_azure_key
AZURE_SPEECH_REGION=your_region

API Documentation:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

📁 Project Structure

hackomania-2026/
├── backend/                    # FastAPI backend
│   ├── app/
│   │   ├── main.py            # API routes and endpoints
│   │   ├── config.py          # Environment configuration
│   │   ├── schemas.py         # Pydantic models
│   │   ├── db.py              # Database connections
│   │   ├── speech_transcriber.py  # Azure Speech integration
│   │   └── voice_info_repository.py  # Data access layer
│   ├── requirements.txt       # Python dependencies
│   └── README.md              # Backend documentation
│
├── front-end/
│   ├── pab-dashboard/         # Emergency Response Dashboard
│   │   ├── src/
│   │   │   ├── pages/
│   │   │   │   └── Dashboard.jsx      # Main dashboard logic
│   │   │   └── components/
│   │   │       ├── AlertsPanel.jsx    # Live alerts list
│   │   │       ├── MapPanel.jsx       # Interactive map
│   │   │       ├── SummaryPanel.jsx   # Audio transcript + AI reasoning
│   │   │       ├── ContactList.jsx    # Emergency contacts
│   │   │       └── StatCards.jsx      # Statistics overview
│   │   ├── vite.config.js     # Vite configuration with proxy
│   │   └── package.json
│   │
│   └── user-audio/            # Personal Alert Button App
│       ├── src/
│       │   ├── App.js         # Main app with recording logic
│       │   ├── App.css        # Responsive styles + PWA
│       │   └── WaveAnimation.js  # Recording visual feedback
│       ├── public/
│       │   ├── index.html     # PWA meta tags
│       │   └── manifest.json  # PWA manifest
│       └── package.json
│
├── dist-combined/             # Production build output
│   ├── index.html             # PAB Dashboard
│   ├── user.html              # User Audio App
│   └── assets/                # Bundled JS/CSS
│
├── docs/                      # Documentation and diagrams
├── deploy.sh                  # Combined build script
├── vercel.json                # Vercel deployment config
├── DEPLOY_QUICK.md            # Quick deployment guide
├── DEPLOYMENT.md              # Detailed deployment guide
└── README.md                  # This file

🔧 Technology Stack

Frontend

• React 18.x - UI framework
• Vite - Build tool and dev server (Dashboard)
• Create React App - Build tool (User Audio)
• Axios - HTTP client for API requests
• React Leaflet - Interactive maps with OpenStreetMap
• CSS3 - Custom styling with glassmorphism effects

Backend

• FastAPI - Modern Python web framework
• Python 3.10+
• Uvicorn - ASGI server
• Azure Speech Services - Audio transcription
• PostgreSQL/ClickHouse - Database (configurable)

Deployment

• Vercel - Frontend hosting with serverless functions
• Google Cloud Run - Backend API hosting
• GitHub - Version control and CI/CD

APIs & External Services

• hackit-api-111308238154.asia-southeast1.run.app - Main API backend
• OpenStreetMap / Leaflet - Mapping services
• Azure Cognitive Services - Speech-to-text transcription

🌐 Deployment

The project uses a unified deployment strategy where both frontends are combined:

Production Deployment (Vercel)

# Build both apps into dist-combined/
./deploy.sh

# Deploy to Vercel
vercel --prod

Deployment Structure:

• Root (/) → PAB Dashboard serves at the root
• User Audio (/user.html) → Personal Alert Button app
• Assets (/assets/*) → Shared CSS/JS bundles

Build Process

The deploy.sh script:

1. Builds PAB Dashboard with Vite (npm run build)
2. Builds User Audio with CRA (npm run build)
3. Combines outputs into dist-combined/
4. Renames User Audio's index.html → user.html

API Configuration

Both frontends connect to the production API:

https://hackit-api-111308238154.asia-southeast1.run.app

Key Endpoints:

• GET /db/voice_infos - Fetch all alerts
• POST /db/voice_info/resolve?device_id={id} - Resolve alert
• POST /detect - Upload audio recording

Environment Setup

No environment variables needed for production deployment - API URLs are hardcoded to production endpoints.

For custom deployments, update API endpoints in:

• front-end/pab-dashboard/src/pages/Dashboard.jsx
• front-end/pab-dashboard/src/components/AlertsPanel.jsx
• front-end/user-audio/src/App.js

🧪 Development Tips

Dashboard Development

• Proxy Configured: Vite proxy routes /api/* to backend (for local dev)
• Hot Reload: Changes reflect immediately in browser
• Debug Logs: Check console for API responses
• State Inspector: Use React DevTools for component state

User Audio Development

• Microphone Testing: Requires HTTPS or localhost
• PWA Testing: Use npm run build and serve with HTTPS
• Mobile Testing: Use ngrok or deploy to test on real devices
• Fullscreen Mode: Works on desktop; on iOS use "Add to Home Screen"

Backend Development

• Auto-reload: uvicorn --reload flag watches for file changes
• API Docs: Always available at /docs and /redoc
• CORS: Already configured for frontend origins
• SQLite: Use for local testing instead of PostgreSQL

📱 Mobile Installation (PWA)

iOS (Safari)

1. Open https://hackomania-2026.vercel.app/user.html in Safari
2. Tap Share button → "Add to Home Screen"
3. App opens in fullscreen standalone mode
4. Status bar is translucent for immersive experience

Android (Chrome)

1. Open the user audio URL
2. Tap menu → "Install app" or "Add to Home Screen"
3. App runs in fullscreen with system UI auto-hide
4. Can also use fullscreen button within app

🐛 Troubleshooting

Frontend Issues

Dashboard not updating:

• Check browser console for API errors
• Verify API endpoint is accessible
• Check for CORS issues (should be configured)

Map not loading:

• Ensure internet connection for OpenStreetMap tiles
• Check Leaflet CSS is loaded correctly
• Verify coordinates are valid numbers

User Audio recording fails:

• Grant microphone permissions in browser
• Use HTTPS (required for getUserMedia)
• Check WebM codec support in browser

API Issues

CORS errors:

• Backend must include frontend origin in CORS settings
• Check preflight OPTIONS requests are handled

505 errors (audio upload):

• Verify audio file format (WebM)
• Check FormData is properly constructed
• Ensure device_id is included

🔐 Security Notes

• API endpoints are public (demo purposes)
• No authentication implemented
• Microphone permissions required for recording
• HTTPS required for production microphone access
• Safe area insets protect from notch overlap on mobile

✅ Feature Checklist

PAB Dashboard ✨

• Real-time alert monitoring (5-second auto-refresh)
• Live location tracking with interactive map
• AI-powered triage reasoning display
• Audio transcript viewer
• Emergency contacts integration (patient + family)
• Statistical overview cards
• One-click alert resolution
• Responsive layout (desktop, tablet, mobile)
• Risk-based color coding (High/Medium/Low)
• Time-ago formatting for alerts
• Loading states and error handling
• Null-safe data processing

User Audio App 📱

• One-tap SOS emergency recording
• Long-press (5s) hotline connection
• Fullscreen mode toggle
• PWA support (installable app)
• iOS standalone mode
• Android fullscreen support
• Visual recording feedback (wave animation)
• Recording status messages
• Microphone permission handling
• Fallback silent alert
• Safe area support (notches)
• Touch-optimized controls
• Custom progress indicator

Backend API 🔧

• Voice info CRUD operations
• Audio file upload handling
• Speech-to-text transcription
• Alert resolution endpoint
• Contact management
• Device tracking
• CORS configuration
• API documentation (Swagger/ReDoc)
• Error handling and validation

🎯 System Capabilities

Response Time: < 2 seconds for alert notification
Auto-Refresh: 5-second polling interval
Supported Audio: WebM, MP3, WAV formats
Mobile Support: iOS 12+, Android 8+
Browser Support: Chrome, Safari, Firefox, Edge (latest versions)
API Reliability: 99.9% uptime on Google Cloud Run
Concurrent Users: Scales automatically with Vercel/GCP

🚀 Future Enhancements

• WebSocket for real-time push updates
• User authentication and role-based access
• Historical data analytics and reporting
• Multi-language support
• SMS/Email notifications
• Geofencing for location-based alerts
• Offline mode with sync when online
• Video call integration for hotline
• Voice command activation
• Machine learning for predictive alerts

📝 License

See LICENSE for details.

This project wouldn't have been completed if not for Yan's awesome intensive contribution. She is so awesome! Awesome team as well.