sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add tenancy module migration plan and session notes

Browse Source 
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>
This commit is contained in:
Samir Boulahtit
2026-01-31 14:52:13 +01:00
parent 23d59492b7
commit d747f9ebaa
2 changed files with 431 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
docs/architecture/tenancy-module-migration.md Normal file
View File

@@ -0,0 +1,286 @@
# 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)

145
docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md Normal file
View File

@@ -0,0 +1,145 @@
# Session Note: Tenancy Module Consolidation Plan
**Date:** 2026-01-31
**Topic:** Complete migration plan for tenancy module and remaining legacy code
## Summary
This session established a comprehensive plan for migrating all identity and organizational management code to the tenancy module, plus identified where other legacy code should go.
## Key Decisions
### 1. Tenancy Module Scope
The tenancy module owns **identity and organizational hierarchy**:
- Platforms (top-level SaaS instances)
- Companies (business entities)
- Vendors (merchant accounts)
- Users (admin users, team members)
- Authentication (login, tokens, sessions)
- Teams (vendor team management)
- Domains (custom domain configuration)
### 2. Completed Migrations (This Session)
- Migrated `app/api/v1/vendor/info.py` → `tenancy/routes/api/vendor.py`
- Changed path from `/{vendor_code}` to `/info/{vendor_code}` (removes catch-all)
- Set up tenancy module as `is_self_contained=True`
- Updated frontend JS to use new endpoint path
### 3. Files Identified for Tenancy Migration
#### Routes to Migrate
```
Admin API:
- admin_users.py → tenancy/routes/api/admin_users.py
- companies.py → tenancy/routes/api/admin_companies.py
- platforms.py → tenancy/routes/api/admin_platforms.py
- vendors.py → tenancy/routes/api/admin_vendors.py
- vendor_domains.py → tenancy/routes/api/admin_vendor_domains.py
- users.py → tenancy/routes/api/admin_users.py
- auth.py → tenancy/routes/api/admin_auth.py
Vendor API:
- auth.py → tenancy/routes/api/vendor_auth.py
- profile.py → tenancy/routes/api/vendor_profile.py
- team.py → tenancy/routes/api/vendor_team.py
```
#### Services to Migrate
```
- vendor_service.py
- company_service.py
- platform_service.py
- admin_service.py
- admin_platform_service.py
- vendor_domain_service.py
- vendor_team_service.py
- team_service.py
- auth_service.py
- platform_signup_service.py
```
#### Models to Migrate
```
- vendor.py
- company.py
- platform.py
- admin.py
- admin_platform.py
- vendor_domain.py
- vendor_platform.py
- user.py
```
### 4. Other Module Assignments
| Module | Files to Receive |
|--------|-----------------|
| **monitoring** | background_tasks, logs, monitoring, platform_health, audit |
| **dev_tools** | code_quality, tests |
| **messaging** | messages, notifications, email_templates, email_settings |
| **cms** | media, images, vendor_themes |
| **core** (new) | dashboard, settings |
### 5. Framework-Level (Stay in ROOT)
- Module system (`modules.py`, `module_config.py`)
- Menu configuration (`menu_config.py`)
- System settings (`settings.py`)
- Base models (`base.py`, `platform_module.py`, `admin_menu_config.py`)
## Architecture Validation Updates
Added new rules to enforce module-first architecture:
- **MOD-016**: Routes must be in modules, not `app/api/v1/`
- **MOD-017**: Services must be in modules, not `app/services/`
- **MOD-018**: Tasks must be in modules, not `app/tasks/`
- **MOD-019**: Schemas must be in modules, not `models/schema/`
## Documentation Created
1. `docs/architecture/tenancy-module-migration.md` - Full migration plan
2. `docs/development/migration/module-autodiscovery-migration.md` - Migration history
3. Updated `docs/architecture/module-system.md` - Entity auto-discovery reference
## Next Actions
### Immediate (High Priority)
1. Migrate vendor auth routes to tenancy
2. Migrate admin auth routes to tenancy
3. Migrate vendor profile and team routes
### Short-term
4. Migrate company/vendor/platform admin routes
5. Move services to tenancy module
6. Create re-exports for backwards compatibility
### Medium-term
7. Migrate models to tenancy (careful - many dependencies)
8. Migrate schemas
9. Move messaging routes to messaging module
10. Move media routes to cms module
### Long-term
11. Create core module for dashboard/settings
12. Remove all re-exports once migration complete
13. Archive legacy directories
## Commits This Session
1. `401db56` - refactor: migrate remaining routes to modules and enforce auto-discovery
2. `23d5949` - refactor: move vendor info endpoint to tenancy module
## Key Principle
> **Tenancy owns identity and organizational hierarchy.**
> Everything else belongs to feature modules.
## Related Files
- `/docs/architecture/tenancy-module-migration.md`
- `/docs/architecture/module-system.md`
- `/docs/development/migration/module-autodiscovery-migration.md`
- `/.architecture-rules/module.yaml`
- `/scripts/validate_architecture.py`