smoothschedule/PLAN_APP_REORGANIZATION.md

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

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

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

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:

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:

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