Services¶

Overview¶

┌──────────────────────────────────────────────────────────┐
│                      NGINX Proxy                          │
│  / → Frontend  │  /api → Orders  │  /ws → Notifications  │
└──────────────────────────────────────────────────────────┘
         │                │                    │
    ┌────▼────┐    ┌──────▼──────┐    ┌───────▼────────┐
    │Frontend │    │Order Service│    │Notifications   │
    │ (React) │    │  (FastAPI)  │    │   (FastAPI)    │
    └─────────┘    └──────┬──────┘    └───────┬────────┘
                          │                    │
                   ┌──────▼──────┐    ┌───────▼────────┐
                   │  Delivery   │    │   Simulator    │
                   │  (FastAPI)  │    │   (Python)     │
                   └─────────────┘    └────────────────┘

Service	Port	Role
`order-service`	8003	Order management, menu, stock control
`delivery-service`	8001	Delivery record creation and tracking
`notifications-service`	8002	WebSocket gateway for real-time updates
`order-simulator`	–	Drives order lifecycle transitions
`frontend`	3000	React UI for browsing, ordering, tracking

Order Service¶

The entry point for all business logic. Handles order creation with stock validation inside MongoDB transactions, and publishes domain events to Redis Streams.

Endpoints

GET /api/v1/menu – list menu items with stock levels

POST /api/v1/orders – create an order (validates stock, decrements atomically)

GET /api/v1/orders/{id} – get order details and current status

GET /api/v1/health – readiness check

GET /metrics – Prometheus metrics

Publishes to

orders-stream, simulate-order-stream

Consumes from

order-status-stream (status updates from simulator)

Key behavior

Order creation runs inside a MongoDB transaction. Stock is checked and decremented atomically – if two users order the last pizza simultaneously, one gets the order and the other gets a 400 error. The event is published only after the transaction commits.

Delivery Service¶

Reacts to orders reaching “out for delivery” status. Creates delivery records and tracks the delivery lifecycle.

Endpoints

GET /api/v1/health – readiness check

GET /metrics – Prometheus metrics

Publishes to

deliveries-stream, simulate-delivery-stream

Consumes from

orders-stream (new orders), delivery-status-stream (status updates from simulator)

Key behavior

Listens to orders-stream and only acts when an order reaches out_for_delivery status. Creates a delivery record in MongoDB and publishes a delivery.created event. Has no REST API for delivery management – everything is event-driven.

Notifications Service¶

The WebSocket gateway. Bridges the event bus to the browser, pushing real-time status updates to connected clients.

Endpoints

WS /ws/v1/order-tracking/{order_id} – WebSocket for live order tracking

GET /api/v1/health – readiness check

GET /metrics – Prometheus metrics

Consumes from

orders-stream, deliveries-stream

Key behavior

When a client connects via WebSocket, the service first checks Redis cache for the latest known status (instant response), then keeps the connection alive and pushes updates as they arrive from the event bus. Uses ping/pong frames with a 60-second timeout for keepalive. No database dependency – purely stateless, backed by Redis.

Order Simulator¶

Drives the demo. Simulates realistic order lifecycle transitions with configurable delays, making the system useful without manual interaction.

Consumes from

simulate-order-stream, simulate-delivery-stream

Publishes to

order-status-stream, delivery-status-stream

Status transitions

Order:    created → confirmed → preparing → out_for_delivery
Delivery: waiting → on_the_way → delivered

Each transition has a randomized delay (configurable via environment variables) to simulate real-world processing times.

Frontend¶

React 19 + TypeScript single-page application with:

Menu browsing with stock indicators
Shopping cart with real-time validation
Order placement with instant feedback
Live order tracking via WebSocket connection
Dev tools page with links to Grafana dashboards and API docs

Built with Vite, styled with Tailwind CSS + shadcn/ui, data fetching via TanStack Query, routing via TanStack Router.

Supporting Infrastructure¶

Service	Role	Details
MongoDB	Document store	Replica set (`rs0`) for transaction support, keyfile auth
Redis	Event bus + cache	Streams with consumer groups, status caching with 24h TTL
NGINX	Reverse proxy	Routes traffic, WebSocket upgrade, Prometheus GET-only restriction
Prometheus	Metrics	Scrapes `/metrics` from all services every 15s
Grafana	Dashboards	3 pre-provisioned dashboards, anonymous viewer access
Loki	Log aggregation	Receives logs from Promtail, 72h retention
Promtail	Log collector	Docker service discovery, filters to app containers only