System Architecture Overview¶

🎯 Design Philosophy¶

The Orbital Manager Backend is designed as a microservices architecture within a monorepo. This approach provides:

Separation of Concerns: Each service has a single, well-defined responsibility
Shared Components: Common code lives in the shared/ folder
Independent Deployment: Services can be deployed and scaled independently
Type Safety: gRPC with Protocol Buffers ensures type-safe communication

🏗️ Service Architecture¶

graph TB
    subgraph External
        M[MongoDB]
        F[Frontend]
    end

    subgraph "Order Management Service"
        ML[MongoDB Listener]
        OC[Order gRPC Client]
    end

    subgraph "Kitchen Batch Tool Service"
        OS[Order gRPC Server]
        SSE[SSE Endpoint]
        BI[Batch Items API]
    end

    subgraph "Shared Components"
        DB[Databases]
        GRPC[gRPC Implementations]
        PAT[Patterns]
    end

    M -->|Change Stream| ML
    ML -->|Extract & Send| OC
    OC -->|gRPC Proto| OS
    OS -->|Events| SSE
    SSE -->|Real-time| F
    BI -->|REST| F

    ML -.->|Uses| DB
    ML -.->|Uses| PAT
    OC -.->|Implements| GRPC
    OS -.->|Implements| GRPC

📦 Services¶

Order Management Service¶

Responsibility: Monitor MongoDB for new orders and distribute them to kitchen services

Key Components: - MongoDB change stream listener with exponential backoff retry - gRPC client for sending orders - Async MongoDB connection management

Port: 8000 (FastAPI)

Dependencies: - MongoDB - Kitchen Batch Tool Service (gRPC)

Kitchen Batch Tool Service¶

Responsibility: Receive orders and manage batch item processing

Key Components: - gRPC server for receiving orders - Server-Sent Events for frontend updates - PostgreSQL for batch item persistence - REST API for batch item management

Ports: - 8001 (FastAPI) - 50051 (gRPC)

Dependencies: - PostgreSQL - Order Management Service proto

🔄 Data Flow¶

Order Processing Flow¶

sequenceDiagram
    participant M as MongoDB
    participant OMS as Order Management Service
    participant KBT as Kitchen Batch Tool Service
    participant FE as Frontend

    M->>OMS: New order insert
    OMS->>OMS: Parse MongoDB document
    OMS->>OMS: Extract essential fields
    OMS->>KBT: SendOrder(gRPC)
    KBT->>KBT: Display to console
    KBT->>KBT: Publish to SSE queue
    KBT->>FE: Stream event (SSE)
    KBT-->>OMS: OrderResponse

Data Transformation¶

MongoDB Document (Input):

{
  "_id": "67adcfdc15da8840bc9673bd",
  "OtterOrderId": "019c52aa-1232-307c-b56d-1a3af34b458c",
  "BrandName": "Desayuna",
  "CustomerName": "Frankie P",
  "Total": "78.64",
  "StationOrders": [
    {
      "OwnStationName": "Burger Plancha Station",
      "OrderItems": [
        {"Name": "Burger", "Quantity": 2}
      ]
    }
  ],
  // ... 50+ more fields
}

gRPC Message (Transmitted):

OrderRequest {
  order_id: "67adcfdc15da8840bc9673bd"
  otter_order_id: "019c52aa-1232-307c-b56d-1a3af34b458c"
  brand_name: "Desayuna"
  order_items: [
    {
      item_name: "Burger"
      station_name: "Burger Plancha Station"
      quantity: 2
    }
  ]
  // Only 6 fields total - 90% reduction!
}

🛡️ Resilience Features¶

Exponential Backoff¶

MongoDB listener uses exponential backoff when connection fails: - Initial delay: 1 second - Maximum delay: 60 seconds - Pattern: 1s → 2s → 4s → 8s → 16s → 32s → 60s

Graceful Degradation¶

Order Management Service starts even if MongoDB is down
Listener retries connections automatically
Service continues running during temporary failures

Clean Shutdown¶

All services implement proper cleanup: 1. Stop background listeners 2. Close gRPC connections 3. Close database connections 4. 5-second grace period for in-flight requests

🔐 Security Considerations¶

Production Deployment

The current implementation uses insecure gRPC channels. For production:

Use TLS/SSL for gRPC connections
Implement authentication/authorization
Use secure MongoDB connection strings
Set proper CORS origins

📈 Scalability¶

Horizontal Scaling¶

Services can be scaled independently: - Multiple Order Management Service instances can watch the same MongoDB collection - Kitchen Batch Tool Service can run multiple replicas behind a load balancer - gRPC supports load balancing and health checks

Vertical Scaling¶

MongoDB connection pool can be configured
gRPC thread pool size is configurable (max_workers=10)
FastAPI uses async/await for efficient resource usage

🔍 Monitoring¶

Health Checks¶

Both services provide /ping endpoints:

curl http://localhost:8000/ping  # Order Management
curl http://localhost:8001/ping  # Kitchen Batch Tool

Structured Logging¶

All services use structured logging with context:

logger.info(
    "Order sent successfully",
    order_id=order_id,
    brand_name=brand_name,
    item_count=len(order_items)
)

Metrics (Future)¶

Future enhancements may include: - Prometheus metrics - OpenTelemetry tracing - Performance dashboards

🧪 Testing Strategy¶

Unit Tests: Test individual components in isolation
Integration Tests: Test service interactions
E2E Tests: Test complete order flow
Load Tests: Verify performance under load