An advanced, real-time, event-driven smart office monitoring system designed for the IoT hackathon. This monorepo orchestrates simulated IoT hardware, real-time data streaming over WebSockets, deterministic alert logic, a Discord bot assistant, and Gemini-powered generative office summaries.
- Interactive Web Dashboard: https://frontend-production-27e2.up.railway.app
- Backend API Swagger Docs: https://backend-production-d529.up.railway.app/docs
- Backend Health Status: https://backend-production-d529.up.railway.app/api/v1/health
- Tinkercad IoT Hardware Simulator: Tinkercad Circuit Design Link
The following diagram illustrates how the system's independent microservices securely interact via private overlay networks and stream real-time updates to client browsers:
| Requirement | Implementation & Tech Stack | Location in Repo |
|---|---|---|
| 1. Multi-Device IoT Simulation | Simulates 15 physical devices (fans & lights) across 3 distinct rooms (Drawing Room, Workspace 1, Workspace 2). Automatically toggles random devices every 5–10s to model realistic sensor telemetry. | backend/app/simulator/engine.py |
| 2. Interactive UI Floor Plan | Implements a responsive React floor plan with Tailwind and Lucide icons. Enables users to visually inspect device states and click individual cards to manually toggle device power status. | frontend/src/App.tsx |
| 3. Real-Time Data Sync | Broadcaster establishes a persistent WebSocket connection. Streams immediate telemetry updates (device_update, power_update, alert_created, simulator_update) to keep all browser clients in sync. |
backend/app/api/websocket.py |
| 4. Power Usage Integration | Background service integrates total active power consumption in Watts every 60 seconds to compute daily energy metrics in Kilowatt-Hours (kWh). | backend/app/simulator/engine.py |
| 5. Intelligent Alert Engine | Deterministic rule checker runs alerts rules. Includes Rule 1 (Overconsumption) when power exceeds 200W, and Rule 2 (Extended Runtime) when a room runs devices continuously for >10s. Automatically resolves alerts when normal thresholds return. | backend/app/simulator/alert_engine.py |
| 6. Discord Bot Assistant | Integrates an interactive Discord Bot that connects directly to the backend API to query status, display room configurations, check daily power metrics, and ask natural language AI questions. | discord-bot/bot.py |
| 7. Google Gemini AI Integration | Integrates gemini-3.1-flash-lite via Google AI Studio to answer contextual office state queries (e.g. "What needs attention?"). Employs a robust deterministic template fallback if the API key is missing or fails. |
backend/app/services/ai_service.py |
| 8. Multi-Container Orchestration | Standardized Docker Compose orchestrating Postgres, FastAPI, React/Nginx, and the Discord Bot with cross-service environment configuration and dynamic port mapping templates. | docker-compose.yml |
| 9. Automated CI/CD Pipelines | Configured GitHub Actions workflow that executes Ruff checks, format enforcement, and Python pytest unit test cases on every push or pull request. | .github/workflows/ci-cd.yml |
- Docker & Docker Compose installed on your system.
- A Discord Bot Token (optional for running the Bot).
- A Gemini API Key from Google AI Studio (optional for AI summaries).
Copy the environment template and insert your credentials:
cp .env.example .envOpen .env and fill in your keys:
DATABASE_URL=sqlite:///./smart_office.db
GEMINI_API_KEY=your_google_ai_studio_key
DISCORD_TOKEN=your_discord_bot_application_tokenRun Docker Compose to build and launch all containers (Database, API, Dashboard, and Bot):
docker compose up --build- Web Dashboard: http://localhost:5173 (Static frontend hosted on Nginx)
- Backend OpenAPI Swagger UI: http://localhost:8000/docs
- API Health Status: http://localhost:8000/api/v1/health
To allow judges to easily verify synchronization between different components, we implemented a real-time IoT Simulation Control switch.
In a live smart office, the simulator automatically toggles random devices every 5–10 seconds. When presenting or grading the hackathon project, this automatic toggle makes it difficult to copy data and verify that the Discord Bot's !status embeds match the Web Dashboard's active status exactly. By pausing the simulation, you can freeze the office environment to compare states or run manual device tests without automatic interference.
- Interactive Control Switch: Located in the premium header of the React Dashboard as a toggle pill (
Sim Active/Sim Paused). - REST API Endpoint: Clicking the toggle sends a request to
POST /api/v1/devices/simulator/toggleon the FastAPI backend. - In-Memory Concurrency Management: The backend updates the unified
settings.SIMULATOR_ENABLEDsingleton reference, which instantly pauses or resumes the background execution task loop. - WebSocket Synchronization: The backend publishes a
simulator_updateevent to all open WebSocket connections. All browser instances update their toggle pill state instantly, ensuring real-time multi-client synchronization.
Add the bot to your Discord server and control your smart office using the following commands:
!status— Returns a rich embed summarizing active devices, total power draw, and active alerts.!room <drawing|work1|work2>— Returns the specific device statuses, types, and power draw for a given room.!usage— Displays daily aggregated power consumption in kWh.!ask <question>— Asks the Gemini AI assistant a natural language question about the current office conditions.!ping— Diagnostic bot heartbeat.!help— Lists all available commands.
We use Pytest for backend testing and Ruff for linting/formatting checks.
To run the tests and linter locally:
# Backend tests
cd backend
.venv\Scripts\pytest
# Discord bot tests
cd ../discord-bot
pytestThese validations are executed automatically in GitHub Actions on every pull request and push to the main or dev branches.