QueueFlow is an AI-assisted queue monitoring and management system for hospitals, banks, supermarkets, and other service locations. It combines live camera analysis, queue statistics, forecasting, smart alerts, operational reports, and role-based administration in one dashboard.
- Detect people from browser-camera frames with YOLOv8 and a queue region of interest.
- Keep camera analysis running while staff navigate between dashboard pages.
- Register saved cameras, reconnect them to existing queues, and upload private video sources.
- Calculate person count, density, waiting time, and queue status automatically.
- Estimate visual capacity from the camera while retaining administrator-controlled manual capacity.
- Track historical measurements and forecast the next count, density, wait, and status.
- Select a queue to highlight its forecast and focus every analytics graph.
- Generate transition-based smart alerts without repeated alert spam.
- Provide Camera Health, CSV/print Reports, REST APIs, and authenticated WebSocket updates.
- Enforce administrator, operator, and viewer permissions with JWT authentication.
QueueFlow is organized by responsibility:
Camera/video → AI pipeline → Backend API → PostgreSQL → Dashboard
└──────→ WebSocket → Dashboard
The AI layer publishes measurements, while the backend owns queue state, threshold-based status calculation, persistence, alerts, forecasting, and external APIs. See the architecture notes for details.
Start with the QueueFlow complete code guide. It follows execution from Docker and application startup through the AI pipeline, backend/database/API, React dashboard, real-time camera/WebSocket behavior, and every automated test. The guide also includes an inventory explaining the purpose and dashboard connection of every first-party code file.
| Area | Technology |
|---|---|
| Dashboard | React, TypeScript, Vite, Tailwind CSS, charts |
| API | Python, FastAPI, Pydantic, SQLAlchemy |
| Data | PostgreSQL |
| Vision | YOLOv8, OpenCV, replaceable detection/tracking adapters |
| Forecasting | scikit-learn Random Forest with a safe short-history fallback |
| Live updates | Authenticated WebSockets with HTTP polling fallback |
| Deployment | Docker Compose, Nginx, Uvicorn |
Backend dependencies are listed in backend/requirements.txt; dashboard dependencies and commands are in frontend/package.json.
frontend/ React dashboard, camera session, pages, and tests
backend/ FastAPI API, database models, services, and tests
ai/ Detection, tracking, and queue analytics modules
database/ Database documentation and schema assets
infrastructure/ Docker, Nginx, deployment, backup, and operations assets
docs/ Architecture, API, and development documentation
cp .env.example .env
docker compose up --build -d
docker compose psOpen http://localhost:8080. Configure the bootstrap administrator values described in .env.example, then follow the deployment and operational checks in infrastructure/README.md. Never commit the real .env file.
For backend development, use Python 3.11+ and follow the migration, seed, run, and test instructions in backend/README.md.
For the dashboard, use Node.js 20+, configure frontend/.env when required, then run npm install and npm run dev inside frontend/. Full instructions are in frontend/README.md.
cd backend && pytest
cd ../frontend && npm run lint && npm run test -- --run && npm run buildLatest verified result: 52 backend/AI tests and 9 frontend tests passed; frontend lint, production build, health, readiness, and the Docker Compose services were verified.
- Work in one module at a time and keep module interfaces explicit.
- Add focused tests with each subsystem.
- Run the relevant checks before requesting review.
- Do not commit credentials, generated model weights, or local database data.
The current work plan is in docs/development/roadmap.md. Production setup and operational checks are documented in infrastructure/README.md.
Milestones 1–13 are complete and release verified. Milestone 14 — Post-Release Operations & Maintenance is active and contains the camera persistence, video upload, automatic/manual capacity, forecasting selection, smart alerts, Camera Health, Reports, restart policies, and complete code-guide improvements described above.
Known non-blocking limitations are documented in AGENTS.md: automatic camera capacity is an approximation based on visible-person scale, performance baselines are not production capacity guarantees, and the React Router v7 migration remains a separate breaking upgrade.