Distributed Order Fulfillment Platform

A production-grade microservices platform for order fulfillment with high concurrency, distributed transactions (Saga pattern), and fault tolerance.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Client Applications                             │
│                         (Web App, Mobile App, Partners)                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              API Gateway                                     │
│                    (Auth, Rate Limiting, Routing, CORS)                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
            ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
            │    Order     │  │  Inventory   │  │   Payment    │
            │   Service    │  │   Service    │  │   Service    │
            │   (Saga)     │  │  (Locking)   │  │ (Idempotent) │
            └──────────────┘  └──────────────┘  └──────────────┘
                    │                 │                 │
                    └─────────────────┼─────────────────┘
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            Apache Kafka                                      │
│              (orders.created, inventory.reserved, payment.success)           │
└─────────────────────────────────────────────────────────────────────────────┘
                    │                 │                 │
                    ▼                 ▼                 ▼
            ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
            │  Fulfillment │  │ Notification │  │    Redis     │
            │   Service    │  │   Service    │  │    Cache     │
            └──────────────┘  └──────────────┘  └──────────────┘

✨ Features

• Saga Pattern - Distributed transactions with compensating actions
• Idempotency - Duplicate request handling with idempotency keys
• Database Locking - Pessimistic & optimistic locking for inventory
• Event-Driven - Kafka-based async communication
• Multi-Cloud - Terraform for AWS & GCP
• Observability - Structured logging, tracing, metrics

📦 Project Structure

distributed-fulfillment-platform/
├── .github/workflows/          # CI/CD pipelines
├── api/                        # API contracts
│   ├── openapi/                # REST API specs
│   └── proto/                  # gRPC definitions
├── apps/                       # Microservices
│   ├── api-gateway/
│   ├── order-service/
│   ├── inventory-service/
│   ├── payment-service/
│   ├── fulfillment-service/
│   └── notification-service/
├── libs/                       # Shared libraries
│   ├── common/
│   ├── database/
│   ├── messaging/
│   └── logger/
├── infra/                      # Infrastructure
│   ├── docker-compose.yml
│   ├── k8s/
│   └── terraform/
└── tools/                      # Scripts & utilities

🚀 Quick Start

Prerequisites

• Go 1.23+
• Docker & Docker Compose
• Make

Local Development

# Clone repository
git clone https://github.com/bhushanasati25/Distributed-Order-Fulfillment-Platform.git
cd Distributed-Order-Fulfillment-Platform

# Start infrastructure (PostgreSQL, Redis, Kafka)
make infra-up

# Run all services
make run-all

# Or run individual service
make run-order

API Testing

# Create an order
curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customer_id": "cust_123",
    "items": [
      {"sku": "PROD-001", "quantity": 2, "price": 29.99}
    ],
    "shipping_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001"
    }
  }'

# Check order status
curl http://localhost:8080/api/v1/orders/{order_id}

🔄 Saga Flow

1. Client → Order Service: POST /orders
2. Order Service: Creates PENDING order
3. Order Service → Kafka: Publish "OrderCreated"
4. Inventory Service: Consumes event → Reserves stock
5. Inventory Service → Kafka: Publish "StockReserved"
6. Payment Service: Consumes event → Charges card
7. Payment Service → Kafka: Publish "PaymentSuccess"
8. Order Service: Consumes event → Updates to CONFIRMED
9. Notification Service: Sends confirmation email

Compensating Transactions

If Payment fails:
1. Payment Service → Kafka: Publish "PaymentFailed"
2. Inventory Service: Releases reserved stock
3. Order Service: Updates to CANCELLED
4. Notification Service: Sends cancellation email

🛠️ Tech Stack

Component	Technology
Language	Go 1.23
API	REST + gRPC
Messaging	Apache Kafka
Database	PostgreSQL 15
Cache	Redis 7
Container	Docker
Orchestration	Kubernetes
IaC	Terraform
CI/CD	GitHub Actions

📊 Services

Service	Port	Description
API Gateway	8080	Entry point, auth, rate limiting
Order Service	8081	Order lifecycle, Saga orchestrator
Inventory Service	8082	Stock management, reservations
Payment Service	8083	Payment processing, Stripe/PayPal
Fulfillment Service	8084	Shipping, FedEx/UPS integration
Notification Service	8085	Email/SMS notifications

🧪 Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Integration tests (requires Docker)
make test-integration

# Load testing
make test-load

📈 Monitoring

• Metrics: Prometheus + Grafana
• Tracing: Jaeger / OpenTelemetry
• Logging: Structured JSON logs (zerolog)

🚢 Deployment

Docker Compose (Development)

docker-compose -f infra/docker-compose.yml up -d

Kubernetes (Production)

# Apply Helm charts
helm install fulfillment-platform ./infra/k8s/charts/platform

# Or using kubectl
kubectl apply -f ./infra/k8s/manifests/

Terraform (Cloud Infrastructure)

cd infra/terraform/aws  # or gcp
terraform init
terraform plan
terraform apply

📄 License

MIT License - see LICENSE for details.

👥 Contributing

See CONTRIBUTING.md for contribution guidelines.

👨‍💻 Author

Bhushan Asati

• GitHub: @bhushanasati25
• Repository: Distributed-Order-Fulfillment-Platform