sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
95f0eac0793dbcc1e718b14f99efa7370ef42f71
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

12 KiB
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

Reference in New Issue View Git Blame Copy Permalink