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:**
```python
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:**
```python
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

```python
# 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!