V4 Documentation Index

Complete index of coditect-v4 reference materials copied to the t2 project.

Overview

Total V4 Reference Materials: ~2.2MB

• Architecture Docs: 3 files (SDD, TDD, CODI design)
• ADRs: 88 architecture decision records
• Agent System: Complete agent framework documentation
• Source Code: 11 directories (~5.3MB, see v4-source-code-reference.md)

Directory Structure

docs/
├── v4-reference/              # Architecture & ADRs (1.7MB)
│   ├── README.md             # Reference documentation guide
│   ├── architecture/         # SDD, TDD, CODI design (3 docs)
│   └── adrs/                 # 88 ADRs covering all v4 decisions
└── v4-agents/                # Agent system docs (512KB)
    ├── coditect/             # 10 CODITECT agent definitions
    ├── coditect-enhanced/    # Enhanced agent variants
    ├── quick-start-guides/   # Agent onboarding guides
    ├── templates/            # Agent templates
    └── tools/                # Agent tooling scripts

src/
├── frontend-original/        # V4 React frontend (2.6MB)
└── v4-*/                     # 10 V4 service directories (2.7MB)

Key Documents

Architecture Documents

Document	Location	Size	Purpose
V4 SDD	docs/v4-reference/architecture/v4-sdd-software-design-document.md	20KB	System overview, components
V4 TDD	docs/v4-reference/architecture/v4-tdd-technical-design-document.md	12KB	Technical implementation
CODI Design	docs/v4-reference/architecture/v4-codi-race-free-architecture-design.md	26KB	Concurrency patterns

Critical ADRs for T2

FoundationDB & Storage:

• ADR-002-v4-storage-architecture - Keyspace design, data partitioning
• ADR-006-v4-data-model - User/workspace/session schemas

Multi-Tenant & Security:

• ADR-003-v4-multi-tenant-architecture - Tenant isolation patterns
• ADR-005-v4-authentication-authorization - JWT, RBAC, sessions
• ADR-024-v4-security-hardening-architecture - Security best practices

Monitoring & Observability:

• ADR-008-v4-monitoring-observability - Logging, metrics, tracing
• ADR-016-v4-codi-rust-implementation - File monitoring in Rust
• ADR-031-v4-codi2-monitor-integration - File system event handling

AI & llm Integration:

• ADR-007-v4-ai-router-architecture - llm provider routing
• ADR-019-v4-prompt-engine-server-architecture - Prompt optimization
• ADR-022-v4-llm-log-reranking - Log analysis with llms

System Architecture:

• ADR-001-v4-container-execution-architecture - Container orchestration
• ADR-004-v4-api-architecture - API design patterns
• ADR-017-v4-unified-workspace-architecture - Multi-session management

Agent System Documentation

Document	Purpose
docs/v4-agents/coditect-sub-agents-master-list.md	Complete agent catalog
docs/v4-agents/multi-session-guide.md	Multi-agent coordination
docs/v4-agents/migration-guide.md	Agent system migration
docs/v4-agents/sub-agent-build-sprint-checklist.md	Agent development workflow
docs/v4-agents/coditect/orchestrator.md	Orchestrator agent definition
docs/v4-agents/coditect/rust-developer.md	Rust specialist agent
docs/v4-agents/coditect/frontend-developer.md	Frontend specialist agent

Usage Guidelines

When to Reference V4 Documentation

✅ Reference for:

1. FoundationDB keyspace design patterns (ADR-002, ADR-006)
2. Multi-tenant isolation strategies (ADR-003)
3. Authentication & authorization flows (ADR-005)
4. File monitoring architecture (ADR-016, ADR-031)
5. Agent coordination patterns (v4-agents/)
6. Security hardening approaches (ADR-024)

When NOT to Copy V4 Patterns

❌ Do NOT copy:

1. workspace architecture - T2 uses theia, not custom React
2. Container orchestration - Different deployment model
3. Frontend components - T2 is theia extensions
4. editor implementation - Use theia's built-in Monaco
5. terminal implementation - Use theia's built-in terminal

Key Differences: V4 vs T2

Aspect	V4 (Reference)	T2 (Current)	Use V4 Docs For
IDE	Custom React web app	Eclipse theia extensions	UI patterns, styling ideas
Storage	FoundationDB + K8s PVs	FoundationDB + OPFS	FDB patterns (✅)
Multi-tenant	K8s pods per user	theia workspaces	Isolation patterns (✅)
Auth	JWT + FDB sessions	JWT + FDB sessions	Auth flows (✅)
Monitoring	CODI Rust + FDB	CODI + file-monitor	CODI architecture (✅)
Agents	Multi-agent MCP/A2A	Multi-agent MCP/A2A	Agent patterns (✅)
editor	Custom Monaco	theia's Monaco	❌ Don't copy
terminal	Custom xterm.js pods	theia's terminal	❌ Don't copy
Build	Vite + Cargo	theia build	❌ Don't copy

