# Module Documentation Migration Plan

Migrate ~18,000 lines of module-specific documentation from top-level `docs/` into each module's `docs/` folder (source of truth), following the standard defined in [Module Documentation](../development/module-documentation.md).

## Current State

- 20 modules each have `docs/index.md` (overview page)
- Only `prospecting` has additional docs (`database.md`, `scoring.md`, `research-findings.md`)
- ~38 files across `docs/` are specific to a single module's internals but live in top-level directories
- 2 files are empty stubs (`product-management.md`, `csv-import.md`)

## Migration Rules

1. **Move** the file into `app/modules/{name}/docs/` with a clear name
2. **Update** the symlink-based `docs/modules/{name}/` nav in `mkdocs.yml`
3. **Leave a redirect stub** in the original location (one-line with a link to the new path) so existing bookmarks still work
4. **Update cross-references** in other docs that link to the moved file
5. **Run `mkdocs build --strict`** after each phase to catch broken links

## Phase 1 — Tenancy (largest module, 12 models, 19 API routes)

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/architecture/tenancy-module-migration.md` (286 lines) | `app/modules/tenancy/docs/migration.md` | Migration plan & entity breakdown |
| `docs/backend/store-rbac.md` (844 lines) | `app/modules/tenancy/docs/rbac.md` | Store RBAC system |
| `docs/guides/user-management.md` (377 lines) | `app/modules/tenancy/docs/user-management.md` | User & team management guide |
| `docs/features/store-onboarding.md` (191 lines) | `app/modules/tenancy/docs/onboarding.md` | Store onboarding wizard |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/tenancy/docs/data-model.md` | Entity diagram: Platform → Merchant → Store → AdminUser, domains, email verification |

**Expected result:** 6 docs in `app/modules/tenancy/docs/` (index + 5)

---

## Phase 2 — Billing (subscriptions, tiers, Stripe, scheduled tasks)

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/features/subscription-billing.md` (631 lines) | `app/modules/billing/docs/subscription-system.md` | Subscription architecture |
| `docs/guides/subscription-tier-management.md` (135 lines) | `app/modules/billing/docs/tier-management.md` | Tier management guide |
| `docs/implementation/subscription-workflow-plan.md` (454 lines) | `app/modules/billing/docs/subscription-workflow.md` | Subscription lifecycle |
| `docs/implementation/feature-gating-system.md` (434 lines) | `app/modules/billing/docs/feature-gating.md` | Feature provider pattern |
| `docs/deployment/stripe-integration.md` (617 lines) | `app/modules/billing/docs/stripe-integration.md` | Stripe setup & webhooks |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/billing/docs/data-model.md` | Schema: Subscription, MerchantSubscription, TierFeatureLimit |

**Expected result:** 7 docs in `app/modules/billing/docs/` (index + 6)

---

## Phase 3 — Loyalty (anti-fraud, wallet integration, scoring)

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/features/user-journeys/loyalty.md` (794 lines) | `app/modules/loyalty/docs/user-journeys.md` | User journey flows |
| `docs/proposals/loyalty-program-analysis.md` (387 lines) | `app/modules/loyalty/docs/program-analysis.md` | Business analysis |
| `docs/proposals/loyalty-phase2-interfaces-plan.md` (670 lines) | `app/modules/loyalty/docs/ui-design.md` | Admin/store interface design |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/loyalty/docs/data-model.md` | Schema: LoyaltyProgram, LoyaltyCard, LoyaltyTransaction, StaffPin, AppleDeviceRegistration |
| `app/modules/loyalty/docs/business-logic.md` | Anti-fraud system, cooldown, daily limits, lockout, wallet sync |

**Expected result:** 6 docs in `app/modules/loyalty/docs/` (index + 5)

---

## Phase 4 — Marketplace (Letzshop sync, import jobs)

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/architecture/marketplace-integration.md` (1345 lines) | `app/modules/marketplace/docs/architecture.md` | Integration architecture |
| `docs/guides/marketplace-integration.md` (808 lines) | `app/modules/marketplace/docs/integration-guide.md` | User guide |
| `docs/guides/letzshop-marketplace-api.md` (322 lines) | `app/modules/marketplace/docs/api.md` | Letzshop API reference |
| `docs/guides/letzshop-order-integration.md` (839 lines) | `app/modules/marketplace/docs/order-integration.md` | Order import/sync |
| `docs/guides/letzshop-admin-management.md` (261 lines) | `app/modules/marketplace/docs/admin-guide.md` | Admin portal guide |
| `docs/implementation/letzshop-order-import-improvements.md` (601 lines) | `app/modules/marketplace/docs/import-improvements.md` | GraphQL & field mapping |
| `docs/implementation/letzshop-jobs-improvements.md` (716 lines) | `app/modules/marketplace/docs/job-queue.md` | Job queue improvements |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/marketplace/docs/data-model.md` | Schema: Letzshop, MarketplaceProduct, MarketplaceProductTranslation, MarketplaceImportJob |

**Expected result:** 9 docs in `app/modules/marketplace/docs/` (index + 8)

---

## Phase 5 — Orders (lifecycle, fulfillment, invoicing)

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/architecture/customer-orders-architecture.md` (345 lines) | `app/modules/orders/docs/architecture.md` | Customer-orders architecture |
| `docs/implementation/unified-order-view.md` (275 lines) | `app/modules/orders/docs/unified-order-view.md` | Unified order schema |
| `docs/implementation/order-item-exceptions.md` (288 lines) | `app/modules/orders/docs/exceptions.md` | Order item exception system |
| `docs/implementation/oms-feature-plan.md` (662 lines) | `app/modules/orders/docs/oms-features.md` | OMS feature plan |
| `docs/implementation/vat-invoice-feature.md` (734 lines) | `app/modules/orders/docs/vat-invoicing.md` | VAT invoice specification |
| `docs/implementation/stock-management-integration.md` (371 lines) | `app/modules/orders/docs/stock-integration.md` | Order-inventory integration |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/orders/docs/data-model.md` | Schema: Order, Invoice, OrderItemException |

**Expected result:** 8 docs in `app/modules/orders/docs/` (index + 7)

---

## Phase 6 — Messaging & CMS (email system spans both)

The email system touches both modules. Migration decision:

| Topic | Module | Rationale |
|-------|--------|-----------|
| Email templates (content, rendering) | **cms** | Templates are content, managed via CMS admin |
| Email delivery (providers, sending) | **messaging** | Provider config, SMTP, delivery tracking |
| Email settings (provider config) | **messaging** | Provider selection, credentials, test sending |
| Notifications (admin alerts) | **messaging** | Part of notification center |

### Messaging

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/implementation/messaging-system.md` (243 lines) | `app/modules/messaging/docs/architecture.md` | Messaging architecture |
| `docs/implementation/admin-notification-system.md` (187 lines) | `app/modules/messaging/docs/notifications.md` | Notification system |
| `docs/features/email-system.md` (331 lines) | `app/modules/messaging/docs/email-system.md` | Email delivery system |
| `docs/guides/email-settings.md` (254 lines) | `app/modules/messaging/docs/email-settings.md` | Provider configuration |
| `docs/implementation/email-settings.md` (exists) | `app/modules/messaging/docs/email-settings-impl.md` | Email settings implementation |

**Expected result:** 6 docs in `app/modules/messaging/docs/` (index + 5)

### CMS

**Files to migrate:**

| Source | Target | New Name |
|--------|--------|----------|
| `docs/features/content-management-system.md` (604 lines) | `app/modules/cms/docs/architecture.md` | CMS architecture |
| `docs/features/cms-implementation-guide.md` (414 lines) | `app/modules/cms/docs/implementation.md` | Implementation checklist |
| `docs/implementation/email-templates-architecture.md` (458 lines) | `app/modules/cms/docs/email-templates.md` | Email template system |
| `docs/guides/email-templates.md` (287 lines) | `app/modules/cms/docs/email-templates-guide.md` | Template customisation guide |
| `docs/guides/media-library.md` (182 lines) | `app/modules/cms/docs/media-library.md` | Media library guide |

**New files to create:**

| File | Content |
|------|---------|
| `app/modules/cms/docs/data-model.md` | Schema: ContentPage, Media, StoreTheme |

**Expected result:** 7 docs in `app/modules/cms/docs/` (index + 6)

---

## Phase 7 — Medium modules (catalog, inventory, hosting, prospecting)

### Catalog

| Source | Target |
|--------|--------|
| `docs/architecture/product-architecture.md` (291 lines) | `app/modules/catalog/docs/architecture.md` |
| `docs/guides/product-management.md` (empty) | Delete |
| `docs/guides/csv-import.md` (empty) | Delete |

Create: `app/modules/catalog/docs/data-model.md`

### Inventory

| Source | Target |
|--------|--------|
| `docs/guides/inventory-management.md` (366 lines) | `app/modules/inventory/docs/user-guide.md` |

Create: `app/modules/inventory/docs/data-model.md`

### Hosting

| Source | Target |
|--------|--------|
| `docs/features/user-journeys/hosting.md` (502 lines) | `app/modules/hosting/docs/user-journeys.md` |

### Prospecting

| Source | Target |
|--------|--------|
| `docs/features/user-journeys/prospecting.md` (435 lines) | `app/modules/prospecting/docs/user-journeys.md` |

---

## Phase 8 — Cleanup & verification

1. Remove empty redirect stubs that are older than one release cycle
2. Verify all `mkdocs.yml` nav entries point to valid files
3. Run `mkdocs build --strict` — zero warnings
4. Update `docs/development/module-documentation.md` if conventions evolved
5. Audit: every complex module should have at least `index.md` + `data-model.md`

---

## Summary

| Phase | Module(s) | Files Migrated | Files Created | Total Lines |
|-------|-----------|---------------|---------------|-------------|
| 1 | Tenancy | 4 | 1 | ~1,698 |
| 2 | Billing | 5 | 1 | ~2,271 |
| 3 | Loyalty | 3 | 2 | ~1,851 |
| 4 | Marketplace | 7 | 1 | ~4,892 |
| 5 | Orders | 6 | 1 | ~2,675 |
| 6 | Messaging + CMS | 10 | 1 | ~2,960 |
| 7 | Catalog + Inventory + Hosting + Prospecting | 3 + 2 delete | 2 | ~1,594 |
| 8 | Cleanup | — | — | — |
| **Total** | **10 modules** | **38 migrated** | **9 created** | **~17,941** |

## Execution Notes

- Each phase is independent and can be done in a single session
- Always run `mkdocs build --strict` after each phase
- Update the `mkdocs.yml` Modules nav section to include new docs
- Leave redirect stubs so external links don't break immediately
- Cross-references between modules should use relative paths from `docs/modules/`