Orbital Platform¶

The Orbital Platform is a comprehensive kitchen management system built with .NET 8 and ASP.NET Core, designed to streamline restaurant operations, order management, and kitchen workflows.

Overview¶

Orbital is the core platform that powers Orbital Kitchens' operations, providing:

Order Management: Real-time order processing and tracking
Kitchen Display System (KDS): Interactive displays for kitchen operations
POS Integration: Integration with Square and other POS systems
Delivery Service Integration: GrubHub, Uber Eats, and other delivery platforms
Analytics & Reporting: Business intelligence and KPI tracking
Printer Management: Automated printing of order tickets
Staff Management: Integration with 7shifts for scheduling

Architecture¶

The Orbital platform follows a modular architecture using .NET Aspire for orchestration:

graph TB
    subgraph "Presentation Layer"
        WEB[Web App<br/>React + TypeScript + Vite]
        KDS_UI[KDS App<br/>Blazor WebAssembly]
    end

    subgraph "Application Layer"
        APPHOST[App Host<br/>.NET Aspire Orchestration]
        API[API Service<br/>ASP.NET Core Web API]
        KDS_SERVER[KDS Server<br/>Blazor Server]
    end

    subgraph "Business Logic Layer"
        LOGIC[Orbital.Logic<br/>Business Rules & Services]
    end

    subgraph "Service Layer"
        GRUBHUB[GrubHub Service]
        UBER[UberEats Service]
        SQUARE[Square Service]
        OTTER[Otter Service]
        SLACK[Slack Service]
        WEATHER[Weather Service]
        AIRCALL[Aircall Service]
        SEVENSHIFT[7Shifts Service]
        SNOWFLAKE[Snowflake Service]
        CLOUDKITCHEN[CloudKitchen Service]
    end

    subgraph "Data Layer"
        ORBITALDB[(OrbitalDB<br/>PostgreSQL)]
        CACHE[(Redis Cache)]
    end

    subgraph "Background Processing"
        WORKERS[Background Workers<br/>Order Processing, Sync, Monitoring]
    end

    WEB --> API
    KDS_UI --> KDS_SERVER
    KDS_SERVER --> API
    APPHOST --> API
    APPHOST --> KDS_SERVER
    APPHOST --> WORKERS
    APPHOST --> WEB

    API --> LOGIC
    KDS_SERVER --> LOGIC
    WORKERS --> LOGIC

    LOGIC --> GRUBHUB
    LOGIC --> UBER
    LOGIC --> SQUARE
    LOGIC --> OTTER
    LOGIC --> SLACK
    LOGIC --> WEATHER
    LOGIC --> AIRCALL
    LOGIC --> SEVENSHIFT
    LOGIC --> SNOWFLAKE
    LOGIC --> CLOUDKITCHEN

    LOGIC --> ORBITALDB
    LOGIC --> CACHE

    WORKERS --> GRUBHUB
    WORKERS --> UBER
    WORKERS --> ORBITALDB

    style WEB fill:#e1f5ff
    style KDS_UI fill:#e1f5ff
    style API fill:#fff3e0
    style LOGIC fill:#c8e6c9
    style WORKERS fill:#ffccbc

Project Structure¶

Orbital/
├── Orbital.AppHost/              # .NET Aspire orchestration
├── Orbital.ApiService/           # Main API service
│   ├── Controllers/              # API endpoints
│   ├── Health/                   # Health checks
│   ├── ML/                       # Machine learning models
│   └── Models/                   # Data models
├── Orbital.Web/                  # React frontend
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   ├── pages/                # Page components
│   │   ├── hooks/                # Custom React hooks
│   │   ├── types/                # TypeScript types
│   │   └── utils/                # Utility functions
│   └── public/                   # Static assets
├── Orbital.KDS/                  # Kitchen Display System
│   ├── Orbital.KDS/              # Blazor Server
│   └── Orbital.KDS.Client/       # Blazor WebAssembly
├── Orbital.Logic/                # Business logic layer
│   ├── *Logic.cs                 # Domain logic services
│   └── Util/                     # Helper utilities
├── Orbital.Services/             # External integrations
│   ├── GrubHub/                  # GrubHub integration
│   ├── UberEats/                 # Uber Eats integration
│   ├── SquareService/            # Square POS integration
│   ├── Otter/                    # Otter integration
│   ├── Slack/                    # Slack notifications
│   ├── Aircall/                  # Call management
│   ├── SevenShift/               # Staff scheduling
│   ├── CloudKitchen/             # CloudKitchen integration
│   ├── Weather/                  # Weather service
│   ├── Snowflake/                # Data warehouse
│   ├── OrbitalDB/                # Database access
│   └── OrbitalCache/             # Caching service
├── Orbital.Workers/              # Background workers
│   ├── Workers/                  # Worker services
│   └── Logic/                    # Worker business logic
├── Orbital.ServiceDefaults/      # Shared service configuration
└── Orbital.Util/                 # Shared utilities

