# Django App Reorganization Plan - Option C (Domain-Based)

## Overview

Reorganize Django apps from their current scattered locations into a clean domain-based structure within `smoothschedule/smoothschedule/`.

**Branch:** `refactor/organize-django-apps`
**Risk Level:** Medium-High (migration history must be preserved)
**Estimated Parallel Agents:** 6-8

---

## Current State Analysis

### Current App Locations (Inconsistent)

| App | Current Location | Registered As |
|-----|-----------------|---------------|
| core | `smoothschedule/core/` | `"core"` |
| schedule | `smoothschedule/schedule/` | `"schedule"` |
| payments | `smoothschedule/payments/` | `"payments"` |
| platform_admin | `smoothschedule/platform_admin/` | `"platform_admin.apps.PlatformAdminConfig"` |
| analytics | `smoothschedule/analytics/` | `"analytics"` |
| notifications | `smoothschedule/notifications/` | `"notifications"` |
| tickets | `smoothschedule/tickets/` | `"tickets"` |
| contracts | `smoothschedule/contracts/` | **NOT REGISTERED** |
| communication | `smoothschedule/communication/` | **NOT REGISTERED** |
| users | `smoothschedule/smoothschedule/users/` | `"smoothschedule.users"` |
| comms_credits | `smoothschedule/smoothschedule/comms_credits/` | `"smoothschedule.comms_credits"` |
| field_mobile | `smoothschedule/smoothschedule/field_mobile/` | `"smoothschedule.field_mobile"` |
| public_api | `smoothschedule/smoothschedule/public_api/` | `"smoothschedule.public_api"` |

### Migration Counts by App

| App | Migrations | Complexity |
|-----|------------|------------|
| core | 22 | High (Tenant model) |
| schedule | 30 | High (main business logic) |
| payments | 1 | Low |
| platform_admin | 12 | Medium |
| users | 10 | Medium |
| tickets | 13 | Medium |
| contracts | 1 | Low |
| notifications | 1 | Low |
| comms_credits | 2 | Low |
| field_mobile | 1 | Low |
| public_api | 3 | Low |
| analytics | 0 | None |
| communication | 1 | Low |

---

## Target Structure (Option C - Domain-Based)

```
smoothschedule/smoothschedule/
├── __init__.py
│
├── identity/                        # User & Tenant Management
│   ├── __init__.py
│   ├── core/                        # Multi-tenancy, permissions, OAuth
│   │   └── (moved from smoothschedule/core/)
│   └── users/                       # User model, auth, invitations
│       └── (keep at current location, just move parent)
│
├── scheduling/                      # Core Business Logic
│   ├── __init__.py
│   ├── schedule/                    # Resources, Events, Services, Plugins
│   │   └── (moved from smoothschedule/schedule/)
│   ├── contracts/                   # E-signatures, legal documents
│   │   └── (moved from smoothschedule/contracts/)
│   └── analytics/                   # Reporting, dashboards
│       └── (moved from smoothschedule/analytics/)
│
├── communication/                   # Messaging & Notifications
│   ├── __init__.py
│   ├── notifications/               # In-app notifications
│   │   └── (moved from smoothschedule/notifications/)
│   ├── credits/                     # SMS/voice credits (renamed from comms_credits)
│   │   └── (moved from smoothschedule/smoothschedule/comms_credits/)
│   ├── mobile/                      # Field employee app (renamed from field_mobile)
│   │   └── (moved from smoothschedule/smoothschedule/field_mobile/)
│   └── messaging/                   # Twilio conversations (renamed from communication)
│       └── (moved from smoothschedule/communication/)
│
├── commerce/                        # Payments & Support
│   ├── __init__.py
│   ├── payments/                    # Stripe Connect, transactions
│   │   └── (moved from smoothschedule/payments/)
│   └── tickets/                     # Support tickets, email integration
│       └── (moved from smoothschedule/tickets/)
│
└── platform/                        # Platform Administration
    ├── __init__.py
    ├── admin/                       # Platform settings, subscriptions (renamed)
    │   └── (moved from smoothschedule/platform_admin/)
    └── api/                         # Public API v1 (renamed from public_api)
        └── (moved from smoothschedule/smoothschedule/public_api/)
```

---

## Critical Constraints

### 1. Migration History Preservation

Django migrations contain the app label in their `dependencies` and `app_label` references. We MUST:

- **Keep `app_label` unchanged** in each app's `Meta` class
- Update `AppConfig.name` to the new dotted path
- Django will use the `app_label` (not the path) for migration tracking

### 2. Foreign Key String References

Models use string references like `'users.User'` and `'core.Tenant'`. These reference `app_label`, not the module path, so they remain valid.