Integration with T2 Documentation

T2 Architecture Docs (Primary):

• docs/CLAUDE.md - Main project guidance
• docs/sdd.md - T2 Software Design Document
• docs/tdd.md - T2 Technical Design Document
• docs/adr/ADR-014-*.md - Eclipse theia decision (CRITICAL)
• docs/architecture/architecture.md - T2 system architecture

V4 Docs (Reference):

• Use to validate T2 decisions
• Learn from V4 successes and mistakes
• Extract reusable patterns (FDB, auth, monitoring)
• Understand multi-tenant architecture

ADR Quick Reference

By Number

ADR	Title	Key Topic
001	Container Execution	K8s pods, resource limits
002	Storage Architecture	FoundationDB keyspace
003	Multi-Tenant	Tenant isolation
004	API Architecture	REST/GraphQL patterns
005	Auth/Authorization	JWT, sessions, RBAC
006	Data Model	FDB schemas
007	AI Router	llm provider routing
008	Monitoring	Logging, metrics
009	CODI CLI	Command interface
010	Disaster Recovery	Backup strategies
011	Audit/Compliance	GDPR, SOC2
012	Code Generation	AI code generation
013	Queue Management	Task queues
014	Deployment Pipeline	CI/CD
015	Team Collaboration	Real-time collab
016	CODI Rust	File monitoring
017	Unified workspace	Multi-session
018	Dynamic Commands	CODI commands
019	Prompt Engine	Prompt optimization
020	Agents.md Adoption	Agent framework
021	Hybrid Graph System	Knowledge graphs
022	llm Log Reranking	Log analysis
024	Security Hardening	Security best practices
025	Migration Strategy	System migration
026	Error Handling	Error patterns
027	Coordination Framework	Multi-agent coordination
028	CODI2 Separation	Component boundaries
029	Server Hub	Central server
030	Document Server	KBaaS
031	Monitor Integration	File system events

By Topic

Most Relevant to T2:

• Storage & Data: ADR-002, ADR-006
• Multi-Tenant: ADR-003, ADR-005
• Monitoring: ADR-008, ADR-016, ADR-031
• AI Integration: ADR-007, ADR-019, ADR-022
• Architecture: ADR-017, ADR-027, ADR-028

Less Relevant (Different Approach):

• Container/K8s: ADR-001, ADR-004
• Deployment: ADR-014, ADR-025
• Collaboration: ADR-015 (theia has built-in)

Source Code Reference

See docs/v4-source-code-reference.md for details on:

• src/frontend-original/ - React frontend (2.6MB)
• src/v4-api-v2/ - Rust/Axum API (432KB)
• src/v4-websocket-gateway/ - WebSocket gateway (104KB)
• Plus 8 more v4 service directories

Document Freshness

Copied: 2025-10-06 from coditect-v4 submodule

ADR Status Indicators:

• ✅ Accepted - Implemented and validated
• 🔄 Superseded - Replaced by newer ADR
• 📝 Proposed - Design only, not implemented
• ⚠️ QA Review - Under quality review

Check each ADR's "Status" section for current state.

Search Tips

Find ADRs by Topic

# FoundationDB patterns
grep -r "FoundationDB\|keyspace" docs/v4-reference/adrs/ -l

# Multi-tenant patterns
grep -r "tenant\|isolation" docs/v4-reference/adrs/ -l

# Authentication flows
grep -r "JWT\|authentication\|authorization" docs/v4-reference/adrs/ -l

# CODI monitoring
grep -r "CODI\|monitoring\|file.*watch" docs/v4-reference/adrs/ -l

Find Agent Documentation

# Agent definitions
ls docs/v4-agents/coditect/

# Agent coordination
grep -r "coordination\|handoff\|session" docs/v4-agents/ -l

Next Steps

1. Read ADR-002 and ADR-006 - FoundationDB patterns for t2
2. Review CODI design - File monitoring architecture
3. Study agent system - Multi-agent coordination patterns
4. Extract FDB schemas - Adapt for theia-based architecture
5. Learn from mistakes - Read "Alternatives Considered" sections

Related Documentation

• V4 Source Code: docs/v4-source-code-reference.md
• T2 Main Guidance: docs/CLAUDE.md
• T2 Architecture: docs/architecture/architecture.md
• T2 ADRs: docs/adr/ (14+ ADRs specific to t2)

---

Remember: V4 documentation is for reference and learning. T2 is building a fundamentally different architecture (theia extensions vs. standalone web app). Use V4 patterns selectively and adapt to theia's paradigm.