# 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`