Building StadiumOS: A Real-Time Multi-Agent AI System for Crowd Management
Have you ever wondered how megastructures like sports stadiums handle tens of thousands of people moving around simultaneously? Between food court rushes, security bottlenecks, and exit gate stampedes, stadium operations are incredibly complex to manage.
I set out to tackle this problem by building StadiumOS — a multi-agent coordination engine capable of simulating and optimizing stadium operations in real time.
The Architecture: A Brain for the Stadium
This wasn’t just a simple web app. I wanted to build a true system-level intelligence platform. Here is the stack that powered it:
Backend: Node.js and Express (Simulation Engine and REST API)
Database: In-memory caching with optional Firebase Firestore mirroring
Frontend: Next.js 16 with Tailwind CSS and Leaflet.js
Brain: A custom Multi-Agent Architecture
How the Multi-Agent System Works
Instead of one monolithic AI trying to figure everything out, I decentralized the logic. StadiumOS runs a live simulation (ticking every 2 seconds) passing data to four independent AI Agents, each handling a specific domain:
- Crowd Agent: Monitors zone densities to prevent overcrowding.
Write on Medium
Vendor Agent: Analyzes food court queues against stall service rates to predict wait times.
Security Agent: Keeps a rolling history of crowd spikes to detect anomalies and flag zones.
Transport Agent: Calculates net flow rates at gates to estimate clearance times during egress.
These four agents don’t make final decisions. Instead, they produce structured reports and pass them up to the Coordinator Engine.
The Decision Coordinator
The Coordinator acts as the central brain. It ingests the agent reports, runs them through priority-based rules, and outputs actionable recommendations.
For example: if the Crowd Agent reports the South Stand is highly dense, and the Security Agent flags an unusual spike, the Coordinator immediately generates a Critical Priority Decision: “RESTRICT_ZONE — Halt ingress to South Stand temporarily.”
The Dashboard
To bring this all to life, I built a dark-mode Next.js dashboard. It features an interactive Leaflet map that dynamically changes marker sizes and colors based on zone loads. A polling hook fetches the latest agent reports and coordinator decisions every 2 seconds, displaying a real-time, priority-sorted feed of actions.
Deployment and Takeaways
To cap it off, I containerized the entire monorepo using a multi-stage Docker build, allowing the Express backend to serve the Next.js static build from a single container, and deployed it serverlessly to Google Cloud Run.
Building a multi-agent architecture from scratch was an incredible challenge. It taught me how to decouple complex state, manage real-time tick-based simulations, and build prioritizing rule engines.
Check out the code on my GitHub!
GitHub Repo : https://github.com/arpitpandey0307/Stadium-OS.git
Link to Live Deployment : https://stadium-os-795750315067.us-central1.run.app/
