orion/docs/architecture/tenancy-module-migration.md

# Tenancy Module Migration Plan

This document outlines the complete migration plan for the tenancy module, which manages the multi-tenant organizational hierarchy: platforms, companies, vendors, and users.

## Tenancy Module Domain

The tenancy module owns **identity and organizational hierarchy**:

- **Platforms** - Top-level SaaS instances
- **Companies** - Business entities that own vendors
- **Vendors** - Storefronts/merchant accounts
- **Users** - Admin users, vendor team members
- **Authentication** - Login, tokens, sessions
- **Teams** - Vendor team management
- **Domains** - Custom domain configuration

## Migration Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                         CURRENT STATE                                │
│                                                                      │
│  app/api/v1/admin/     app/api/v1/vendor/     app/services/         │
│  ├── admin_users.py    ├── auth.py            ├── vendor_service    │
│  ├── companies.py      ├── profile.py         ├── company_service   │
│  ├── platforms.py      ├── team.py            ├── platform_service  │
│  ├── vendors.py        └── ...                ├── auth_service      │
│  ├── users.py                                 └── ...               │
│  └── auth.py                                                        │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         TARGET STATE                                 │
│                                                                      │
│  app/modules/tenancy/                                                │
│  ├── routes/api/                                                     │
│  │   ├── admin.py          # All admin tenancy routes               │
│  │   └── vendor.py         # All vendor tenancy routes              │
│  ├── services/                                                       │
│  │   ├── vendor_service.py                                          │
│  │   ├── company_service.py                                         │
│  │   ├── platform_service.py                                        │
│  │   ├── auth_service.py                                            │
│  │   └── team_service.py                                            │
│  ├── models/                                                         │
│  │   ├── vendor.py                                                  │
│  │   ├── company.py                                                 │
│  │   ├── platform.py                                                │
│  │   └── user.py                                                    │
│  └── schemas/                                                        │
│       └── ...                                                        │
└─────────────────────────────────────────────────────────────────────┘
```

## Files to Migrate to Tenancy

### Routes (Admin API)

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `app/api/v1/admin/admin_users.py` | `tenancy/routes/api/admin_users.py` | Admin user CRUD |
| `app/api/v1/admin/companies.py` | `tenancy/routes/api/admin_companies.py` | Company management |
| `app/api/v1/admin/platforms.py` | `tenancy/routes/api/admin_platforms.py` | Platform management |
| `app/api/v1/admin/vendors.py` | `tenancy/routes/api/admin_vendors.py` | Vendor management |
| `app/api/v1/admin/vendor_domains.py` | `tenancy/routes/api/admin_vendor_domains.py` | Domain configuration |
| `app/api/v1/admin/users.py` | `tenancy/routes/api/admin_users.py` | Platform users |
| `app/api/v1/admin/auth.py` | `tenancy/routes/api/admin_auth.py` | Admin authentication |

### Routes (Vendor API)

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `app/api/v1/vendor/auth.py` | `tenancy/routes/api/vendor_auth.py` | Vendor authentication |
| `app/api/v1/vendor/profile.py` | `tenancy/routes/api/vendor_profile.py` | Vendor profile |
| `app/api/v1/vendor/team.py` | `tenancy/routes/api/vendor_team.py` | Team management |

### Services

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `app/services/vendor_service.py` | `tenancy/services/vendor_service.py` | Core vendor operations |
| `app/services/company_service.py` | `tenancy/services/company_service.py` | Company management |
| `app/services/platform_service.py` | `tenancy/services/platform_service.py` | Platform management |
| `app/services/admin_service.py` | `tenancy/services/admin_service.py` | Admin user operations |
| `app/services/admin_platform_service.py` | `tenancy/services/admin_platform_service.py` | Admin-platform relations |
| `app/services/vendor_domain_service.py` | `tenancy/services/vendor_domain_service.py` | Domain management |
| `app/services/vendor_team_service.py` | `tenancy/services/vendor_team_service.py` | Team management |
| `app/services/team_service.py` | `tenancy/services/team_service.py` | Team operations |
| `app/services/auth_service.py` | `tenancy/services/auth_service.py` | Authentication logic |
| `app/services/platform_signup_service.py` | `tenancy/services/platform_signup_service.py` | Platform onboarding |

### Models

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `models/database/vendor.py` | `tenancy/models/vendor.py` | Vendor entity |
| `models/database/company.py` | `tenancy/models/company.py` | Company entity |
| `models/database/platform.py` | `tenancy/models/platform.py` | Platform entity |
| `models/database/admin.py` | `tenancy/models/admin.py` | Admin user entity |
| `models/database/admin_platform.py` | `tenancy/models/admin_platform.py` | Admin-Platform relation |
| `models/database/vendor_domain.py` | `tenancy/models/vendor_domain.py` | Vendor domains |
| `models/database/vendor_platform.py` | `tenancy/models/vendor_platform.py` | Vendor-Platform relation |
| `models/database/user.py` | `tenancy/models/user.py` | User base model |

### Schemas

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `models/schema/vendor.py` | `tenancy/schemas/vendor.py` | Vendor schemas |
| `models/schema/company.py` | `tenancy/schemas/company.py` | Company schemas |
| `models/schema/platform.py` | `tenancy/schemas/platform.py` | Platform schemas |
| `models/schema/admin.py` | `tenancy/schemas/admin.py` | Admin schemas |
| `models/schema/auth.py` | `tenancy/schemas/auth.py` | Auth schemas |

## Files to Keep in ROOT (Framework Level)

These are **framework infrastructure**, not domain logic:

| File | Reason |
|------|--------|
| `app/api/v1/admin/modules.py` | Module system management |
| `app/api/v1/admin/module_config.py` | Module configuration |
| `app/api/v1/admin/menu_config.py` | Menu system |
| `app/api/v1/admin/settings.py` | System settings |
| `models/database/base.py` | SQLAlchemy base |
| `models/database/platform_module.py` | Module enablement |
| `models/database/admin_menu_config.py` | Menu configuration |

## Files to Migrate to OTHER Modules

### → `modules/monitoring/` (or `dev_tools`)

| File | Target Module | Reason |
|------|---------------|--------|
| `admin/background_tasks.py` | monitoring | Task monitoring |
| `admin/code_quality.py` | dev_tools | Dev tools |
| `admin/logs.py` | monitoring | Log viewer |
| `admin/monitoring.py` | monitoring | Monitoring |
| `admin/platform_health.py` | monitoring | Health checks |
| `admin/tests.py` | dev_tools | Test runner |
| `admin/audit.py` | monitoring | Audit logs |

### → `modules/messaging/`

| File | Reason |
|------|--------|
| `admin/messages.py` | Message management |
| `admin/notifications.py` | Notification management |
| `admin/email_templates.py` | Email templates |
| `vendor/messages.py` | Vendor messages |
| `vendor/notifications.py` | Vendor notifications |
| `vendor/email_settings.py` | Email settings |
| `vendor/email_templates.py` | Email templates |

### → `modules/cms/`

| File | Reason |
|------|--------|
| `admin/media.py` | Media library |
| `admin/images.py` | Image management |
| `vendor/media.py` | Vendor media |
| `admin/vendor_themes.py` | Theme management |

### → `modules/core/` (new module)

| File | Reason |
|------|--------|
| `admin/dashboard.py` | Admin dashboard |
| `vendor/dashboard.py` | Vendor dashboard |
| `vendor/settings.py` | Vendor settings |

## Target Module Structure

After migration, tenancy module will have this structure:

```
app/modules/tenancy/
├── __init__.py
├── definition.py
├── exceptions.py
├── config.py                    # Environment configuration
├── routes/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── admin.py             # Aggregates admin sub-routers
│   │   ├── admin_users.py       # Admin user management
│   │   ├── admin_companies.py   # Company management
│   │   ├── admin_platforms.py   # Platform management
│   │   ├── admin_vendors.py     # Vendor management
│   │   ├── admin_vendor_domains.py
│   │   ├── admin_auth.py        # Admin authentication
│   │   ├── vendor.py            # Aggregates vendor sub-routers
│   │   ├── vendor_auth.py       # Vendor authentication
│   │   ├── vendor_profile.py    # Vendor profile
│   │   ├── vendor_team.py       # Team management
│   │   └── vendor_info.py       # Public vendor lookup (DONE)
│   └── pages/
│       ├── __init__.py
│       ├── admin.py             # Admin HTML pages
│       └── vendor.py            # Vendor HTML pages
├── services/
│   ├── __init__.py
│   ├── vendor_service.py
│   ├── company_service.py
│   ├── platform_service.py
│   ├── admin_service.py
│   ├── auth_service.py
│   ├── team_service.py
│   └── vendor_domain_service.py
├── models/
│   ├── __init__.py
│   ├── vendor.py
│   ├── company.py
│   ├── platform.py
│   ├── admin.py
│   ├── user.py
│   ├── vendor_domain.py
│   └── vendor_platform.py
├── schemas/
│   ├── __init__.py
│   ├── vendor.py
│   ├── company.py
│   ├── platform.py
│   ├── admin.py
│   └── auth.py
├── templates/
│   └── tenancy/
│       ├── admin/
│       └── vendor/
├── static/
│   ├── admin/js/
│   └── vendor/js/
└── locales/
    ├── en.json
    ├── de.json
    ├── fr.json
    └── lb.json
