sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a1f71a312614ea6660237308bfbbb27c8d239cd
orion/app/modules/tenancy/docs/migration.md
Samir Boulahtit f141cc4e6a docs: migrate module documentation to single source of truth 
Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 23:38:37 +01:00

244 lines
12 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink