Samir Boulahtit
f141cc4e6a
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
11 KiB
11 KiB
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.
Current State
- 20 modules each have
docs/index.md(overview page) - Only
prospectinghas 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
- Move the file into
app/modules/{name}/docs/with a clear name - Update the symlink-based
docs/modules/{name}/nav inmkdocs.yml - Leave a redirect stub in the original location (one-line with a link to the new path) so existing bookmarks still work
- Update cross-references in other docs that link to the moved file
- Run
mkdocs build --strictafter 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
- Remove empty redirect stubs that are older than one release cycle
- Verify all
mkdocs.ymlnav entries point to valid files - Run
mkdocs build --strict— zero warnings - Update
docs/development/module-documentation.mdif conventions evolved - 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 --strictafter each phase - Update the
mkdocs.ymlModules 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/