Key Components¶

API Service¶

The main API service provides RESTful endpoints for:

Authentication & Authorization: User login, JWT tokens, role-based access
Order Management: CRUD operations, status updates, filtering
Kitchen Operations: Station management, KDS control, order routing
Menu Management: Items, modifiers, pricing
Printer Management: Configuration, print jobs, status monitoring
Settings: Application configuration, user preferences
Analytics: KPIs, busy level tracking, reports
Integrations: Webhooks for delivery services, POS synchronization

Key Controllers:

Controller	Purpose
`OrderController.cs`	Order CRUD and status management
`KitchenController.cs`	Kitchen and station configuration
`KdsController.cs`	KDS display management
`MenuItemController.cs`	Menu item management
`PrinterController.cs`	Printer configuration and control
`UserController.cs`	User management and authentication
`GrubhubHookController.cs`	GrubHub webhook handling
`UberWebhookController.cs`	Uber Eats webhook handling
`SquareController.cs`	Square POS integration
`KeyPerformanceIndicatorController.cs`	KPI tracking and reporting
`BusyLevelDefinitionController.cs`	Kitchen capacity management

Kitchen Display System (KDS)¶

The KDS is built with Blazor and provides real-time kitchen operations:

Features: - Real-time order display with SignalR updates - Batch item grouping and management - Order status tracking (pending → in progress → completed) - Timer tracking for order preparation - Touch-optimized interface for kitchen staff - Theme switching (light/dark mode) - Font size customization - Multi-station support

Components (Orbital.KDS/Orbital.KDS/Components/): - Orders.razor: Main order display component - AppHeader.razor: Header with controls - BatchItemCard.razor: Individual batch item display - BatchItems.razor: Batch management - FooterButtons.razor: Action buttons

Web Application¶

Modern React + TypeScript frontend with:

Key Features: - Real-time order monitoring dashboard - Kitchen management interface - Menu item configuration - Printer setup and management - User authentication and role management - Analytics and reporting dashboards - Settings configuration - Multi-brand support

Technology Stack: - React 18 - TypeScript - Vite (build tool) - Material-UI / Custom components - State management (Context/Redux) - Real-time updates via SignalR

Business Logic Layer (`Orbital.Logic/`)¶

Contains all domain logic and business rules:

Service	Responsibility
`OrderLogic.cs`	Order processing, validation, routing
`KitchenLogic.cs`	Kitchen operations, station management
`KdsLogic.cs`	KDS display logic, batch management
`MenuItemLogic.cs`	Menu management, pricing rules
`PrinterLogic.cs`	Print job management, routing
`UserLogic.cs`	User operations, permissions
`BrandLogic.cs`	Multi-brand support
`GrubhubLogic.cs`	GrubHub order processing
`AuthLogic.cs`	Authentication and authorization
`KeyPerformanceIndicatorLogic.cs`	KPI calculations
`BusyLevelRuleLogic.cs`	Kitchen capacity logic
`FoodCostToolLogic.cs`	Food cost calculations
`MasterDataToolLogic.cs`	Master data management

External Service Integrations¶

GrubHub Integration (`Orbital.Services/GrubHub/`)¶

Order ingestion via webhooks
Menu synchronization
Order status updates
Real-time availability management

