orion/docs/architecture/models-structure.md

Models & Schemas Architecture

Overview

This project uses a module-based architecture for models and schemas:

1. Infrastructure in models/database/ and models/schema/ - Base classes only
2. Module models/schemas in app/modules/<module>/models/ and app/modules/<module>/schemas/ - All domain entities
3. Inline schemas defined directly in API route files - Endpoint-specific request/response models

Directory Structure

models/                              # INFRASTRUCTURE ONLY
├── database/                        # SQLAlchemy base classes
│   ├── __init__.py                  # Exports Base, TimestampMixin only
│   └── base.py                      # Base class, mixins
│
└── schema/                          # Pydantic base classes
    ├── __init__.py                  # Exports base and auth only
    ├── base.py                      # Base schema classes
    └── auth.py                      # Auth schemas (cross-cutting)

app/modules/<module>/                # Domain modules (ALL domain entities)
├── models/                          # Module-specific database models
│   ├── __init__.py                  # Canonical exports
│   └── *.py                         # Model definitions
│
└── schemas/                         # Module-specific schemas
    ├── __init__.py                  # Canonical exports
    └── *.py                         # Schema definitions

---

Architecture Principles

1. Infrastructure vs Module Code

Infrastructure (models/database/, models/schema/) provides base classes only:

• Base - SQLAlchemy declarative base
• TimestampMixin - created_at/updated_at columns
• BaseModel patterns in models/schema/base.py
• auth.py - Authentication schemas (cross-cutting concern)

Module code (app/modules/<module>/) contains all domain-specific entities:

Module	Models	Schemas
tenancy	User, Admin, Store, Merchant, Platform, StoreDomain	merchant, store, admin, team, store_domain
billing	Feature, SubscriptionTier, StoreSubscription	billing, subscription
catalog	Product, ProductTranslation, ProductMedia	catalog, product, store_product
orders	Order, OrderItem, Invoice	order, invoice, order_item_exception
inventory	Inventory, InventoryTransaction	inventory
cms	ContentPage, MediaFile, StoreTheme	content_page, media, image, store_theme
messaging	Email, StoreEmailSettings, StoreEmailTemplate, Message, Notification	email, message, notification
customers	Customer, PasswordResetToken	customer, context
marketplace	5 models	4 schemas
core	AdminMenuConfig	(inline)

2. Schema Patterns

The codebase uses three valid patterns for schemas:

Pattern A: Dedicated Schema Files (Reusable)

For schemas used across multiple endpoints or modules.

# app/modules/inventory/schemas/inventory.py
class InventoryCreate(BaseModel):
    product_id: int
    location: str
    quantity: int

class InventoryResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    product_id: int
    store_id: int
    quantity: int

Pattern B: Inline Schemas (Endpoint-Specific)

For schemas only used by a single endpoint or closely related endpoints.

# app/modules/tenancy/routes/api/admin_platforms.py
class PlatformResponse(BaseModel):
    """Platform response schema - only used in this file."""
    id: int
    code: str
    name: str
    # ...

class PlatformUpdateRequest(BaseModel):
    """Request schema - only used in this file."""
    name: str | None = None
    description: str | None = None

@router.get("/platforms/{code}", response_model=PlatformResponse)
def get_platform(...):
    ...

Pattern C: No Schema (Internal Service Use)

For models only accessed internally by services, not exposed via API.

# Internal association table - no API exposure
class StorePlatform(Base):
    """Links stores to platforms - internal use only."""
    __tablename__ = "store_platforms"
    store_id = Column(Integer, ForeignKey("stores.id"))
    platform_id = Column(Integer, ForeignKey("platforms.id"))

3. When to Use Each Pattern

Scenario	Pattern	Location
Schema used by multiple endpoints	Dedicated file	app/modules/<module>/schemas/
Schema used by single endpoint	Inline	In the route file
Admin-only endpoint schemas	Inline	In the admin route file
Model not exposed via API	No schema	N/A

---

Data Flow Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           API Layer                                  │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐  │
│  │ Request Schema  │───▶│    Endpoint     │───▶│ Response Schema │  │
│  │ (Pydantic)      │    │                 │    │ (Pydantic)      │  │
│  └─────────────────┘    └────────┬────────┘    └─────────────────┘  │
└──────────────────────────────────┼──────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Service Layer                                │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    Business Logic                            │    │
│  │  • Validation      • Transformations    • Business Rules     │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                   │                                  │
│                                   ▼                                  │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              Database Models (SQLAlchemy)                    │    │
│  │  • Direct access   • Queries          • Transactions         │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        Database Layer                                │
│                     PostgreSQL / SQLite                              │
└─────────────────────────────────────────────────────────────────────┘

Key principles:

• Services access database models directly - No schema layer between service and database
• APIs use schemas for validation - Request/response validation at API boundary
• Schemas are API contracts - Define what clients send/receive

---

Import Guidelines

Canonical Imports (Required)

