orion/docs/architecture/overview.md

System Architecture

High-level overview of the Orion multi-tenant e-commerce platform architecture.

Overview

Orion is a multi-tenant e-commerce platform that supports three distinct interfaces:

• Admin - Platform administration and store management
• Store - Store dashboard for managing shops
• Shop - Customer-facing storefronts

Technology Stack

Backend

• Framework: FastAPI (Python)
• Database: PostgreSQL with SQLAlchemy ORM
• Authentication: JWT-based with bcrypt password hashing
• API: RESTful JSON APIs

Frontend

• Templates: Jinja2 server-side rendering
• JavaScript: Alpine.js for reactive components
• CSS: Tailwind CSS
• Icons: Lucide Icons

Infrastructure

• Web Server: Uvicorn (ASGI)
• Middleware: Custom middleware stack for multi-tenancy
• Static Files: FastAPI StaticFiles

System Components

1. Multi-Tenant Routing

The platform supports three deployment modes:

Custom Domain Mode

customdomain.com → Store 1 Shop
anotherdomain.com → Store 2 Shop

Subdomain Mode

store1.platform.com → Store 1 Shop
store2.platform.com → Store 2 Shop
admin.platform.com → Admin Interface

Path-Based Mode (Development Only)

platform.com/stores/store1/shop → Store 1 Shop
platform.com/stores/store2/shop → Store 2 Shop
platform.com/admin                → Admin Interface

See: Multi-Tenant System for detailed implementation

2. Middleware Stack

Custom middleware handles:

• Store detection and context injection
• Request context detection (API/Admin/Store/Shop)
• Theme loading for store shops
• Request/response logging
• Path rewriting for multi-tenant routing

See: Middleware Stack for complete documentation

3. Authentication & Authorization

• JWT-based authentication
• Role-based access control (RBAC)
• Three user roles: Admin, Store, Customer
• Hierarchical permissions system

See: Authentication & RBAC for details

4. Module System

The platform uses a modular architecture with three-tier classification:

┌─────────────────────────────────────────────────────────────┐
│                    FRAMEWORK LAYER                          │
│  (Infrastructure - always available, not modules)           │
│  Config │ Database │ Auth │ Permissions │ Observability     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     MODULE LAYER                            │
│                                                             │
│  CORE (Always Enabled)     OPTIONAL (Per-Platform)         │
│  ├── core                  ├── payments                    │
│  ├── tenancy               ├── billing                     │
│  ├── cms                   ├── inventory                   │
│  └── customers             ├── orders                      │
│                            ├── marketplace                 │
│  INTERNAL (Admin-Only)     ├── analytics                   │
│  ├── dev-tools             └── messaging                   │
│  └── monitoring                                            │
└─────────────────────────────────────────────────────────────┘

Module Features:

• Enable/disable modules per platform
• Module dependencies (billing requires payments)
• Health checks and lifecycle hooks
• Self-contained modules with own services, models, migrations

See: Module System for complete documentation

5. Request Flow

