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.

📖 Quick Links¶

Architecture Overview - System design and data flow
Getting Started - Set up your development environment
Order Flow - How orders move through the system
gRPC Services - Inter-service communication
Contributing - How to contribute to the project

📚 Recent Updates¶

Batch Item Update Summary - Complete batch item system changes
Batch Item Quick Reference - API endpoints and examples

🏗️ System Architecture¶

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

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

    subgraph "Kitchen Batch Tool Service :8001"
        OS[Order Server :50051]
        SSE[SSE Endpoint]
        API[REST API]
    end

    M -->|Change Stream| ML
    ML -->|gRPC| OC
    OC -->|OrderRequest| OS
    OS -->|Events| SSE
    SSE -->|Real-time| F
    API -->|HTTP| F

📦 Services¶

Order Management Service¶

Monitors MongoDB for new orders and distributes them to kitchen services.

Key Features: - MongoDB change stream monitoring - Async connections with retry logic - gRPC client for order sending

Kitchen Batch Tool Service¶

Receives orders and manages batch item processing.

Key Features: - gRPC server for order receiving - Server-Sent Events for real-time updates - REST API for batch item management - PostgreSQL for data persistence

🔧 Shared Components¶

Databases¶

MongoDB async initialization
PostgreSQL connection management
Connection retry logic

gRPC¶

Order client implementation
Order server implementation
Protocol buffer definitions

Patterns¶

BackgroundService base class
SingletonManager pattern

🚀 Quick Start¶

# 1. Clone and install
git clone <repo-url>
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
cd order_management_service && uvicorn app.main:app --reload --port 8000

# Terminal 2  
cd kitchen_batch_tool_service && uvicorn app.main:app --reload --port 8001

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

💡 Common Tasks¶

Insert Test Order¶

db.orders.insertOne({
  OtterOrderId: "test-001",
  BrandName: "Test Restaurant",
  StationOrders: [{
    OwnStationName: "Grill Station",
    OrderItems: [
      { Name: "Burger", Quantity: 2 }
    ]
  }]
})

Watch Order Events (SSE)¶

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

Run Tests¶

pytest
pytest --cov=app

Lint Code¶

ruff check .
ruff check --fix .

📊 Tech Stack¶

Language: Python 3.9+
Framework: FastAPI
Databases: MongoDB (orders), PostgreSQL (batch items)
RPC: gRPC + Protocol Buffers
Build System: Bazel
Linting: Ruff
Testing: pytest
Documentation: MkDocs Material

🎯 Key Features¶

Feature	Description
Async MongoDB	Non-blocking with exponential backoff retry (1s → 60s)
gRPC Communication	Type-safe, efficient inter-service messaging
Server-Sent Events	Real-time order updates to frontend
Structured Logging	Context-rich logging for debugging
Monorepo	Shared components across all services
Graceful Degradation	Services continue running during failures

📈 Performance¶

93% payload reduction: Structured proto vs full JSON
Async all the way: Non-blocking I/O throughout
Connection pooling: Efficient resource usage
Type safety: Catch errors at compile time

🛡️ Resilience¶

MongoDB listener retries with exponential backoff
gRPC error handling and recovery
Services start even if dependencies are down
Graceful shutdown with 5-second grace period

🤝 Contributing¶

We welcome contributions! Please read our Contributing Guide before submitting PRs.

Quick Checklist¶

📞 Get Help¶

Documentation: You're reading it! 📚
Issues: Check GitHub issues for known problems
Team Chat: #backend-dev on Slack
Email: team@orbitalkitchens.com

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
Kitchen Batch Tool Service - Order processing and batch management

Work with Shared Code¶

Shared Components - Reusable libraries and patterns

**Built with ❤️ by the Orbital Kitchens Team** [Report a Bug](https://github.com/your-org/orbital-manager-backend/issues) · [Request a Feature](https://github.com/your-org/orbital-manager-backend/issues) · [View Source](https://github.com/your-org/orbital-manager-backend)