# Tenancy Module Migration Plan

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

## Tenancy Module Domain

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

- **Platforms** - Top-level SaaS instances
- **Merchants** - Business entities that own stores
- **Stores** - Storefronts/merchant accounts
- **Users** - Admin users, store team members
- **Authentication** - Login, tokens, sessions
- **Teams** - Store team management
- **Domains** - Custom domain configuration

## Migration Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                         CURRENT STATE                                │
│                                                                      │
│  app/api/v1/admin/     app/api/v1/store/     app/services/         │
│  ├── admin_users.py    ├── auth.py            ├── store_service    │
│  ├── merchants.py      ├── profile.py         ├── merchant_service   │
│  ├── platforms.py      ├── team.py            ├── platform_service  │
│  ├── stores.py        └── ...                ├── auth_service      │
│  ├── users.py                                 └── ...               │
│  └── auth.py                                                        │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         TARGET STATE                                 │
│                                                                      │
│  app/modules/tenancy/                                                │
│  ├── routes/api/                                                     │
│  │   ├── admin.py          # All admin tenancy routes               │
│  │   └── store.py         # All store tenancy routes              │
│  ├── services/                                                       │
│  │   ├── store_service.py                                          │
│  │   ├── merchant_service.py                                         │
│  │   ├── platform_service.py                                        │
│  │   ├── auth_service.py                                            │
│  │   └── team_service.py                                            │
│  ├── models/                                                         │
│  │   ├── store.py                                                  │
│  │   ├── merchant.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/merchants.py` | `tenancy/routes/api/admin_merchants.py` | Merchant management |
| `app/api/v1/admin/platforms.py` | `tenancy/routes/api/admin_platforms.py` | Platform management |
| `app/api/v1/admin/stores.py` | `tenancy/routes/api/admin_stores.py` | Store management |
| `app/api/v1/admin/store_domains.py` | `tenancy/routes/api/admin_store_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 (Store API)

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `app/api/v1/store/auth.py` | `tenancy/routes/api/store_auth.py` | Store authentication |
| `app/api/v1/store/profile.py` | `tenancy/routes/api/store_profile.py` | Store profile |
| `app/api/v1/store/team.py` | `tenancy/routes/api/store_team.py` | Team management |

### Services

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `app/services/store_service.py` | `tenancy/services/store_service.py` | Core store operations |
| `app/services/merchant_service.py` | `tenancy/services/merchant_service.py` | Merchant 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/store_domain_service.py` | `tenancy/services/store_domain_service.py` | Domain management |
| `app/services/store_team_service.py` | `tenancy/services/store_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/store.py` | `tenancy/models/store.py` | Store entity |
| `models/database/merchant.py` | `tenancy/models/merchant.py` | Merchant 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/store_domain.py` | `tenancy/models/store_domain.py` | Store domains |
| `models/database/store_platform.py` | `tenancy/models/store_platform.py` | Store-Platform relation |
| `models/database/user.py` | `tenancy/models/user.py` | User base model |

### Schemas

| Current Location | Target Location | Description |
|-----------------|-----------------|-------------|
| `models/schema/store.py` | `tenancy/schemas/store.py` | Store schemas |
| `models/schema/merchant.py` | `tenancy/schemas/merchant.py` | Merchant 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 |

## 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_merchants.py   # Merchant management
│   │   ├── admin_platforms.py   # Platform management
│   │   ├── admin_stores.py     # Store management
│   │   ├── admin_store_domains.py
│   │   ├── admin_auth.py        # Admin authentication
│   │   ├── store.py            # Aggregates store sub-routers
│   │   ├── store_auth.py       # Store authentication
│   │   ├── store_profile.py    # Store profile
│   │   ├── store_team.py       # Team management
│   │   └── store_info.py       # Public store lookup (DONE)
│   └── pages/
│       ├── __init__.py
│       ├── admin.py             # Admin HTML pages
│       └── store.py            # Store HTML pages
├── services/
│   ├── __init__.py
│   ├── store_service.py
│   ├── merchant_service.py
│   ├── platform_service.py
│   ├── admin_service.py
│   ├── auth_service.py
│   ├── team_service.py
│   └── store_domain_service.py
├── models/
│   ├── __init__.py
│   ├── store.py
│   ├── merchant.py
│   ├── platform.py
│   ├── admin.py
│   ├── user.py
│   ├── store_domain.py
│   └── store_platform.py
├── schemas/
│   ├── __init__.py
│   ├── store.py
│   ├── merchant.py
│   ├── platform.py
│   ├── admin.py
│   └── auth.py
├── templates/
│   └── tenancy/
│       ├── admin/
│       └── store/
├── static/
│   ├── admin/js/
│   └── store/js/
└── locales/
    ├── en.json
    ├── de.json
    ├── fr.json
    └── lb.json
```

## Module Ownership Summary

| Module | Owns | Key Principle |
|--------|------|---------------|
| **tenancy** | Stores, Merchants, 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/store `__init__.py`
   - Delete legacy route files

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

## Related Documentation

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