# Infrastructure - base classes only
from models.database import Base, TimestampMixin
from models.schema.auth import LoginRequest, TokenResponse

# Module models - from app.modules.<module>.models
from app.modules.tenancy.models import User, Store, Merchant
from app.modules.billing.models import Feature, SubscriptionTier
from app.modules.catalog.models import Product, ProductMedia
from app.modules.orders.models import Order, OrderItem
from app.modules.cms.models import MediaFile, StoreTheme
from app.modules.messaging.models import Email, StoreEmailTemplate

# Module schemas - from app.modules.<module>.schemas
from app.modules.tenancy.schemas import StoreCreate, MerchantResponse
from app.modules.cms.schemas import MediaItemResponse, StoreThemeResponse
from app.modules.messaging.schemas import EmailTemplateResponse
from app.modules.inventory.schemas import InventoryCreate, InventoryResponse
from app.modules.orders.schemas import OrderResponse

Legacy Imports (DEPRECATED)

The following import patterns are deprecated and will cause architecture validation errors:

# DEPRECATED - Don't import domain models from models.database
from models.database import User, Store  # WRONG

# DEPRECATED - Don't import domain schemas from models.schema
from models.schema.store import StoreCreate  # WRONG
from models.schema.merchant import MerchantResponse  # WRONG

---

Module Ownership Reference

Tenancy Module (app/modules/tenancy/)

Models:

• User - User authentication and profile
• Admin - Admin user management
• Store - Store/merchant entities
• StoreUser - Store team members
• Merchant - Merchant management
• Platform - Multi-platform support
• AdminPlatform - Admin-platform association
• StorePlatform - Store-platform association
• PlatformModule - Module configuration per platform
• StoreDomain - Custom domain configuration

Schemas:

• merchant.py - Merchant CRUD schemas
• store.py - Store CRUD and Letzshop export schemas
• admin.py - Admin user and audit log schemas
• team.py - Team management and invitation schemas
• store_domain.py - Domain configuration schemas

CMS Module (app/modules/cms/)

Models:

• ContentPage - CMS content pages
• MediaFile - File storage and management
• StoreTheme - Theme customization

Schemas:

• content_page.py - Content page schemas
• media.py - Media upload/response schemas
• image.py - Image handling schemas
• store_theme.py - Theme configuration schemas

Messaging Module (app/modules/messaging/)

Models:

• Email - Email records
• StoreEmailSettings - Email configuration
• StoreEmailTemplate - Email templates
• Message - Internal messages
• AdminNotification - Admin notifications

Schemas:

• email.py - Email template schemas
• message.py - Message schemas
• notification.py - Notification schemas

Core Module (app/modules/core/)

Models:

• AdminMenuConfig - Menu visibility configuration

Schemas: (inline in route files)

---

Creating New Models

Database Model Checklist

1. Determine location:

   • All domain models → app/modules/<module>/models/

2. Create the model file:

   # app/modules/mymodule/models/my_entity.py
   from sqlalchemy import Column, Integer, String, ForeignKey
   from sqlalchemy.orm import relationship
   from models.database import Base, TimestampMixin
   
   class MyEntity(Base, TimestampMixin):
       __tablename__ = "my_entities"
   
       id = Column(Integer, primary_key=True, index=True)
       store_id = Column(Integer, ForeignKey("stores.id"), nullable=False)
       name = Column(String(255), nullable=False)
   
       store = relationship("Store")
   

3. Export in __init__.py:

   # app/modules/mymodule/models/__init__.py
   from app.modules.mymodule.models.my_entity import MyEntity
   
   __all__ = ["MyEntity"]
   

Schema Checklist

1. Decide if schema is needed:

   • Exposed via API? → Yes, create schema
   • Multiple endpoints use it? → Dedicated schema file
   • Single endpoint? → Consider inline schema
   • Internal only? → No schema needed

2. Create schema (if needed):

   # app/modules/mymodule/schemas/my_entity.py
   from pydantic import BaseModel, ConfigDict, Field
   
   class MyEntityCreate(BaseModel):
       name: str = Field(..., min_length=1, max_length=255)
   
   class MyEntityResponse(BaseModel):
       model_config = ConfigDict(from_attributes=True)
   
       id: int
       store_id: int
       name: str
   

3. Or use inline schema:

   # app/modules/mymodule/routes/api/store.py
   from pydantic import BaseModel
   
   class MyEntityResponse(BaseModel):
       """Response schema - only used in this file."""
       id: int
       name: str
   
   @router.get("/my-entities/{id}", response_model=MyEntityResponse)
   def get_entity(...):
       ...
   

---

Summary

Principle	Implementation
Services access DB directly	from app.modules.X.models import Model
APIs validate with schemas	Request/response Pydantic models
Reusable schemas	Dedicated files in app/modules/<module>/schemas/
Endpoint-specific schemas	Inline in route files
Internal models	No schema needed
All domain models	app/modules/<module>/models/
Infrastructure only	models/database/ (Base, TimestampMixin only)