Skip to content

Folder Structure Guide

This document explains the folder structure and organization patterns used across the Orbital Manager Backend services.

Monorepo Structure

See the repository root: orbital-manager-backend/

  • Services: order_management_service/, kitchen_batch_tool_service/, kitchen_prep_tool_service/
  • Shared: shared/ - Common components (databases, messaging, utils)
  • Deployment: deploy/ - Docker and Nginx configuration

Service Structure

Each service follows a consistent structure. See example: order_management_service/

  • app/main.py - FastAPI entry point
  • app/routers/ - API endpoints
  • app/services/ - Business logic
  • app/sql/ - SQL queries (organized by database type)
  • app/workers/ - Background workers
  • tests/ - Test files

SQL Folder Pattern

Organize queries by database type. See example: order_management_service/app/sql/

  • postgres_sql/ - PostgreSQL queries (operational data)
  • snowflake_sql/ - Snowflake queries (analytical data)

Repository Pattern (Kitchen Prep Tool Service)

The Kitchen Prep Tool Service uses a repository pattern for data access. See example: kitchen_prep_tool_service/app/data/master_product/

Service Layer Pattern

Business logic is separated from data access. See example: order_management_service/app/services/

Router Pattern

API endpoints are organized by feature. See example: order_management_service/app/routers/

Worker Pattern

Background workers are organized by task. See examples: - APScheduler: order_management_service/app/workers/customer_data_sync/worker.py - BackgroundService: kitchen_batch_tool_service/app/workers/session_data_sync/worker.py

Important: Workers must be in app/workers/ within each service, never in shared/.

Shared Components

The shared/ folder contains reusable components. See shared/:

  • databases/ - Database initialization
  • messaging/ - RabbitMQ messaging
  • proto/ - Protocol buffers
  • patterns/ - Design patterns (BackgroundService, etc.)
  • utils/ - Utilities (logging, secrets, Sentry, etc.)

Testing Structure

Tests mirror the application structure. See example: order_management_service/tests/