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: Manage orders, kitchen, KDS, menu items, printers, users, webhooks (GrubHub, Uber Eats), Square POS, KPIs, and busy level definitions.

Kitchen Display System (KDS)¶

The KDS is built with Blazor and provides real-time kitchen operations with the following 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/): Key components include Orders.razor (main order display), AppHeader.razor (header with controls), BatchItemCard.razor (individual batch item display), BatchItems.razor (batch management), and FooterButtons.razor (action buttons).

Web Application¶

Our modern React + TypeScript frontend offers:

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: Built with React 18, TypeScript, Vite, Material-UI/custom components, state management (Context/Redux), and real-time updates via SignalR.

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

This layer contains all domain logic and business rules. Services within this layer (e.g., OrderLogic.cs, KitchenLogic.cs, KdsLogic.cs) handle core functionalities like order processing, kitchen operations, KDS display logic, menu management, printer job management, user operations, brand support, GrubHub integration, authentication, KPI calculations, busy level logic, food cost, and master data management. Helper utilities are located in Util/.

External Service Integrations¶

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

This integration handles:

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

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

This integration covers:

Order receiving and processing.
Menu updates.
Store availability.
Delivery tracking.

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

This integration manages:

POS data synchronization.
Payment processing.
Menu item synchronization.
Inventory tracking.

Other Integrations¶

We also integrate with:

Otter: For multi-platform order aggregation.
Slack: For team notifications and alerts. Primary channel: #engineer-bug-requests
Aircall: For call tracking and management.
7shifts: For staff scheduling.
CloudKitchen: For facility management.
Weather: For weather-based predictions.
Snowflake: For data warehousing and analytics.

Background Workers¶

The Workers project handles asynchronous tasks with the following responsibilities and features:

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
.NET Aspire
Metalama
Node.js and npm: For the React frontend.
Git: Version control.

Installation Steps¶

Clone the repository.
Install Metalama (for Workers project).
Set up the Web frontend.
Configure environment variables: Database connection strings, API keys for external services, Redis connection, authentication secrets.
Run the application via AppHost. 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¶

You can run individual projects by navigating to their respective directories:

API Service: Orbital.ApiService
Web App: Orbital.Web
KDS: Orbital.KDS/Orbital.KDS
Workers: Orbital.Workers

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.
Deploy using azd up.
Follow prompts to: Select subscription, choose region, configure resources, and 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 include:

Order: Customer orders with items, status, and 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 the following:

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¶

We optimize performance at multiple levels:

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 cover:

Database connectivity.
Redis availability.
External service status (GrubHub, Uber, etc.).
Worker service status.

Health checks are accessible at: /health.

Logging¶

Structured logging is implemented with:

Application Insights (Azure).
Serilog.
Log levels: Debug, Info, Warning, Error, Critical.

Metrics¶

Key metrics tracked include:

Request latency.
Error rates.
Order processing time.
External API response times.
Cache hit/miss rates.
Worker execution times.

Testing¶

Our testing strategy includes:

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¶

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/`)¶