metabuilder/frontends/codegen/docs/ORGANIZATION_PLAN.md

Documentation Organization Plan

This document outlines the new documentation structure for CodeForge.

📁 New Structure

/docs/
├── README.md                          # Main docs index
├── PRD.md                            # Product Requirements Document
│
├── /architecture/                     # Architecture documentation
│   ├── DECLARATIVE_SYSTEM.md         # ⭐ Primary system docs
│   ├── ARCHITECTURE_VISUAL_GUIDE.md
│   ├── CONFIG_ARCHITECTURE.md
│   ├── JSON_ORCHESTRATION_COMPLETE.md
│   ├── JSON_ORCHESTRATION_GUIDE.md
│   └── /atomic/                      # Legacy atomic design docs
│       ├── ATOMIC_README.md
│       ├── ATOMIC_COMPONENTS.md
│       ├── ATOMIC_REFACTOR_SUMMARY.md
│       ├── ATOMIC_USAGE_EXAMPLES.md
│       ├── ATOMIC_VISUAL_OVERVIEW.md
│       ├── ATOMIC_DOCS_INDEX.md
│       └── COMPONENT_MAP.md
│
├── /api/                             # API and Hook references
│   ├── COMPLETE_HOOK_LIBRARY.md
│   ├── HOOK_LIBRARY_DOCS.md
│   └── HOOK_LIBRARY_REFERENCE.md
│
├── /guides/                          # User guides
│   ├── QUICK_REFERENCE.md
│   ├── QUICKSTART_HOOKS.md
│   ├── PWA_GUIDE.md
│   ├── CI_CD_GUIDE.md
│   ├── ERROR_REPAIR_GUIDE.md
│   ├── SEED_DATA_GUIDE.md
│   ├── PROPS_CONFIG_GUIDE.md
│   ├── MIGRATION_GUIDE.md
│   └── FAVICON_DESIGNER_ACCESS.md
│
├── /testing/                         # Testing documentation
│   ├── RUN_TESTS.md
│   ├── E2E_TEST_SUMMARY.md
│   ├── SMOKE_TEST_REPORT.md
│   ├── SMOKE_TEST_QUICK_REF.md
│   └── CONNECTION_TEST_PLAN.md
│
├── /deployment/                      # Deployment and operations
│   ├── CI_FIX_SUMMARY.md
│   └── BAD_GATEWAY_FIX.md
│
├── /history/                         # Development history
│   ├── REFACTORING_PLAN.md
│   ├── REFACTORING_LOG.md
│   ├── REFACTORING_SUMMARY.md
│   ├── REFACTORING_EXAMPLE.md
│   ├── REFACTOR_PHASE2.md
│   ├── REFACTOR_PHASE3.md
│   ├── PHASE2_REFACTORING_SUMMARY.md
│   ├── PHASE3_COMPLETE.md
│   ├── PHASE4_IMPLEMENTATION_COMPLETE.md
│   ├── REFACTOR_PHASE4_COMPLETE.md
│   └── DELIVERY_COMPLETE.md
│
└── /reference/                       # Reference materials
    ├── INDEX.md
    ├── EXAMPLE_NEW_PAGE.md
    ├── AGENTS.md
    ├── APP_STATUS.md
    ├── ROADMAP.md
    └── SECURITY.md

🔄 File Migrations

From Root → docs/architecture/

• DECLARATIVE_SYSTEM.md
• ARCHITECTURE_VISUAL_GUIDE.md
• CONFIG_ARCHITECTURE.md
• JSON_ORCHESTRATION_COMPLETE.md
• JSON_ORCHESTRATION_GUIDE.md

From Root → docs/architecture/atomic/

• ATOMIC_README.md
• ATOMIC_COMPONENTS.md
• ATOMIC_REFACTOR_SUMMARY.md
• ATOMIC_USAGE_EXAMPLES.md
• ATOMIC_VISUAL_OVERVIEW.md
• ATOMIC_DOCS_INDEX.md
• COMPONENT_MAP.md

From Root → docs/api/

• COMPLETE_HOOK_LIBRARY.md
• HOOK_LIBRARY_DOCS.md
• HOOK_LIBRARY_REFERENCE.md

From Root → docs/guides/

• QUICK_REFERENCE.md
• QUICKSTART_HOOKS.md
• PWA_GUIDE.md
• CI_CD_GUIDE.md
• ERROR_REPAIR_GUIDE.md
• SEED_DATA_GUIDE.md
• PROPS_CONFIG_GUIDE.md
• MIGRATION_GUIDE.md
• FAVICON_DESIGNER_ACCESS.md

From Root → docs/testing/

• RUN_TESTS.md
• E2E_TEST_SUMMARY.md
• SMOKE_TEST_REPORT.md
• SMOKE_TEST_QUICK_REF.md
• CONNECTION_TEST_PLAN.md

From Root → docs/deployment/

• CI_FIX_SUMMARY.md
• BAD_GATEWAY_FIX.md

From Root → docs/history/

• REFACTORING_PLAN.md
• REFACTORING_LOG.md
• REFACTORING_SUMMARY.md
• REFACTORING_EXAMPLE.md
• REFACTOR_PHASE2.md
• REFACTOR_PHASE3.md
• PHASE2_REFACTORING_SUMMARY.md
• PHASE3_COMPLETE.md
• PHASE4_IMPLEMENTATION_COMPLETE.md
• REFACTOR_PHASE4_COMPLETE.md
• DELIVERY_COMPLETE.md

From Root → docs/reference/

• INDEX.md
• EXAMPLE_NEW_PAGE.md
• AGENTS.md
• APP_STATUS.md
• ROADMAP.md
• SECURITY.md

Stay in Root

• README.md (main project README - updated to point to docs/)
• LICENSE
• package.json
• etc. (all non-documentation files)

✅ Benefits

1. Cleaner Root Directory - Only essential project files in root
2. Logical Grouping - Related docs are together
3. Easy Navigation - Clear folder names indicate content type
4. Scalable - Easy to add new docs in appropriate categories
5. Better Discoverability - Index file guides users to right docs
6. Maintains History - All refactoring logs preserved in /history

📝 Next Steps

1. ✅ Create /docs folder structure
2. ✅ Create docs/README.md index
3. ✅ Move PRD.md to docs/
4. ⏳ Create subdirectories
5. ⏳ Move files to appropriate locations
6. ⏳ Update internal links in moved files
7. ⏳ Update main README.md to reference docs/
8. ⏳ Verify all links work