orion/docs/proposals/PLAN_documentation-consolidation.md

Documentation Consolidation Plan

Overview

Many working documents (session notes, migration plans, proposals) now represent implemented features. This plan consolidates them into proper platform documentation.

Document Categories

1. Implemented → Merge into Architecture/Feature Docs

These documents describe features that are now implemented and should be merged into proper documentation.

Working Document	Target Location	Action
proposals/SESSION_NOTE_2026-01-25_modular-platform-architecture.md	architecture/module-system.md	Merge relevant content, archive original
proposals/SESSION_NOTE_2026-01-26_self-contained-modules.md	architecture/module-system.md	Merge relevant content, archive original
proposals/SESSION_NOTE_2026-01-27_module-reclassification.md	architecture/module-system.md	Merge relevant content, archive original
proposals/SESSION_NOTE_2026-01-28_module-config-migrations.md	architecture/module-system.md	Merge relevant content, archive original
proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md	architecture/module-system.md	Merge relevant content, archive original
proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md	architecture/tenancy-module-migration.md	Merge, archive original
proposals/multi-platform-cms-architecture.md	features/content-management-system.md	Merge as "How CMS Works" section
proposals/multi-platform-cms-architecture-implementation-plan.md	Archive	Implementation complete
proposals/section-based-homepage-plan.md	features/platform-homepage.md	Merge as technical details
proposals/module-migration-plan.md	Archive	Migration complete
migration/language-i18n-implementation.md	architecture/language-i18n.md	Merge (may already exist)
migration/multi-marketplace-product-architecture.md	architecture/marketplace-integration.md	Merge product sync details
migration/vendor-operations-expansion.md	architecture/company-vendor-management.md	Merge operations info
migration/vendor-contact-inheritance.md	architecture/company-vendor-management.md	Merge contact inheritance
migration/product-migration-database-changes.md	Archive	Migration complete
migration/makefile-refactoring-complete.md	Archive	Refactoring complete
migration/tailwind-migration-plan.md	Archive or development/tailwind-css.md	Verify if complete

2. Keep as Development Guides

These should remain as development reference but may need cleanup.

Document	Location	Action
migration/database-migrations.md	Keep	Update if needed
migration/module-autodiscovery-migration.md	Keep	Already updated, serves as history
migration/svc-006-migration-plan.md	development/coding-standards.md	Merge db.commit pattern

3. Future/Unimplemented → Keep in Proposals

Document	Status	Action
proposals/loyalty-program-analysis.md	Future feature	Keep as proposal
proposals/loyalty-phase2-interfaces-plan.md	Future feature	Keep as proposal
proposals/PLAN_storefront-module-restructure.md	Evaluate status	Keep or archive
proposals/humble-orbiting-otter.md	Claude plan file	Archive

Target Documentation Structure

After consolidation, the docs should have:

docs/
├── architecture/
│   ├── module-system.md          ← Comprehensive module docs (merged SESSION_NOTEs)
│   ├── multi-tenant.md           ← Platform/Company/Vendor architecture
│   ├── language-i18n.md          ← i18n implementation
│   ├── marketplace-integration.md ← Letzshop sync, product architecture
│   ├── company-vendor-management.md ← Vendor operations, contact inheritance
│   └── ...
├── features/
│   ├── content-management-system.md ← CMS with multi-platform details
│   ├── platform-homepage.md         ← Section-based homepage
│   ├── subscription-billing.md      ← Billing features
│   └── ...
├── development/
│   ├── creating-modules.md       ← How to create new modules
│   ├── coding-standards.md       ← db.commit pattern, etc.
│   ├── database-migrations.md    ← Migration guide
│   └── migration/                ← Historical migration docs (reference)
│       └── module-autodiscovery-migration.md
├── proposals/                    ← Future features only
│   ├── loyalty-program-analysis.md
│   └── loyalty-phase2-interfaces-plan.md
└── archive/                      ← Completed plans (optional)
    ├── SESSION_NOTE_*.md
    └── *-implementation-plan.md

Consolidation Steps

Phase 1: Module System Documentation

1. Review all SESSION_NOTE files for module system
2. Extract key decisions and final architecture
3. Update architecture/module-system.md with:
   • Clear module classification (core/optional/internal)
   • Route auto-discovery pattern
   • Entity locations (routes, services, models, etc.)
4. Archive SESSION_NOTE files

Phase 2: CMS & Homepage Documentation

1. Merge CMS architecture into features/content-management-system.md
2. Merge homepage sections into features/platform-homepage.md
3. Archive implementation plans

Phase 3: Vendor & Marketplace Documentation

1. Update architecture/company-vendor-management.md with:
   • Contact inheritance
   • Vendor operations
2. Update architecture/marketplace-integration.md with:
   • Multi-marketplace product architecture
   • Sync patterns

Phase 4: Development Guides

1. Create/update development/coding-standards.md with db.commit pattern
2. Verify Tailwind migration status, archive if complete
3. Clean up migration folder

Phase 5: Archive

1. Create docs/archive/ folder (or just delete completed plans)
2. Move completed implementation plans
3. Move SESSION_NOTE files

Priority Order

1. High: Module system (most referenced, core architecture)
2. High: CMS/Homepage (user-facing features)
3. Medium: Vendor/Marketplace (operational)
4. Low: Archive cleanup

Notes

• Keep migration/module-autodiscovery-migration.md as historical reference
• SESSION_NOTEs contain valuable context but are verbose for reference docs
• Focus on "what is" not "what was planned" in final docs