### 3. Import Path Updates

All imports across the codebase must be updated:
- `from core.models import Tenant` → `from smoothschedule.identity.core.models import Tenant`
- `from schedule.models import Event` → `from smoothschedule.scheduling.schedule.models import Event`

### 4. URL Configuration

`config/urls.py` imports views directly - all import paths must be updated.

### 5. Settings Files

- `config/settings/base.py` - `LOCAL_APPS`
- `config/settings/multitenancy.py` - `SHARED_APPS`, `TENANT_APPS`

---

## Implementation Phases

### Phase 1: Preparation (Serial)

**Agent 1: Setup & Verification**
1. Create all domain package directories with `__init__.py` files
2. Verify Docker is running and database is accessible
3. Run existing tests to establish baseline
4. Create backup of current migration state

```bash
# Create domain packages
mkdir -p smoothschedule/smoothschedule/identity
mkdir -p smoothschedule/smoothschedule/scheduling
mkdir -p smoothschedule/smoothschedule/communication
mkdir -p smoothschedule/smoothschedule/commerce
mkdir -p smoothschedule/smoothschedule/platform

# Create __init__.py files
touch smoothschedule/smoothschedule/identity/__init__.py
touch smoothschedule/smoothschedule/scheduling/__init__.py
touch smoothschedule/smoothschedule/communication/__init__.py
touch smoothschedule/smoothschedule/commerce/__init__.py
touch smoothschedule/smoothschedule/platform/__init__.py
```

---

### Phase 2: Move Apps (Parallel - 5 Agents)

Each agent handles one domain. For each app move:

1. **Move directory** to new location
2. **Update `apps.py`** - change `name` to new dotted path, keep `label` same
3. **Update internal imports** within the app
4. **Add explicit `app_label`** to all model Meta classes (if not present)

#### Agent 2: Identity Domain
Move and update:
- `smoothschedule/core/` → `smoothschedule/smoothschedule/identity/core/`
- `smoothschedule/smoothschedule/users/` → `smoothschedule/smoothschedule/identity/users/`

**apps.py changes:**
```python
# identity/core/apps.py
class CoreConfig(AppConfig):
    name = "smoothschedule.identity.core"  # NEW
    label = "core"  # KEEP SAME
    verbose_name = "Core"

# identity/users/apps.py
class UsersConfig(AppConfig):
    name = "smoothschedule.identity.users"  # NEW
    label = "users"  # KEEP SAME
```

#### Agent 3: Scheduling Domain
Move and update:
- `smoothschedule/schedule/` → `smoothschedule/smoothschedule/scheduling/schedule/`
- `smoothschedule/contracts/` → `smoothschedule/smoothschedule/scheduling/contracts/`
- `smoothschedule/analytics/` → `smoothschedule/smoothschedule/scheduling/analytics/`

#### Agent 4: Communication Domain
Move and update:
- `smoothschedule/notifications/` → `smoothschedule/smoothschedule/communication/notifications/`
- `smoothschedule/smoothschedule/comms_credits/` → `smoothschedule/smoothschedule/communication/credits/`
- `smoothschedule/smoothschedule/field_mobile/` → `smoothschedule/smoothschedule/communication/mobile/`
- `smoothschedule/communication/` → `smoothschedule/smoothschedule/communication/messaging/`

**Note:** Rename apps for clarity:
- `comms_credits` label stays same, path changes
- `field_mobile` label stays same, path changes
- `communication` label stays same, path changes

#### Agent 5: Commerce Domain
Move and update:
- `smoothschedule/payments/` → `smoothschedule/smoothschedule/commerce/payments/`
- `smoothschedule/tickets/` → `smoothschedule/smoothschedule/commerce/tickets/`

#### Agent 6: Platform Domain
Move and update:
- `smoothschedule/platform_admin/` → `smoothschedule/smoothschedule/platform/admin/`
- `smoothschedule/smoothschedule/public_api/` → `smoothschedule/smoothschedule/platform/api/`

---

### Phase 3: Update Settings (Serial)

**Agent 7: Settings Configuration**

Update `config/settings/base.py`:
```python
LOCAL_APPS = [
    # Identity
    "smoothschedule.identity.users",
    "smoothschedule.identity.core",

    # Scheduling
    "smoothschedule.scheduling.schedule",
    "smoothschedule.scheduling.contracts",
    "smoothschedule.scheduling.analytics",

    # Communication
    "smoothschedule.communication.notifications",
    "smoothschedule.communication.credits",
    "smoothschedule.communication.mobile",
    "smoothschedule.communication.messaging",

    # Commerce
    "smoothschedule.commerce.payments",
    "smoothschedule.commerce.tickets",

    # Platform
    "smoothschedule.platform.admin",
    "smoothschedule.platform.api",
]
```

