Files

Samir Boulahtit d747f9ebaa docs: add tenancy module migration plan and session notes

DOCUMENTATION:
- docs/architecture/tenancy-module-migration.md
  - Complete migration plan for tenancy module
  - Files to migrate: routes, services, models, schemas
  - Files to keep in root (framework level)
  - Files for other modules (messaging, cms, monitoring, core)
  - Target module structure
  - Recommended migration order

- docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md
  - Session summary and key decisions
  - Module ownership assignments
  - Next actions and priorities

Key principle: Tenancy owns identity and organizational hierarchy.
Everything else belongs to feature modules.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-31 14:52:13 +01:00

13 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, 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:

Phase 1: Services (no route changes)
- Move services to tenancy/services/
- Update imports throughout codebase
- Keep re-exports in app/services/ temporarily
Phase 2: Models (careful - many dependencies)
- Move models to tenancy/models/
- Update all imports
- May need re-exports in models/database/
Phase 3: Schemas
- Move schemas to tenancy/schemas/
- Update route imports
Phase 4: Routes
- Move routes to tenancy/routes/api/
- Update aggregation in admin/vendor __init__.py
- Delete legacy route files
Phase 5: Cleanup
- Remove re-exports
- Delete empty legacy files
- Update documentation

13 KiB Raw Blame History