githubtron/venueflow

1. This is a TypeScript/Python monorepo for a real-time venue operations platform.

The repository is split into frontend apps, many small backend services, shared type definitions, and local infrastructure. Most backend services are independently deployable and each owns a narrow domain: auth, entry, notifications, wayfinding, analytics, emergency, staff, vendors, rewards, compliance, incidents, and ML/simulation.

2. The core event-data pipeline starts at the edge and fans out through Kafka.

The main operational flow is: IoT sensors send telemetry over MQTT into services/iot-gateway, which validates/normalizes payloads and publishes to Kafka. From there, downstream consumers like heatmap-engine, entry-router, rewards-service, and other event-driven services react to the same stream.

3. Heat and crowd intelligence is a dedicated real-time subsystem.

services/heatmap-engine is a Python FastAPI service with a Kafka consumer, an in-memory/Redis-backed store, aggregation/classification logic, and HTTP routes for reading computed heatmap state. The README’s architecture shows its output feeds Redis and then a WebSocket gateway, which is how live crowd state reaches clients.

4. Entry management is a separate transactional boundary.

services/entry-router handles ticket validation/scoring and writes entry events to PostgreSQL. It also has a Redis client and a red-zone subscriber, so it combines stateful checks with near-real-time gating decisions rather than relying only on the central telemetry stream.

5. Authentication and authorization are isolated in their own service.

services/auth-service owns login, JWT/keys, and RBAC middleware with a PostgreSQL migration. Frontends use auth-specific hooks/providers and guard components, so access control is enforced both in UI and at the API boundary.

6. Attendee and staff experiences are split into two client applications.

apps/mobile is a React Native app scaffold with screens for ticketing, navigation, kiosks, rewards, incident reporting, evacuation, and SOS. apps/dashboard is a React/Vite ops console with live maps, staff management, vendor views, compliance, emergency, and analytics pages. Both apps include WebSocket hooks for live updates.

7. Notifications are delivered through multiple channels behind one service.

services/notification-service centralizes delivery logic for WebSocket push, BLE mesh, staff radio, and segmented channels. That makes it the broadcast layer for alerts such as anomalies, emergencies, and targeted operational messages rather than embedding delivery logic in each domain service.

8. Operational domains are modeled as small services with their own storage.

There are dedicated services for staff management, vendor intelligence, kiosk orders, rewards, compliance, incidents, emergency coordination, and wayfinding. Most of these use PostgreSQL migrations and expose a narrow HTTP API; a few also consume Kafka or publish events. This keeps each business area independently evolvable.

9. Analytics and ML are isolated from the live control plane.

services/analytics-service, queue-predictor, sponsor-analytics, ml-pipeline, and simulation-service are separate Python FastAPI services for reporting, prediction, training, and synthetic event generation. services/threat-detection and services/external-integration extend the platform with risk detection and external feeds like traffic/weather. These services inform the product but are not in the critical ingress/egress path.

10. Shared contracts and infra are first-class parts of the architecture.

packages/shared-types holds cross-service TypeScript types, reducing drift across frontend and backend boundaries. infra/docker-compose.yml provides local Kafka/Postgres/Redis-style infrastructure, while infra/cdk contains planned cloud deployment stacks. The repo is therefore structured for local composition now, with a clear migration path to AWS-style managed infrastructure.

11. State is intentionally decentralized by domain.

PostgreSQL is used for transactional service-owned data, Redis for low-latency live state, Kafka for event distribution, and WebSockets for client push. The architecture avoids a single central application server; instead, it connects specialized services through well-defined data flows and shared event contracts.

12. Testing mirrors the service boundaries.

Most services include unit/property tests near the logic they own, and the Python services add Hypothesis-based property tests. That’s a signal that correctness is expected to be enforced per subsystem rather than through a single end-to-end test layer.