Uber Eats Integration (`Orbital.Services/UberEats/`)¶

Order receiving and processing
Menu updates
Store availability
Delivery tracking

Square Integration (`Orbital.Services/SquareService/`)¶

POS data synchronization
Payment processing
Menu item sync
Inventory tracking

Other Integrations¶

Otter: Multi-platform order aggregation
Slack: Team notifications and alerts
Aircall: Call tracking and management
7shifts: Staff scheduling
CloudKitchen: Facility management
Weather: Weather-based predictions
Snowflake: Data warehousing and analytics

Background Workers¶

The Workers project handles asynchronous tasks:

Responsibilities: - Order synchronization with delivery platforms - Periodic data updates - Health monitoring of external services - Scheduled reports - Data cleanup and archival - Cache warming - Alert notifications

Features: - Built with .NET Hosted Services - Aspect-oriented programming with Metalama - Dependency injection - Error handling and retry logic - Health checks

Development Setup¶

Prerequisites¶

.NET 8 SDK: Download
.NET Aspire: Install Guide
Metalama: Installation
Node.js and npm: For the React frontend
Git: Version control

Installation Steps¶

Clone the repository

git clone <repository-url>
cd orbital/Orbital

Install Metalama (for Workers project)
```
dotnet tool install -g Metalama.Tool
```
Set up the Web frontend
```
cd Orbital.Web
npm install
```
Configure environment variables
Database connection strings
API keys for external services
Redis connection
Authentication secrets
Run the application via AppHost
```
cd Orbital.AppHost
dotnet run
```

The AppHost will orchestrate all services: - API Service: Usually on a port like 5000 - Web App: Port 3000 (required for Google Auth) - KDS: Dynamic port - Workers: Background services

Development Workflow¶

Main development branch: aspire
Make changes to the relevant project
Run locally via Orbital.AppHost
Test functionality
Commit and push changes

Running Individual Projects¶

API Service:

cd Orbital.ApiService
dotnet run

Web App:

cd Orbital.Web
npm run dev

KDS:

cd Orbital.KDS/Orbital.KDS
dotnet run

Workers:

cd Orbital.Workers
dotnet run

Deployment¶

The Orbital platform is deployed to Azure using Azure Developer CLI (azd):

Prerequisites¶

Azure CLI installed
Azure subscription
Proper permissions

Deployment Steps¶

Login to Azure
```
az login
```
Deploy
```
azd up
```
Follow prompts to:
Select subscription
Choose region
Configure resources
Deploy services

CI/CD¶

Deployment is automated via GitHub Actions: - On push to main: Deploy to production - On push to develop: Deploy to staging - PR checks: Build and test

API Documentation¶

API documentation is auto-generated and available at:

Development: http://localhost:<port>/swagger
Production: https://<your-domain>/swagger

Authentication¶

Most endpoints require JWT authentication:

Login via /api/auth/login
Receive JWT token
Include token in Authorization: Bearer <token> header

Key Endpoints¶

POST   /api/auth/login                    # User login
GET    /api/orders                         # List orders
POST   /api/orders                         # Create order
GET    /api/orders/{id}                    # Get order details
PUT    /api/orders/{id}                    # Update order
DELETE /api/orders/{id}                    # Delete order

GET    /api/kitchens                       # List kitchens
GET    /api/kitchens/{id}/stations         # Get kitchen stations
POST   /api/kds/batch-items                # Create batch items

GET    /api/menu-items                     # List menu items
POST   /api/menu-items                     # Create menu item
PUT    /api/menu-items/{id}                # Update menu item

GET    /api/printers                       # List printers
POST   /api/printers/{id}/test             # Test printer

GET    /api/kpi                            # Get KPIs
GET    /api/busy-level                     # Get current busy level

POST   /webhook/grubhub                    # GrubHub webhook
POST   /webhook/uber                       # Uber webhook

Database Schema¶

The system uses PostgreSQL via Entity Framework Core:

Key Entities¶

