Repository Architecture Analysis

Activity Dashboard & Context Management Integration

Date: November 26, 2025 Status: Analysis & Recommendation

---

Current State

Repository Structure

46 Git Repositories (1 parent + 45 submodules):

coditect-rollout-master/ (PARENT)
├── .git (https://github.com/coditect-ai/coditect-rollout-master.git)
├── MEMORY-CONTEXT/               # Session data storage (NOT in submodule)
│   ├── dashboard/                # Activity Timeline Dashboard (⚠️ ORPHANED)
│   │   ├── index.html
│   │   ├── css/
│   │   ├── js/
│   │   ├── data/ (135 files, 8MB)
│   │   └── Python scripts (4 search database builders)
│   ├── sessions/
│   ├── checkpoints/
│   ├── exports/
│   └── dedup_state/
│
└── submodules/dev/coditect-dev-context/  # Context Management System
    ├── .git (https://github.com/coditect-ai/coditect-dev-context.git)
    ├── app/                      # FastAPI application
    ├── backend/                  # Backend services
    ├── docs/                     # NEW: Complete documentation suite
    │   ├── sdd/                  # Software Design Document
    │   ├── tdd/                  # Test-Driven Development
    │   ├── diagrams/             # C4 architecture/workflows
    │   ├── business/             # Business plans, pitch decks
    │   └── adrs/                 # Architecture Decision Records
    ├── main.py                   # Entry point
    └── requirements.txt

Two GitHub Repositories

1. coditect-ai/coditect-rollout-master (Parent)

   • Purpose: Master orchestration, 46 submodules
   • Contains: MEMORY-CONTEXT data storage
   • NOT versioned separately: Activity dashboard

2. coditect-ai/coditect-dev-context (Submodule)

   • Purpose: Context management system (backend + API)
   • Contains: Complete technical + business documentation
   • Missing: Frontend dashboard

---

Problem Analysis

Issue #1: Dashboard is Orphaned

Current Location: /MEMORY-CONTEXT/dashboard/ in parent repo

Problems:

• ✗ Not version controlled separately (part of monolithic parent)
• ✗ Not semantically grouped with context management code
• ✗ Difficult to deploy independently
• ✗ No clear ownership (parent repo or submodule?)

Dashboard Stats:

• 118 files, 21 MB total
• 10,206 conversation messages
• 124 sessions indexed
• 4,060 file references
• 1,732 commands tracked
• Interactive web UI (HTML/CSS/JS)
• Python data generator scripts

Issue #2: Semantic Mismatch

coditect-dev-context is the "Context Management System" but has:

• ✓ Backend API (FastAPI)
• ✓ Database models
• ✓ Business logic
• ✓ Complete documentation (SDD, TDD, C4, Business Plan)
• ✗ Missing: Frontend/Dashboard

The dashboard that SHOWS context is NOT in the context management repo!

Issue #3: Data vs. Presentation Split

• Data Storage: /MEMORY-CONTEXT/ in parent repo (correct location)
• Data Presentation: /MEMORY-CONTEXT/dashboard/ in parent repo (should be in submodule)

This creates confusion about what belongs where.

---

Recommendation: 3 Options

Option 1: Move Dashboard to Submodule (RECOMMENDED ⭐)

Move: /MEMORY-CONTEXT/dashboard/ → /submodules/dev/coditect-dev-context/frontend/

Structure:

coditect-dev-context/
├── app/                    # Backend API
├── backend/                # Services
├── frontend/               # NEW: Activity Dashboard
│   ├── public/
│   │   ├── index.html
│   │   ├── css/
│   │   ├── js/
│   │   └── assets/
│   ├── scripts/
│   │   └── generate-dashboard.py
│   └── README.md
├── docs/                   # Documentation
└── main.py

Pros:

• ✓ Semantic grouping (frontend + backend together)
• ✓ Independent versioning of dashboard
• ✓ Clear ownership
• ✓ Can deploy frontend separately
• ✓ Can develop independently

Cons:

• ✗ Dashboard references data in parent repo (need config)
• ✗ One-time migration effort

Data Access Strategy:

• Dashboard runs via HTTP server (already required)
• Configure data path to reference parent repo: ../../../MEMORY-CONTEXT/data/
• Or: Copy/sync data to frontend/data/ during build

Option 2: Create Separate Frontend Submodule

New Repo: coditect-dev-context-dashboard (separate submodule)

Pros:

• ✓ Maximum separation of concerns
• ✓ Frontend team can work independently
• ✓ Clear versioning

Cons:

• ✗ Adds complexity (now 47 repos instead of 46)
• ✗ Overkill for current size
• ✗ More overhead to manage

Option 3: Keep Dashboard in Parent (Status Quo)

No change - keep dashboard in /MEMORY-CONTEXT/dashboard/

Pros:

• ✓ No migration needed
• ✓ Direct access to data

Cons:

• ✗ Poor semantic grouping
• ✗ Not independently versionable
• ✗ Unclear ownership
• ✗ Harder to deploy separately

---

Recommended Action Plan

Phase 1: Backup & Prepare (30 minutes)

1. Backup current dashboard:

   cd /Users/halcasteel/PROJECTS/coditect-rollout-master/MEMORY-CONTEXT
   tar -czf dashboard-backup-$(date +%Y%m%d-%H%M%S).tar.gz dashboard/

2. Create migration branch in submodule:

   cd submodules/dev/coditect-dev-context
   git checkout -b feature/add-frontend-dashboard

3. Test dashboard still works:

   cd /Users/halcasteel/PROJECTS/coditect-rollout-master/MEMORY-CONTEXT/dashboard
   python3 -m http.server 8080
   # Verify: http://localhost:8080

Phase 2: Move Dashboard to Submodule (1 hour)

1. Create frontend directory in submodule:

   cd /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/dev/coditect-dev-context
   mkdir -p frontend/public frontend/scripts

2. Copy dashboard files:

   # Copy web assets
   cp -r ../../../MEMORY-CONTEXT/dashboard/index.html frontend/public/
   cp -r ../../../MEMORY-CONTEXT/dashboard/css frontend/public/
   cp -r ../../../MEMORY-CONTEXT/dashboard/js frontend/public/
   cp -r ../../../MEMORY-CONTEXT/dashboard/assets frontend/public/
   
   # Copy scripts
   cp ../../../MEMORY-CONTEXT/dashboard/*.py frontend/scripts/
   
   # Copy documentation
   cp ../../../MEMORY-CONTEXT/dashboard/README.md frontend/
   cp ../../../MEMORY-CONTEXT/dashboard/*.md frontend/

3. Create data symlink:

   cd frontend/public
   ln -s ../../../../../MEMORY-CONTEXT/dashboard/data data

4. Update README with new paths:

   # Update frontend/README.md to document:
   # - New location
   # - Data symlink
   # - How to run: cd frontend/public && python3 -m http.server 8080

Phase 3: Update Configuration (30 minutes)

1. Create frontend/config.json:

   {
     "dataPath": "./data/",
     "apiEndpoint": "http://localhost:8000/api/v1",
     "version": "1.0.0"
   }

2. Update JavaScript to use config:

   // frontend/public/js/config.js
   const CONFIG = {
     dataPath: './data/',  // Symlink to parent repo
     apiEndpoint: 'http://localhost:8000/api/v1'
   };

3. Test dashboard from new location:

   cd submodules/dev/coditect-dev-context/frontend/public
   python3 -m http.server 8080
   # Verify: http://localhost:8080

Phase 4: Commit & Push (15 minutes)

1. Commit in submodule:

   cd /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/dev/coditect-dev-context
   git add frontend/
   git commit -m "feat: Add frontend activity dashboard
   
   - Move dashboard from parent repo MEMORY-CONTEXT/dashboard
   - Create frontend/public/ for web assets
   - Create frontend/scripts/ for Python generators
   - Add data symlink to parent repo
   - Update README with new location
   
   🤖 Generated with Claude Code
   Co-Authored-By: Claude <noreply@anthropic.com>"
   git push origin feature/add-frontend-dashboard

2. Update parent repo:

   cd /Users/halcasteel/PROJECTS/coditect-rollout-master
   git add submodules/dev/coditect-dev-context
   git commit -m "Update coditect-dev-context: Add frontend dashboard"
   git push

3. Optional: Remove old dashboard from parent (after verification):

   # Keep backup, remove old location
   mv MEMORY-CONTEXT/dashboard MEMORY-CONTEXT/dashboard-OLD-BACKUP-20251126
   # Add to .gitignore if not already
   echo "MEMORY-CONTEXT/dashboard-OLD-BACKUP-*" >> .gitignore

Phase 5: Documentation Update (30 minutes)

1. Update submodule README:

   • Document frontend/ directory
   • Explain data symlink strategy
   • Add development instructions

2. Update parent repo CLAUDE.md:

   • Note that dashboard moved to submodule
   • Update paths in documentation

3. Create migration guide:

   • Document why we moved it
   • How to access from new location
   • Troubleshooting tips

---

Timeline & Resources

Phase	Duration	Resources	Deliverables
Phase 1	30 min	1 developer	Backup, test, branch created
Phase 2	1 hour	1 developer	Dashboard moved, symlink created
Phase 3	30 min	1 developer	Config updated, tested
Phase 4	15 min	1 developer	Committed, pushed
Phase 5	30 min	1 developer	Documentation updated
Total	2.75 hours	1 developer	Dashboard integrated

---

Success Criteria

• Dashboard accessible from submodule location
• All 10,206 messages load correctly
• Navigation works (6 main views)
• Data loading works (135 JSON files)
• Timeline renders correctly
• Search functionality works
• No broken links or paths
• Old location backed up
• Documentation updated
• Both repos committed & pushed

---

Risk Assessment

Risk	Probability	Impact	Mitigation
Data path breaks	Medium	High	Symlink + config.json with fallback paths
Dashboard stops working	Low	High	Keep backup, test before removing old
Git conflicts	Low	Medium	Work in feature branch, merge carefully
Team confusion	Medium	Low	Clear documentation, migration guide

---

Decision

Recommended: Option 1 - Move Dashboard to Submodule

Rationale:

1. Semantic correctness (frontend + backend together)
2. Independent versioning
3. Clearer ownership
4. Better for future frontend development
5. Minimal complexity increase
6. 2.75 hours migration time is acceptable

Next Steps:

1. Get approval to proceed
2. Execute Phase 1 (backup & prepare)
3. Execute Phases 2-5 if Phase 1 succeeds

---

Prepared By: Claude Code (AI Assistant) Date: November 26, 2025 Status: Awaiting approval to proceed