Skip to content

Orbital Manager Backend

Welcome to the Orbital Manager Backend team wiki.

What You'll Find Here

This comprehensive documentation covers everything you need to know about our backend microservices architecture.

AI Agents Start Here: This is the main entry point for understanding the codebase.

System Architecture

graph TB
    subgraph External
        O[Otter]
        F[Frontend]
        SF[Snowflake]
        PG[(PostgreSQL)]
    end

    subgraph "Order Management Service :8001"
        WH[Webhook Endpoint]
        RMQ_PUB[RabbitMQ Publisher]
        OMS_WORKERS[Background Workers]
    end

    subgraph "Kitchen Batch Tool Service :8000"
        RMQ_CON[RabbitMQ Consumer]
        BI_API[Batch Items API]
        SSE[SSE Endpoint]
    end

    subgraph "Kitchen Prep Tool Service :8002"
        PREP_API[Prep Inventory API]
        TU_API[TU Inventory API]
        PAR_API[PAR Management API]
    end

    O -->|Webhooks| WH
    WH -->|Publish| RMQ_PUB
    RMQ_PUB -->|Protobuf Messages| RMQ_CON
    RMQ_CON -->|Process| BI_API
    BI_API -->|Events| SSE
    SSE -->|Real-time| F
    PREP_API -->|REST| F

Services

Order Management Service

Port: 8001

Purpose: Central hub for order processing. Receives orders from Otter POS system via webhooks, normalizes order data, stores it in PostgreSQL, and distributes structured orders to kitchen services via RabbitMQ.

What It Does: - Receives real-time order events from Otter (new orders, cancellations, status updates) - Processes and normalizes order data into standardized format - Stores orders in PostgreSQL for operational queries - Distributes processed orders to kitchen services via RabbitMQ - Synchronizes customer and promotion data to Snowflake for analytics - Provides REST APIs for order queries and status tracking

Key Features: - HTTP webhook endpoint for Otter events - RabbitMQ publisher for order distribution - Otter event consumer worker for processing events - Background workers for data synchronization - REST API for order management

Kitchen Batch Tool Service

Port: 8000

Purpose: Manages real-time batch processing workflow in commercial kitchens. Receives orders, calculates batch items (grouped by station), and provides real-time updates to kitchen staff.

What It Does: - Consumes structured order messages from RabbitMQ - Calculates batch items by grouping order items by kitchen station - Manages active kitchen sessions (work periods) - Tracks batch item status: - pending - → in progress - → completed - Streams real-time updates to frontend via Server-Sent Events - Persists batch items and sessions to PostgreSQL - Synchronizes session data to Snowflake for analytics

Key Features: - RabbitMQ consumer for order messages - Server-Sent Events for real-time updates - REST API for batch item management - PostgreSQL for data persistence - Reference data cache for fast lookups - Background workers for session data sync

Kitchen Prep Tool Service

Port: 8002

Purpose: Manages inventory, prep work, and product tracking for commercial kitchens. Handles prep inventory, transfer units, PAR levels, and product scanning workflows.

What It Does: - Tracks prep inventory (prepared items, quantities, expiration dates) - Manages transfer units (inventory movements between locations) - Monitors PAR levels (minimum stock levels) and sends low stock alerts - Processes product scans for inventory verification and tracking - Maintains master product catalog - Synchronizes inventory data to Snowflake for analytics

Key Features: - Authentication and authorization - Prep inventory management - Transfer units (TU) inventory management - PAR (Periodic Automatic Replenishment) level management - Master product management - Product scanning and tracking - Background workers for data sync and notifications

Shared Components

Databases: PostgreSQL connection management (Supabase), Snowflake initialization, Redis Cache initialization, connection retry logic.

Messaging: RabbitMQ connection management, structured order publisher/consumer (structured_order_data exchange), Otter event publisher/consumer (otter_events exchange), Protocol Buffer serialization.

Patterns: BackgroundService base class for continuous workers, SingletonManager pattern, AsyncRepository pattern (used by Kitchen Prep Tool Service).

