# 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/validate_architecture.py`