orion/docs/archive/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md

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)
• Merchants (business entities)
• Stores (merchant accounts)
• Users (admin users, team members)
• Authentication (login, tokens, sessions)
• Teams (store team management)
• Domains (custom domain configuration)

2. Completed Migrations (This Session)

• Migrated app/api/v1/store/info.py → tenancy/routes/api/store.py
• Changed path from /{store_code} to /info/{store_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
- merchants.py      → tenancy/routes/api/admin_merchants.py
- platforms.py      → tenancy/routes/api/admin_platforms.py
- stores.py        → tenancy/routes/api/admin_stores.py
- store_domains.py → tenancy/routes/api/admin_store_domains.py
- users.py          → tenancy/routes/api/admin_users.py
- auth.py           → tenancy/routes/api/admin_auth.py

Store API:
- auth.py           → tenancy/routes/api/store_auth.py
- profile.py        → tenancy/routes/api/store_profile.py
- team.py           → tenancy/routes/api/store_team.py

Services to Migrate

- store_service.py
- merchant_service.py
- platform_service.py
- admin_service.py
- admin_platform_service.py
- store_domain_service.py
- store_team_service.py
- team_service.py
- auth_service.py
- platform_signup_service.py

Models to Migrate

- store.py
- merchant.py
- platform.py
- admin.py
- admin_platform.py
- store_domain.py
- store_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, store_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 store auth routes to tenancy
2. Migrate admin auth routes to tenancy
3. Migrate store profile and team routes

Short-term

4. Migrate merchant/store/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 store 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