Documentation Reorganization Proposal
Date: 2025-10-07 Status: 📋 Proposal Purpose: Improve documentation discoverability and logical organization
🎯 Problem Statement
Current Issues:
- Flat structure - 26 files in
/docs/root with no clear categorization - Mixed concerns - Infrastructure, security, deployment, and architecture docs intermixed
- Hard to find - No clear entry point for specific topics (security, infrastructure, API)
- Duplication risk - Similar topics scattered across multiple locations
Example:
- Infrastructure docs in both
/docs/AND/infrastructure/ - Security now in
/docs/04-security/security-hardening-plan.mdbut no dedicated security section - API docs in
/docs/,/docs/api/, and/backend/
📂 Proposed Structure
Option 1: Topic-Based Organization (Recommended)
/workspace/PROJECTS/t2/
├── docs/
│ ├── README.md # Master index, quick links
│ ├── index.md # Detailed table of contents
│ │
│ ├── 01-getting-started/ # Quick start guides
│ │ ├── README.md # Getting started overview
│ │ ├── quick-start.md # 15-min setup guide
│ │ ├── DEPLOYMENT-TRACKER.md # Step-by-step tracker
│ │ └── TROUBLESHOOTING.md # Common issues
│ │
│ ├── 02-architecture/ # System design
│ │ ├── README.md # Architecture overview
│ │ ├── sdd.md # Software Design Doc
│ │ ├── tdd.md # Technical Design Doc
│ │ ├── V5-SCALING-architecture.md
│ │ ├── CODITECT-V5-automated-pod-provisioning.md
│ │ └── diagrams/ # Mermaid/SVG diagrams
│ │
│ ├── 03-infrastructure/ # IaC & deployment
│ │ ├── README.md # Infrastructure overview
│ │ ├── infrastructure-map.md # IP addresses, network topology
│ │ ├── iac-implementation-summary.md # Terraform implementation
│ │ ├── critical-roadmap.md # Infrastructure roadmap
│ │ ├── gcp-setup-commands.md # GCP initial setup
│ │ ├── foundationdb-info.md # FDB cluster info
│ │ └── terraform/ # Symlink to /infrastructure/terraform/
│ │
│ ├── 04-security/ # Security & compliance
│ │ ├── README.md # Security overview
│ │ ├── security-hardening-plan.md # 3-phase hardening plan
│ │ ├── COMPLIANCE-CHECKLIST.md # SOC2/GDPR/HIPAA (future)
│ │ ├── INCIDENT-RESPONSE.md # Security incident runbook (future)
│ │ ├── SECRETS-MANAGEMENT.md # Secret Manager guide (future)
│ │ └── AUDIT-LOGS.md # Audit logging guide (future)
│ │
│ ├── 05-api/ # API documentation
│ │ ├── README.md # API overview
│ │ ├── api-testing-summary.md # Test suite summary
│ │ ├── api-test-plan.md # Symlink to /backend/api-test-plan.md
│ │ ├── ENDPOINTS.md # API endpoint reference
│ │ └── openapi.yaml # OpenAPI spec (future)
│ │
│ ├── 06-backend/ # Backend implementation
│ │ ├── README.md # Backend overview
│ │ ├── backend-deployment-resolution.md
│ │ ├── backend-integration.md
│ │ ├── backend-summary.md
│ │ └── gcp-cloud-build-guide.md
│ │
│ ├── 07-adr/ # Architecture Decision Records
│ │ ├── README.md # ADR index
│ │ ├── ADR-001-react-typescript.md
│ │ ├── ADR-014-eclipse-theia.md
│ │ └── ...
│ │
│ ├── 08-v4-reference/ # V4 legacy reference
│ │ ├── README.md # V4 documentation index
│ │ ├── V4-DOCUMENTATION-index.md
│ │ ├── v4-source-code-reference.md
│ │ ├── adrs/ # V4 ADRs (88 files)
│ │ ├── architecture/ # V4 architecture docs
│ │ ├── agents/ # V4 agent system
│ │ └── config/ # V4 config reference
│ │
│ ├── 09-sessions/ # Session exports & context
│ │ ├── README.md # Session tracking overview
│ │ ├── 2025-10-06_llm-migration/
│ │ ├── 2025-10-07_infrastructure/ # Today's session
│ │ └── templates/
│ │
│ ├── 10-execution-plans/ # Project roadmaps
│ │ ├── README.md # Execution plan overview
│ │ ├── corrected-execution-order.md
│ │ ├── optimal-execution-order.md
│ │ ├── v5-mvp-automation-roadmap.md
│ │ ├── phase-1-completion-summary.md
│ │ └── deployment-step-by-step-tracker.md
│ │
│ ├── 11-analysis/ # Research & analysis
│ │ ├── V5-FDB-SCHEMA-AND-ADR-analysis.md
│ │ └── build-logs/ # Build analysis logs
│ │
│ └── 99-archive/ # Deprecated docs
│ └── old-deployment-guides/
│
├── infrastructure/ # Infrastructure as Code
│ ├── README.md # User-facing infra guide
│ ├── CLAUDE.md # AI assistant guidance
│ ├── KUBERNETES-TERRAFORM-HELM-1-2-3-quickstart.md # Keep here (primary)
│ └── terraform/ # Terraform modules
│ ├── README.md
│ ├── CLAUDE.md
│ └── modules/
│
└── backend/ # Backend code
├── README.md
├── api-test-plan.md # API testing documentation
└── test-api.sh # API test script
Option 2: Audience-Based Organization
docs/
├── for-developers/ # Dev-focused docs
│ ├── quick-start/
│ ├── api/
│ ├── backend/
│ └── architecture/
│
├── for-operations/ # Ops-focused docs
│ ├── infrastructure/
│ ├── deployment/
│ ├── monitoring/
│ └── troubleshooting/
│
├── for-security/ # Security-focused docs
│ ├── hardening/
│ ├── compliance/
│ └── incident-response/
│
└── for-leadership/ # High-level docs
├── roadmaps/
├── status-reports/
└── architecture-decisions/
Option 3: Minimal Reorganization (Conservative)
docs/
├── infrastructure/ # Move infra docs here
│ ├── infrastructure-map.md
│ ├── iac-implementation-summary.md
│ ├── critical-roadmap.md
│ ├── gcp-setup-commands.md
│ └── foundationdb-info.md
│
├── security/ # New security folder
│ ├── security-hardening-plan.md
│ ├── COMPLIANCE-CHECKLIST.md (future)
│ └── INCIDENT-RESPONSE.md (future)
│
├── api/ # Already exists
│ └── (existing API docs)
│
├── backend/ # Move backend docs
│ ├── backend-deployment-resolution.md
│ ├── backend-integration.md
│ └── backend-summary.md
│
└── (rest stay in /docs/ root)
🎯 Recommendation: Option 1 (Topic-Based)
Rationale:
- ✅ Scalable - Easy to add new categories as project grows
- ✅ Discoverable - Clear hierarchy by topic
- ✅ Maintainable - Related docs grouped together
- ✅ Familiar - Matches industry best practices (GitLab, Kubernetes docs)
- ✅ Future-proof - Room for compliance, monitoring, runbooks
Migration Effort: 2-3 hours (mostly file moves + update links)
📋 Migration Plan
Phase 1: Create New Structure (30 minutes)
# Create new directories
cd /workspace/PROJECTS/t2/docs
mkdir -p 01-getting-started
mkdir -p 02-architecture/{diagrams}
mkdir -p 03-infrastructure
mkdir -p 04-security
mkdir -p 05-api
mkdir -p 06-backend
mkdir -p 07-adr
mkdir -p 08-v4-reference
mkdir -p 09-sessions
mkdir -p 10-execution-plans
mkdir -p 11-analysis
mkdir -p 99-archive
# Create README files for each section
for dir in 0*-*/; do
echo "# $(basename $dir | sed 's/[0-9]*-//' | tr '-' ' ' | sed 's/.*/\u&/')" > "$dir/README.md"
done
Phase 2: Move Files (1 hour)
# Infrastructure docs
mv infrastructure-map.md 03-infrastructure/
mv iac-implementation-summary.md 03-infrastructure/
mv critical-infrastructure-roadmap.md 03-infrastructure/critical-roadmap.md
mv gcp-setup-commands.md 03-infrastructure/
mv foundationdb-info.md 03-infrastructure/
# Security docs
mv security-hardening-plan.md 04-security/
# API docs
mv api-testing-summary.md 05-api/
# Symlink api-test-plan.md from /backend/
ln -s ../../backend/api-test-plan.md 05-api/api-test-plan.md
# Backend docs
mv backend-deployment-resolution-report.md 06-backend/backend-deployment-resolution.md
mv backend-integration.md 06-backend/
mv backend-summary.md 06-backend/
mv coditect-v5-gcp-cloud-build-deployment-guide.md 06-backend/gcp-cloud-build-guide.md
# Architecture docs
mv sdd.md 02-architecture/
mv tdd.md 02-architecture/
mv V5-SCALING-architecture.md 02-architecture/
mv CODITECT-V5-AUTOMATED-POD-PROVISIONING-architecture.md 02-architecture/
mv diagrams/ 02-architecture/diagrams/
# ADRs
mv adr/ 07-adr/
# V4 reference
mv V4-DOCUMENTATION-index.md 08-v4-reference/
mv v4-source-code-reference.md 08-v4-reference/
mv v4-reference/ 08-v4-reference/
mv v4-agents/ 08-v4-reference/agents/
mv v4-analysis/ 08-v4-reference/analysis/
mv v4-config/ 08-v4-reference/config/
# Sessions
mv sessions/ 09-sessions/
# Execution plans
mv corrected-execution-order.md 10-execution-plans/
mv optimal-execution-order.md 10-execution-plans/
mv v5-mvp-automation-roadmap.md 10-execution-plans/
mv phase-1-completion-summary.md 10-execution-plans/
mv deployment-step-by-step-tracker.md 10-execution-plans/
mv deployment.md 10-execution-plans/
# Analysis
mv V5-FDB-SCHEMA-AND-ADR-analysis.md 11-analysis/
mv build-logs/ 11-analysis/
# Getting started
mv guides/ 01-getting-started/
Phase 3: Update Links (1 hour)
# Use sed to update all internal links
find . -name "*.md" -exec sed -i 's|docs/03-infrastructure/infrastructure-map.md|docs/03-infrastructure/infrastructure-map.md|g' {} \;
find . -name "*.md" -exec sed -i 's|docs/04-security/security-hardening-plan.md|docs/04-security/security-hardening-plan.md|g' {} \;
# ... (continue for all moved files)
Phase 4: Create Master Index (30 minutes)
# Update docs/README.md with new structure
# Update docs/index.md with detailed navigation
📚 Master Index Structure
docs/README.md (New)
# Coditect V5 Documentation
**Quick Links**: [Getting Started](#getting-started) | [Architecture](#architecture) | [Infrastructure](#infrastructure) | [Security](#security) | [API](#api)
## 🚀 Getting Started
- [Quick Start Guide](01-getting-started/quick-start.md) - 15-minute setup
- [Deployment Tracker](10-execution-plans/deployment-step-by-step-tracker.md)
- [Troubleshooting](01-getting-started/TROUBLESHOOTING.md)
## 🏗️ Architecture
- [Software Design Document (SDD)](02-architecture/sdd.md)
- [Technical Design Document (TDD)](02-architecture/tdd.md)
- [V5 Scaling Architecture](02-architecture/V5-SCALING-architecture.md)
## 🌐 Infrastructure
- [Infrastructure Map](03-infrastructure/infrastructure-map.md) - IPs, networks, topology
- [Terraform Implementation](03-infrastructure/iac-implementation-summary.md)
- [Quick Start: Terraform + K8s](../infrastructure/KUBERNETES-TERRAFORM-HELM-1-2-3-quickstart.md)
## 🔒 Security
- [Security Hardening Plan](04-security/security-hardening-plan.md) - 3-phase plan
- [Compliance Checklist](04-security/COMPLIANCE-CHECKLIST.md) (future)
## 🔌 API
- [API Testing Summary](05-api/api-testing-summary.md)
- [API Test Plan](05-api/api-test-plan.md)
## 📖 Reference
- [Architecture Decision Records](07-adr/)
- [V4 Reference Documentation](08-v4-reference/)
---
**For detailed navigation**, see [index.md](index.md)
🎯 Benefits of This Organization
For Developers
- ✅ Clear entry point:
docs/README.md - ✅ Quick access to getting started guides
- ✅ Easy to find API and backend docs
For Operations
- ✅ All infrastructure docs in one place (
03-infrastructure/) - ✅ Security hardening plan easy to find (
04-security/) - ✅ Deployment guides centralized
For Security Team
- ✅ Dedicated security section (
04-security/) - ✅ Room for compliance, incident response, audit logs
- ✅ Clear separation from operational docs
For Leadership
- ✅ High-level roadmaps in
10-execution-plans/ - ✅ Status reports in
09-sessions/or dedicated section - ✅ Architecture decisions in
07-adr/
For Maintainability
- ✅ Related docs grouped together
- ✅ Numbered folders enforce logical order
- ✅ README.md in each section provides context
- ✅ Symlinks avoid duplication
🚨 Rollback Plan
If reorganization causes issues:
# Git revert
git checkout HEAD -- docs/
git clean -fd docs/
# Or manual restore from backup
cp -r /workspace/PROJECTS/t2/docs-backup/* /workspace/PROJECTS/t2/docs/
Before migration: Create backup
cp -r /workspace/PROJECTS/t2/docs /workspace/PROJECTS/t2/docs-backup
📝 Alternative: Symlinks (If Full Migration Too Risky)
Keep current structure but add symlinks for navigation:
cd /workspace/PROJECTS/t2/docs
# Create topic folders with symlinks
mkdir security
ln -s ../security-hardening-plan.md security/
mkdir infrastructure
ln -s ../infrastructure-map.md infrastructure/
ln -s ../iac-implementation-summary.md infrastructure/
mkdir api
ln -s ../api-testing-summary.md api/
Pros: No link updates needed Cons: Cluttered root directory remains
🎯 Recommended Next Steps
- Approve Structure - Choose Option 1, 2, 3, or alternative
- Create Backup -
cp -r docs docs-backup - Run Migration Script - Execute Phase 1-4
- Update README.md - Create master index
- Update Links - Fix internal references
- Test Navigation - Verify all links work
- Update CLAUDE.md - Update AI guidance with new structure
- Commit Changes - Git commit with clear message
Estimated Time: 2-3 hours total
📊 Before/After Comparison
Before
docs/
├── 26 files in root (hard to navigate)
├── adr/
├── api/
├── v4-reference/
└── sessions/
After (Option 1)
docs/
├── README.md (master index)
├── 01-getting-started/
├── 02-architecture/
├── 03-infrastructure/
├── 04-security/ ← NEW
├── 05-api/
├── 06-backend/
├── 07-adr/
├── 08-v4-reference/
├── 09-sessions/
├── 10-execution-plans/
└── 11-analysis/
Discoverability: 🔴 Poor → 🟢 Excellent
Decision Required: Which option should we implement?
My Recommendation: Option 1 (Topic-Based) for long-term maintainability and scalability.