Amazon Bounce Detection Dashboard

Bounce detection dashboard for Amazon buildings that tracks rapid sensor state transitions (occupied/available) to surface hardware issues or environmental interference. Building and floor hierarchies are discovered dynamically via the Density API key. The system uses WebSocket connections for real-time monitoring and SQLite for data persistence.

Tech Stack

Backend

• Python
• FastAPI 0.115.6
• uvicorn 0.34.0
• WebSockets 14.1
• aiosqlite 0.20.0
• httpx 0.28.1
• python-dotenv

Frontend

• React 18
• Material-UI (MUI)
• Recharts
• Victory

Database

• SQLite (bounce.db)

Density API Endpoints

Endpoint	Method	Purpose
/v3/spaces	GET	Building, floor, and space hierarchy discovery
/v3/analytics/sessions/raw	POST	Historical session data for backfill
/v3/analytics/occupancy/current	POST	Current occupancy state
/v3/analytics/ws/floor/{floor_id}/presence	WebSocket	Real-time presence data per floor

The WebSocket connection to /v3/analytics/ws/floor/{floor_id}/presence provides live presence updates for each floor. The backend maintains persistent WebSocket connections and streams state transitions to the frontend, enabling real-time bounce detection without polling.

Setup

Environment Variables

Create a .env file in the project root with the following variables:

Variable	Description
DENSITY_API_KEY	API key for Density platform access
DASHBOARD_PASSWORD	Password for dashboard authentication
SECRET_KEY	Secret key for session/token signing

Automated Setup

chmod +x start.sh
./start.sh

Manual Setup

# Backend
pip install -r backend/requirements.txt
python -m backend.main

# Frontend (in a separate terminal)
cd frontend
npm install
npm run dev

Once running, open http://localhost:8000.

Testing

pip install pytest pytest-asyncio
pytest backend/test_bounce_tracker.py -v