Order: Customer orders with items, status, timestamps
OrderItem: Individual items within an order
Kitchen: Physical kitchen locations
KitchenStation: Preparation stations within kitchens
MenuItem: Menu items with pricing and categories
Printer: Printer configuration and status
User: System users with roles and permissions
Brand: Multi-brand support
PrintJob: Print job queue and history
BusyLevel: Kitchen capacity tracking
KPI: Key performance indicators

Caching Strategy¶

Redis is used for caching:

Menu items: Frequently accessed, rarely changed
Kitchen configurations: Station setups
User sessions: Authentication tokens
Real-time data: Order statuses, busy levels
API responses: Cached for performance

Cache Keys Pattern:

orbital:{entity}:{id}
orbital:menu:all
orbital:kitchen:{id}:stations
orbital:orders:active

Performance Optimization¶

API Level¶

Response caching
Database query optimization
Connection pooling
Asynchronous operations
Pagination for large datasets

Frontend Level¶

Code splitting
Lazy loading
Optimized bundle size
Service worker caching
SignalR for real-time updates (vs polling)

Database Level¶

Proper indexing
Query optimization
Connection pooling
Read replicas for analytics

Monitoring & Observability¶

Health Checks¶

Built-in health checks for: - Database connectivity - Redis availability - External service status (GrubHub, Uber, etc.) - Worker service status

Access at: /health

Logging¶

Structured logging with: - Application Insights (Azure) - Serilog - Log levels: Debug, Info, Warning, Error, Critical

Metrics¶

Key metrics tracked: - Request latency - Error rates - Order processing time - External API response times - Cache hit/miss rates - Worker execution times

Testing¶

Unit Tests¶

xUnit framework
Moq for mocking
FluentAssertions
Business logic coverage

Integration Tests¶

WebApplicationFactory
Test database
API endpoint testing

Running Tests¶

dotnet test

Security¶

Authentication¶

JWT-based authentication
Token expiration and refresh
Role-based authorization

Authorization¶

Claims-based permissions
Role hierarchy (Admin, Manager, Staff)
Action-level authorization

Data Protection¶

Encrypted connection strings
Secure API keys in Azure Key Vault
HTTPS enforcement
CORS configuration

Troubleshooting¶

Common Issues¶

Issue: AppHost fails to start - Solution: Ensure all required ports are available, check configuration

Issue: Database connection errors - Solution: Verify connection string, check database server status

Issue: External service integration failures - Solution: Check API keys, network connectivity, service status

Issue: React app not loading on port 3000 - Solution: Google Auth requires port 3000, change port configuration

Logs Location¶

Development: Console output
Production: Application Insights
File logs: logs/ directory (if configured)

Contributing¶

Create feature branch from aspire
Make changes
Write tests
Submit pull request
Code review
Merge to aspire

Orbital Platform¶

Overview¶

Architecture¶

Project Structure¶

Key Components¶

API Service¶

Kitchen Display System (KDS)¶

Web Application¶

Business Logic Layer (Orbital.Logic/)¶

External Service Integrations¶

GrubHub Integration (Orbital.Services/GrubHub/)¶

Uber Eats Integration (Orbital.Services/UberEats/)¶

Square Integration (Orbital.Services/SquareService/)¶

Other Integrations¶

Background Workers¶

Development Setup¶

Prerequisites¶

Installation Steps¶

Development Workflow¶

Running Individual Projects¶

Deployment¶

Prerequisites¶

Deployment Steps¶

CI/CD¶

API Documentation¶

Authentication¶

Key Endpoints¶

Database Schema¶

Key Entities¶

Caching Strategy¶

Performance Optimization¶

API Level¶

Frontend Level¶

Database Level¶

Monitoring & Observability¶

Health Checks¶

Logging¶

Metrics¶

Testing¶

Unit Tests¶

Integration Tests¶

Running Tests¶

Security¶

Authentication¶

Authorization¶

Data Protection¶

Troubleshooting¶

Common Issues¶

Logs Location¶

Contributing¶

Additional Resources¶

Business Logic Layer (`Orbital.Logic/`)¶

GrubHub Integration (`Orbital.Services/GrubHub/`)¶

Uber Eats Integration (`Orbital.Services/UberEats/`)¶

Square Integration (`Orbital.Services/SquareService/`)¶