orion/models_restructure.md

Models Restructure Plan

New Structure

models/
├── database/
│   ├── __init__.py           # Import all models for easy access
│   ├── base.py              # Base model class and mixins
│   ├── user.py              # User model
│   ├── shop.py              # Shop, ShopProduct models
│   ├── product.py           # Product model
│   ├── stock.py             # Stock model
│   └── marketplace.py       # MarketplaceImportJob model
└── api/
    ├── __init__.py          # Common imports
    ├── base.py              # Base response models
    ├── auth.py              # User auth models (register, login, response)
    ├── shop.py              # Shop management models
    ├── product.py           # Product CRUD models
    ├── stock.py             # Stock operation models
    ├── marketplace.py       # Marketplace import models
    └── stats.py             # Statistics response models

File Contents Breakdown

Database Models

models/database/base.py:

from datetime import datetime
from sqlalchemy import Column, DateTime
from app.core.database import Base

class TimestampMixin:
    """Mixin to add created_at and updated_at timestamps to models"""
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    updated_at = Column(
        DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False
    )

models/database/user.py:

• User model (lines 12-37 from your current file)

models/database/shop.py:

• Shop model (lines 40-75)
• ShopProduct model (lines 155-199)

models/database/product.py:

• Product model (lines 78-152)

models/database/stock.py:

• Stock model (lines 202-232)

models/database/marketplace.py:

• MarketplaceImportJob model (lines 235-284)

API Models

models/api/base.py:

from typing import List, TypeVar, Generic
from pydantic import BaseModel

T = TypeVar('T')

class ListResponse(BaseModel, Generic[T]):
    """Generic list response model"""
    items: List[T]
    total: int
    skip: int
    limit: int

class StatusResponse(BaseModel):
    """Generic status response"""
    success: bool
    message: str

models/api/auth.py:

• UserRegister (lines 12-34)
• UserLogin (lines 37-46)
• UserResponse (lines 49-61)
• LoginResponse (lines 64-69)

models/api/shop.py:

• ShopCreate (lines 72-103)
• ShopUpdate (lines 106-122)
• ShopResponse (lines 125-145)
• ShopListResponse (lines 148-153)
• ShopProductCreate (lines 247-270)
• ShopProductResponse (lines 273-293)

models/api/product.py:

• ProductBase (lines 156-193)
• ProductCreate (lines 196-206)
• ProductUpdate (lines 209-211)
• ProductResponse (lines 214-221)
• ProductListResponse (lines 408-413)
• ProductDetailResponse (lines 416-420)

models/api/stock.py:

• StockBase (lines 296-300)
• StockCreate (lines 303-305)
• StockAdd (lines 308-310)
• StockUpdate (lines 313-315)
• StockResponse (lines 318-327)
• StockLocationResponse (lines 330-333)
• StockSummaryResponse (lines 336-342)

models/api/marketplace.py:

• MarketplaceImportRequest (lines 345-381)
• MarketplaceImportJobResponse (lines 384-399)

models/api/stats.py:

• StatsResponse (lines 423-431)
• MarketplaceStatsResponse (lines 434-439)

Migration Steps

Step 1: Create the new structure

1. Create the new directories
2. Create __init__.py files
3. Move the base classes first

Step 2: Database models migration

1. Extract models one by one, starting with User
2. Update imports in each file
3. Test database connections after each model

Step 3: API models migration

1. Extract API models by domain
2. Update imports in route files
3. Test API endpoints after each model group

Step 4: Update imports across the application

• Update all route files to use new import paths
• Update service files
• Update test files

Benefits of This Structure

1. Domain separation: Related models are grouped together
2. Easier maintenance: Smaller files are easier to navigate and modify
3. Reduced conflicts: Multiple developers can work on different domains
4. Better testability: Can test model groups independently
5. Clear dependencies: Import relationships become more explicit

Import Examples After Restructure

# In route files
from models.database.user import User, Product, Stock
from models.api.auth import UserLogin, UserResponse
from models.api.product import ProductCreate, ProductListResponse

# Or specific imports
from models.database.product import Product
from models.api.product import ProductCreate, ProductResponse

Consideration for Relationships

When splitting database models, be careful with SQLAlchemy relationships:

• Keep related models in the same file if they have tight coupling
• Use string references for relationships across files: relationship("User") instead of relationship(User)
• Consider lazy imports in __init__.py files to avoid circular imports

This restructure will make your codebase much more maintainable as it grows!