```

## Module Ownership Summary

| Module | Owns | Key Principle |
|--------|------|---------------|
| **tenancy** | Vendors, Companies, Platforms, Users, Auth, Teams | Identity & organizational hierarchy |
| **core** | Dashboard, Settings | Foundational non-domain features |
| **messaging** | Messages, Notifications, Email | Communication |
| **cms** | Media, Images, Themes, Content | Content management |
| **monitoring** | Logs, Health, Tasks, Audit | Observability |
| **dev_tools** | Code quality, Tests | Development tools |
| **ROOT** | Module system, Menu config, Base models | Framework infrastructure |

## Migration Order

Recommended order for migrating tenancy:

1. **Phase 1: Services** (no route changes)
   - Move services to `tenancy/services/`
   - Update imports throughout codebase
   - Keep re-exports in `app/services/` temporarily

2. **Phase 2: Models** (careful - many dependencies)
   - Move models to `tenancy/models/`
   - Update all imports
   - May need re-exports in `models/database/`

3. **Phase 3: Schemas**
   - Move schemas to `tenancy/schemas/`
   - Update route imports

4. **Phase 4: Routes**
   - Move routes to `tenancy/routes/api/`
   - Update aggregation in admin/vendor `__init__.py`
   - Delete legacy route files

5. **Phase 5: Cleanup**
   - Remove re-exports
   - Delete empty legacy files
   - Update documentation

## Related Documentation

- [Module System Architecture](module-system.md)
- [Module Auto-Discovery Migration](../development/migration/module-autodiscovery-migration.md)
- [Multi-Tenant Architecture](multi-tenant.md)