Update `config/settings/multitenancy.py`:
```python
SHARED_APPS = [
    'django_tenants',
    'smoothschedule.identity.core',
    'smoothschedule.platform.admin',
    # ... rest of shared apps with new paths
]

TENANT_APPS = [
    'django.contrib.contenttypes',
    'smoothschedule.scheduling.schedule',
    'smoothschedule.commerce.payments',
    'smoothschedule.scheduling.contracts',
]
```

---

### Phase 4: Update All Import Paths (Parallel - Multiple Agents)

**This is the largest task.** Each agent handles specific import patterns:

#### Agent 8: Core Imports
Find and replace across entire codebase:
- `from core.models import` → `from smoothschedule.identity.core.models import`
- `from core.` → `from smoothschedule.identity.core.`
- `import core` → `import smoothschedule.identity.core as core`

#### Agent 9: Schedule Imports
- `from schedule.models import` → `from smoothschedule.scheduling.schedule.models import`
- `from schedule.` → `from smoothschedule.scheduling.schedule.`

#### Agent 10: Users/Auth Imports
- `from smoothschedule.users.` → `from smoothschedule.identity.users.`
- `from users.` → `from smoothschedule.identity.users.`

#### Agent 11: Other App Imports
Handle remaining apps:
- payments, tickets, notifications, contracts, analytics
- platform_admin, public_api, comms_credits, field_mobile, communication

---

### Phase 5: URL Configuration Updates (Serial)

**Agent 12: URL Updates**

Update `config/urls.py` with new import paths:
```python
# Old
from schedule.views import ResourceViewSet, EventViewSet
from core.api_views import business_current

# New
from smoothschedule.scheduling.schedule.views import ResourceViewSet, EventViewSet
from smoothschedule.identity.core.api_views import business_current
```

---

### Phase 6: Cleanup & Verification (Serial)

**Agent 13: Cleanup**
1. Remove old empty directories at top level
2. Remove deprecated `smoothschedule/smoothschedule/schedule/` directory
3. Update `CLAUDE.md` documentation
4. Update any remaining references

**Agent 14: Verification**
1. Run `docker compose exec django python manage.py check`
2. Run `docker compose exec django python manage.py makemigrations --check`
3. Run `docker compose exec django python manage.py migrate --check`
4. Run test suite
5. Manual smoke test of key endpoints

---

## App Label Mapping Reference

| Old Import Path | New Import Path | app_label (unchanged) |
|----------------|-----------------|----------------------|
| `core` | `smoothschedule.identity.core` | `core` |
| `smoothschedule.users` | `smoothschedule.identity.users` | `users` |
| `schedule` | `smoothschedule.scheduling.schedule` | `schedule` |
| `contracts` | `smoothschedule.scheduling.contracts` | `contracts` |
| `analytics` | `smoothschedule.scheduling.analytics` | `analytics` |
| `notifications` | `smoothschedule.communication.notifications` | `notifications` |
| `smoothschedule.comms_credits` | `smoothschedule.communication.credits` | `comms_credits` |
| `smoothschedule.field_mobile` | `smoothschedule.communication.mobile` | `field_mobile` |
| `communication` | `smoothschedule.communication.messaging` | `communication` |
| `payments` | `smoothschedule.commerce.payments` | `payments` |
| `tickets` | `smoothschedule.commerce.tickets` | `tickets` |
| `platform_admin` | `smoothschedule.platform.admin` | `platform_admin` |
| `smoothschedule.public_api` | `smoothschedule.platform.api` | `public_api` |

---

## Rollback Plan

If issues are encountered:

1. **Git Reset:** `git checkout main` and delete branch
2. **Database:** No migration changes, database remains intact
3. **Docker:** Rebuild containers if needed

---

## Success Criteria

- [ ] All apps moved to domain-based structure
- [ ] `python manage.py check` passes
- [ ] `python manage.py makemigrations --check` shows no changes
- [ ] All existing tests pass
- [ ] Frontend can communicate with API
- [ ] Mobile app can communicate with API
- [ ] CLAUDE.md updated with new structure

---

## Execution Order

```
Phase 1 (Serial):     Agent 1 - Setup
Phase 2 (Parallel):   Agents 2-6 - Move apps by domain
Phase 3 (Serial):     Agent 7 - Update settings
Phase 4 (Parallel):   Agents 8-11 - Update imports
Phase 5 (Serial):     Agent 12 - URL updates
Phase 6 (Serial):     Agents 13-14 - Cleanup & verify
```

**Total Agents:** 14 (8 can run in parallel at peak)