From d747f9ebaa2be686f3a6fcdc553f4c9a5e44770e Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sat, 31 Jan 2026 14:52:13 +0100 Subject: [PATCH] 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 --- docs/architecture/tenancy-module-migration.md | 286 ++++++++++++++++++ ...2026-01-31_tenancy-module-consolidation.md | 145 +++++++++ 2 files changed, 431 insertions(+) create mode 100644 docs/architecture/tenancy-module-migration.md create mode 100644 docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md diff --git a/docs/architecture/tenancy-module-migration.md b/docs/architecture/tenancy-module-migration.md new file mode 100644 index 00000000..6180bf55 --- /dev/null +++ b/docs/architecture/tenancy-module-migration.md @@ -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) diff --git a/docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md b/docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md new file mode 100644 index 00000000..53537510 --- /dev/null +++ b/docs/proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md @@ -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`