Utilities: Structured logging (shared.utils.logger), secret management via Azure Key Vault (shared.utils.secret_manager), Sentry error tracking, PDF generation, template rendering, Slack notifications.

Quick Start

# 1. Clone and install
git clone https://github.com/Orbital-Kitchens/orbital-manager-backend.git
cd orbital-manager-backend
pip install -r requirements.txt

# 2. Configure environment
cp .env.example .env
# Edit .env with your settings

# 3. Start services
# Terminal 1 - Kitchen Batch Tool Service
cd kitchen_batch_tool_service && uvicorn app.main:app --reload --port 8000

# Terminal 2 - Order Management Service
cd order_management_service && uvicorn app.main:app --reload --port 8001

# Terminal 3 - Kitchen Prep Tool Service
cd kitchen_prep_tool_service && uvicorn app.main:app --reload --port 8002

# 4. Test
curl http://localhost:8000/ping
curl http://localhost:8001/ping
curl http://localhost:8002/ping

Common Tasks

Test Otter Webhook

curl -X POST http://localhost:8001/webhooks/otter \
  -H "Content-Type: application/json" \
  -d @test_webhook_payload.json

Watch Order Events (SSE)

curl -N http://localhost:8000/orders/events

Run Tests

# All tests
pytest

# With coverage
pytest --cov=app --cov-report=html

# Specific service
pytest kitchen_batch_tool_service/tests/

Lint Code

# Check for issues
ruff check .

# Auto-fix issues
ruff check . --fix

# Format code
ruff format .

Tech Stack

  • Language: Python 3.11+
  • Framework: FastAPI
  • Databases: PostgreSQL (orders, batch items, prep inventory), Snowflake (analytics, reference data sync)
  • Message Broker: RabbitMQ (FANOUT exchanges for pub/sub)
  • Serialization: Protocol Buffers
  • Linting: Ruff
  • Testing: pytest

Key Features

  • Otter Webhook Integration: Direct HTTP webhook endpoint receives orders from Otter POS
  • RabbitMQ FANOUT Exchanges: otter_events and structured_order_data exchanges for pub/sub messaging
  • Server-Sent Events: Real-time order updates to frontend (Kitchen Batch Tool Service)
  • Structured Logging: Context-rich logging via shared.utils.logger
  • Monorepo with Shared Components: shared/ folder for common code, accessed via sys.path manipulation
  • SQL Organization: Queries separated by database type (postgres_sql/, snowflake_sql/)
  • Repository Pattern: Kitchen Prep Tool Service uses async repository for complex data access
  • Background Workers: Service-specific workers in app/workers/ (never in shared/)

Performance

  • Protocol Buffers for compact message serialization
  • Async/await throughout for non-blocking I/O
  • Connection pooling for databases
  • Reference data cache (e.g., ReferenceDataCache in Kitchen Batch Tool) reduces database load
  • Type safety via Protocol Buffers

Resilience

  • Webhook endpoints handle errors gracefully
  • RabbitMQ message persistence and delivery guarantees
  • Services start even if dependencies are down (graceful degradation)
  • Clean shutdown with 5-second grace period
  • Sentry error tracking with Linear integration

Contributing

We welcome contributions! Please read our Best Practices guide before submitting PRs.

Quick Checklist

  • Follow coding standards (run ruff check)
  • Add tests (aim for good coverage)
  • Update documentation
  • Write clear commit messages
  • Create focused PRs

Get Help

Learn the Architecture

Start with Architecture Overview to understand how everything fits together.

Set Up Development

Follow Getting Started to get your environment running.

Understand the Services

  • Order Management Service - Order detection and distribution via RabbitMQ
  • Kitchen Batch Tool Service - Order processing and batch management
  • Kitchen Prep Tool Service - Prep inventory, PAR, and product management

Code Organization

Deployment

Built by the Orbital Kitchens Team

Report a Bug · Request a Feature · View Source