graph TB
    A[Client Request] --> B[Logging Middleware]
    B --> C[Store Context Middleware]
    C --> D[Context Detection Middleware]
    D --> E[Theme Context Middleware]
    E --> F{Request Type?}

    F -->|API /api/*| G[API Router]
    F -->|Admin /admin/*| H[Admin Page Router]
    F -->|Store /store/*| I[Store Page Router]
    F -->|Shop /shop/*| J[Shop Page Router]

    G --> K[JSON Response]
    H --> L[Admin HTML]
    I --> M[Store HTML]
    J --> N[Shop HTML]

See: Request Flow for detailed journey

Application Areas

Admin Interface (/admin/*)

Purpose: Platform administration

Features:

• Store management
• User management
• System settings
• Audit logs
• Analytics dashboard

Access: Admin users only

Store Dashboard (/store/*)

Purpose: Store shop management

Features:

• Product management
• Inventory tracking
• Order processing
• Shop settings
• Team member management
• Analytics

Access: Store users (owners and team members)

Shop Interface (/shop/* or custom domains)

Purpose: Customer-facing storefront

Features:

• Product browsing
• Shopping cart
• Checkout
• Order tracking
• Customer account

Access: Public + registered customers

API (/api/*)

Purpose: RESTful JSON API for all operations

Features:

• All CRUD operations
• Authentication endpoints
• Data export/import
• Webhook support

Access: Authenticated users based on role

Data Architecture

Database Schema

┌─────────────────┐
│     stores     │ ← Multi-tenant root
└────────┬────────┘
         │
         ├─── store_domains
         ├─── store_themes
         ├─── store_settings
         │
         ├─── products ────┬─── product_variants
         │                 ├─── product_images
         │                 └─── product_categories
         │
         ├─── cart_items (session-based shopping cart)
         │
         ├─── orders ──────┬─── order_items
         │                 └─── order_status_history
         │
         └─── customers ───┬─── customer_addresses
                           └─── customer_sessions

Key Design Patterns

1. Tenant Isolation: All data scoped to store_id
2. Soft Deletes: Records marked as deleted, not removed
3. Audit Trail: All changes tracked with user and timestamp
4. JSON Fields: Flexible metadata storage

Security Architecture

Authentication Flow

1. User submits credentials
2. Server validates against database
3. JWT token generated with user info
4. Token returned to client
5. Client includes token in subsequent requests
6. Server validates token on each request

Authorization Layers

1. Route-level: Middleware checks user authentication
2. Role-level: Decorators enforce role requirements
3. Resource-level: Services check ownership/permissions
4. Tenant-level: All queries scoped to store

See: Authentication & RBAC

Scalability Considerations

Current Architecture

• Single server: Suitable for small to medium deployments
• In-memory rate limiting: Per-process limits
• Session state: Stateless JWT tokens

Future Enhancements

• Horizontal scaling: Load balancer + multiple app servers
• Redis integration: Distributed rate limiting and caching
• Database replication: Read replicas for scaling
• CDN integration: Static asset distribution
• Message queue: Async task processing (Celery + Redis)

Development Workflow

Local Development

# Setup
make install-all
make db-setup

# Development
make dev          # Start FastAPI server
make docs-serve   # Start documentation server

# Testing
make test         # Run all tests
make test-coverage  # Run with coverage report

# Code Quality
make format       # Format code (black + isort)
make lint         # Run linters (ruff + mypy)

Project Structure

project/
├── app/                    # Application code
│   ├── api/               # API routes
│   ├── routes/            # Page routes (HTML)
│   ├── services/          # Business logic
│   ├── core/              # Core functionality (config, db, observability)
│   ├── modules/           # Module definitions and self-contained modules
│   │   ├── base.py       # ModuleDefinition class
│   │   ├── registry.py   # Module registry (CORE, OPTIONAL, INTERNAL)
│   │   ├── service.py    # Module enablement service
│   │   ├── events.py     # Module event bus
│   │   ├── cms/          # Self-contained CMS module
│   │   ├── payments/     # Self-contained payments module
│   │   └── ...           # Other modules
│   └── exceptions/        # Custom exceptions
│
├── middleware/            # Custom middleware
│   ├── auth.py           # Authentication
│   ├── store_context.py # Tenant detection
│   ├── context_middleware.py  # Context detection
│   └── theme_context.py  # Theme loading
│
├── models/               # Data models
│   ├── database/        # SQLAlchemy models
│   └── schema/          # Pydantic schemas
│
├── static/              # Static files
│   ├── admin/          # Admin assets
│   ├── store/         # Store assets
│   └── shop/           # Shop assets
│
├── templates/           # Jinja2 templates
│   ├── admin/
│   ├── store/
│   └── shop/
│
├── tests/              # Test suite
│   ├── unit/
│   └── integration/
│
└── docs/               # Documentation
    ├── architecture/   # System architecture
    ├── frontend/       # Frontend guides
    ├── backend/        # Backend development
    └── api/            # API documentation

Monitoring & Observability

The platform includes a comprehensive observability framework:

Health Checks

• Aggregated health endpoint (/health)
• Kubernetes probes (/health/live, /health/ready)
• Module health check integration
• External tool links (/health/tools)

Metrics

• Prometheus metrics endpoint (/metrics)
• Request latency histograms
• Counter and gauge support

Error Tracking

• Sentry integration for production
• Exception capture with context
• Environment-aware configuration

Logging

• Structured logging with Python logging module
• Request/response logging via middleware
• Error tracking with stack traces
• Audit logging for admin actions

See: Observability for complete documentation

Deployment Architecture

Production Deployment

                    ┌─────────────┐
Internet ───────────│ Load Balancer│
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       ┌────▼────┐    ┌────▼────┐   ┌────▼────┐
       │ App     │    │ App     │   │ App     │
       │ Server 1│    │ Server 2│   │ Server 3│
       └────┬────┘    └────┬────┘   └────┬────┘
            │              │              │
            └──────────────┼──────────────┘
                           │
                    ┌──────▼───────┐
                    │  PostgreSQL  │
                    │  (Primary +  │
                    │   Replicas)  │
                    └──────────────┘

See: Deployment Documentation

Related Documentation

• Multi-Tenant System - Detailed multi-tenancy implementation
• Module System - Module architecture and classification
• Menu Management - Sidebar and menu configuration
• Observability - Health checks, metrics, error tracking
• Middleware Stack - Complete middleware documentation
• Authentication & RBAC - Security and access control
• Request Flow - Detailed request processing
• Frontend Architecture - Frontend development guides
• Backend Development - Backend development guides
• API Documentation - API reference

Quick Links

For Developers

• Creating a New Admin Page
• Backend Development Guide
• Database Migrations

For Operations

• Deployment Guide
• Environment Configuration
• Database Setup

For Team Members

• Contributing Guide
• PyCharm Setup
• Troubleshooting