A production-style event-driven microservices system built in Python to demonstrate:
- Microservices architecture
- Event-driven communication using Kafka
- Saga pattern for distributed transactions
- Failure handling and compensation
- Observability fundamentals
Most tutorials explain microservices in isolation. This project answers the question:
“What actually happens when things fail in a distributed system?”
Using a real-world food delivery scenario, it demonstrates:
- Order creation
- Payment processing
- Delivery assignment
- Failure recovery using Saga
Key principles:
- Each service owns its logic and database
- Services communicate via Kafka events
- The system is eventually consistent
- Client places an order
- Order Service creates the order with status
PENDING - Order Service publishes an event to Kafka
- Payment Service consumes the event and processes payment
- Delivery Service reacts to payment success and assigns delivery
- Order → Payment → Delivery
- Everything succeeds
- Payment fails
- Order is cancelled via compensation
- Delivery is skipped
- Python (FastAPI)
- Kafka (event streaming)
- PostgreSQL (per-service DB)
- Redis (idempotency - optional)
- Docker & Docker Compose
| Service | Responsibility |
|---|---|
| API Gateway | Entry point for clients |
| Order Service | Creates orders and starts the Saga |
| Payment Service | Processes payment events |
| Delivery Service | Assigns delivery after payment success |
- Clone the repository
git clone <your-repo-url>
cd Python-Microservice-POC- Start the system
docker-compose up --build- To rebuild and restart a single service after code changes
docker-compose up -d --no-deps --build <service-name>Example:
docker-compose up -d --no-deps --build order-service- Trigger the flow
curl -X POST http://localhost:8000/place-order- Order created by the Order Service
- Payment randomly succeeds or fails
- Delivery assigned on payment success
- Order cancelled when payment fails
- Structured logs with
correlation_idacross order/payment/delivery services - Kafka event flow from
ORDER_CREATED→PAYMENT_SUCCESS/PAYMENT_FAILED→ delivery action
The Payment Service randomly returns:
- SUCCESS
- FAILURE
This demonstrates:
- Real-world unpredictability
- System resilience
- Service logs across components
- Event tracing through the flow
- Structured JSON logs in the Order Service, Payment Service, and Delivery Service
- Correlation ID propagation via
X-Correlation-ID - Kafka event metadata in logs for better tracing
Order Service now exposes Prometheus metrics at /metrics, including:
- total orders created
- Kafka publish success/failure counts
- order processing latency
Payment and Delivery services now log:
- startup and consumer readiness
- received Kafka events
- event handling decisions
- delivery assignment or skip actions
Use docker-compose logs -f order_service payment_service delivery_service to follow the full saga execution.
- Kafka publish success/failure counts
- order processing latency
Why Prometheus?
- It collects runtime metrics automatically
- It lets you monitor service behavior over time
- It helps answer questions like “how many orders are processed” and “how long order creation takes”
Potential extensions:
- Grafana for dashboarding
- OpenTelemetry for distributed traces
- Add OpenTelemetry tracing
- Add JWT authentication
- Add Kubernetes deployment
- Add retry logic and DLQ (Dead Letter Queue)
- Add a UI dashboard
- Real-world distributed system behavior
- Event-driven design
- Failure handling using Saga
- Production thinking, not just code