ADR-017-v4: Unified workspace Architecture (Part 1: Narrative)

Document: ADR-017-v4-unified-workspace-architecture-part1-narrative
Version: 3.0.0
Purpose: Define comprehensive unified workspace architecture for human understanding
Audience: Business stakeholders, developers, UX designers
Date Created: 2025-08-29
Date Modified: 2025-09-03
QA Reviewed: Pending
Status: UPDATED_FOR_STATEFULSETS
Supersedes: v2.0.0
Changes: Replaced ephemeral containers with GKE StatefulSets

Table of Contents

• 1. Document Information
• 2. Purpose of this ADR
• 3. User Story Context
• 4. Executive Summary
• 5. Visual Overview
• 6. Background & Problem
• 7. Decision
• 8. Implementation Blueprint
• 9. Testing Strategy
• 10. Security Considerations
• 11. Real-World Scenario
• 12. Performance Characteristics
• 13. Operational Considerations
• 14. Migration Strategy
• 15. Consequences
• 16. References & Standards
• 17. Review & Approval
• 18. Appendix
• 19. QA Review Block

1. Document Information 🔴 REQUIRED

Field	Value
ADR Number	ADR-017
Title	Unified workspace Architecture
Status	Updated for StatefulSets
Date Created	2025-08-29
Last Modified	2025-09-03
Version	3.0.0
Decision Makers	CTO, Lead Architect, UX Director
Stakeholders	Development teams, UX/UI designers, Product managers

2. Purpose of this ADR 🔴 REQUIRED

This ADR serves dual purposes:

• For Humans 👥: Understand how CODITECT provides a complete development environment in a single web interface
• For AI Agents 🤖: Implement a VS Code-like workspace with activity-centric architecture supporting 533 tasks

3. User Story Context 🔴 REQUIRED

As a developer,
I want all my development tools in one unified interface with persistent workspaces,
So that I can work efficiently without context switching or losing state.

As an AI orchestrator,
I want structured workspace interfaces,
So that I can automate development tasks programmatically.

As a team lead,
I want real-time visibility into project progress,
So that I can track work across human and AI contributors.

📋 Acceptance Criteria:

• VS Code-like interface with familiar keybindings
• Support for 533 YAML task files
• Real-time collaboration features
• Virtual scrolling for millions of log entries
• Responsive design for various screen sizes
• < 5 second workspace ready time (including StatefulSet pod startup)
• Keyboard-accessible for all features

4. Executive Summary 🔴 REQUIRED

🏢 For Business Stakeholders

Think of CODITECT's workspace like the cockpit of a modern aircraft - every control has a purpose, organized in zones for maximum efficiency. Instead of switching between 12+ different tools (VS Code, GitHub, Jenkins, Jira, Postman), developers get everything in one unified interface with persistent workspaces that survive restarts thanks to GKE StatefulSets.

Business Value:

• 50% reduction in context switching time
• 30% faster task completion
• 80% developer preference over separate tools
• Single authentication point improves security

Key Decision: Implement activity-centric workspace architecture with VS Code familiarity but enhanced for AI-driven development.

💻 For Technical Readers

Technical Summary: React-based workspace using Monaco editor, WebSocket synchronization, virtual scrolling for performance, and plugin architecture for extensibility. Runs in persistent GKE StatefulSet pods with integrated PersistentVolumeClaims for workspace storage. Supports real-time collaboration and AI agent integration.

↑ Back to Top

5. Visual Overview 🔴 REQUIRED

5.1 workspace layout

5.2 Activity Flow

5.3 Real-Time Synchronization

↑ Back to Top

6. Background & Problem 🔴 REQUIRED

6.1 Business Context

The Challenge: Building a Web-Based Development Environment

Why this matters:

• Developer Productivity: Average developer uses 12+ tools daily
• Context Switching: Costs 23 minutes per switch (UC Irvine study)
• Tool Sprawl: $1,200/developer/year in redundant licenses
• Learning Curve: 2-3 weeks onboarding for tool stack

User impact:

• Constant tab switching between tools
• Multiple authentication systems to manage
• Inconsistent keyboard shortcuts
• Lost work due to sync issues

Cost of inaction:

• 2 hours/day lost to context switching
• 15% productivity loss from tool friction
• Higher error rates from manual integration
• Difficult to onboard new team members

6.2 Technical Context

Current state in industry:

• Desktop IDEs (VS Code, IntelliJ) dominate
• Web IDEs limited (Codespaces, Gitpod)
• No unified AI-human workspace
• Task management separate from code
• Log analysis requires specialized tools

Limitations:

• Browser memory constraints
• Network latency for large files
• Limited filesystem access
• WebAssembly still maturing
• Real-time sync complexity

6.3 Constraints

Type	Constraint	Impact
⏰ Time	8-week implementation	Phased rollout required
💰 Budget	Existing team only	Leverage open source
👥 Resources	5 frontend developers	Focus on core features
🔧 Technical	Browser limitations	Creative workarounds
📜 Compliance	WCAG 2.1 AA required	Accessibility first

↑ Back to Top

7. Decision 🔴 REQUIRED

7.1 Y-Statement Format

In the context of providing a complete development environment,
facing tool fragmentation and context switching costs,
we decided for unified activity-centric workspace architecture
and neglected separate tools and desktop-only solutions,
to achieve 50% productivity gain and seamless AI integration,
accepting browser limitations and initial development cost,
because unified experience drives adoption and efficiency.

7.2 What We're Doing

Implementing a comprehensive web-based workspace:

1. Activity-Centric Design

   • Left activity bar for major functions
   • Context-aware sidebar transformations
   • Flexible editor arrangements
   • Collapsible panel area

2. Core Components

   • File Explorer with drag-drop
   • Monaco editor integration
   • Git workflow UI
   • Task Runner for 533 YAMLs
   • AI Agent Monitor
   • Log Viewer with virtual scrolling

3. Performance Optimizations

   • Virtual scrolling for large datasets
   • Web Workers for heavy computation
   • IndexedDB for local caching
   • Lazy loading strategies

4. Collaboration Features

   • Real-time cursor sharing
   • Operational Transform for conflicts
   • WebSocket synchronization
   • Session recording/playback

7.3 Why This Approach

Activity-centric design:

• Groups related functionality
• Reduces cognitive load
• Enables muscle memory
• Supports keyboard navigation

VS Code familiarity:

• Reduces learning curve
• Leverages existing skills
• Rich ecosystem inspiration
• Proven UX patterns

This approach balances:

• Power vs simplicity
• Flexibility vs structure
• Performance vs features
• Innovation vs familiarity

7.4 Alternatives Considered 🟡 OPTIONAL

Option A: Traditional Multi-Page Application

Aspect	Details
Description	Separate pages for each tool function
✅ Pros	• Simple implementation • Lower memory usage • SEO friendly
❌ Cons	• Constant page reloads • Lost context on navigation • Poor user experience
Rejection Reason	Context switching defeats productivity goals

Option B: Desktop Electron App

Aspect	Details
Description	Native desktop application using Electron
✅ Pros	• Full filesystem access • Native performance • OS integration
❌ Cons	• Installation required • Platform-specific builds • Update distribution
Rejection Reason	Against zero-installation philosophy

↑ Back to Top

8. Implementation Blueprint 🔴 REQUIRED

8.1 Architecture Overview

8.2 Core Components

Activity Bar: Navigation hub for workspace functions. See Part 2 - To be created for implementation.

Sidebar System: Dynamic panels that transform based on activity. Complete code in Part 2 - To be created.

editor Area: Flexible editor groups with Monaco integration. Technical details in Part 2 - To be created.

Panel Area: Collapsible bottom panel for outputs. Implementation in Part 2 - To be created.

8.3 The Architecture: Activity-Centric Design

1. The Activity Bar (The Pilot's Quick Access Panel)

Just like preset radio stations in your car, the Activity Bar provides one-click access to major functions. Each workspace runs in its own persistent GKE StatefulSet pod, ensuring your environment is always ready:

[📁] Explorer      - Browse and manage files
[🔍] Search        - Find anything, anywhere
[🌿] Git           - Version control at your fingertips
[▶️] Tests         - Run and monitor test suites
[🤖] AI Agents     - Orchestrate your AI workforce
[📦] Tasks         - Manage 533 YAML tasks
[📊] Logs          - Real-time system monitoring

Each icon can show badges: "3" untracked files in Git, "!" for failing tests, "LIVE" for active monitoring.

2. The Sidebar (The Navigator)

When you click an activity, the sidebar transforms:

• File Explorer: Drag-drop files, create folders, just like your OS
• Search Panel: Global search with regex, fuzzy matching, file filters
• Git Panel: Stage, commit, push without leaving the interface
• Test Runner: Tree view of all tests with real-time results
• Agent Monitor: See which AI agents are working on what
• Task Manager: 533 tasks organized by phase with progress tracking

3. The editor Area (The workspace)

This is where the magic happens. But unlike traditional IDEs limited to code, and unlike ephemeral containers that lose state, your workspace persists across sessions thanks to PersistentVolumeClaims:

Multi-Format Editing (All state preserved in PersistentVolumes):

• Code Files: Full Monaco editor with IntelliSense
• ADR Documents: Split-pane editor for Narrative and Technical parts
• YAML Tasks: Visual editor with validation
• Dashboards: Real-time metrics and charts
• terminals: Multiple persistent terminal sessions (survive pod restarts)
• Log Viewers: Stream millions of entries with virtual scrolling

Advanced layouts:

• Split editors horizontally or vertically
• Tab groups for organizing related files
• Picture-in-picture for monitoring while coding
• Zen mode for distraction-free writing

4. The Panel Area (Mission Control)

The bottom panel provides real-time feedback:

• Integrated terminal: Not just one, but multiple terminal sessions
• Problems: Compilation errors, linting issues, test failures
• Output: Build logs, deployment status, agent activity
• Debug Console: Step through code execution
• CODI Logs: Every file operation tracked and attributed

5. The Status Bar (The HUD)

Critical information always visible:

• Project status: "42.5% complete"
• AI agents: "4/7 active"
• Build time: "2-4 min"
• Git branch: "main"
• Language mode: "TypeScript"
• Encoding: "UTF-8"

8.4 Configuration

All workspace configuration managed through:

• User preferences in IndexedDB (browser cache)
• workspace settings in FoundationDB (global state)
• File system state in PersistentVolumes (workspace persistence)
• Theme definitions in JSON
• Keyboard shortcuts customizable

See Part 2 - To be created for schemas.

8.5 API Endpoints

Endpoint	Method	Purpose
/workspace/layout	GET/PUT	Save/restore layout
/workspace/preferences	GET/PUT	User preferences
/workspace/files	GET	File tree structure
/workspace/search	POST	Global search
/workspace/sync	WebSocket	Real-time sync

8.6 Logging Requirements

All workspace events must be logged:

• User actions with timestamps
• Performance metrics
• Error conditions
• AI agent interactions
• Collaboration events

Detailed patterns in Part 2 - To be created.

8.7 Error Handling

workspace errors must:

• Show user-friendly messages
• Provide recovery options
• Log detailed diagnostics
• Maintain workspace stability

See Part 2 - To be created for implementation.

↑ Back to Top

9. Testing Strategy 🔴 REQUIRED

9.1 Test Scenarios

1. Component Tests

   • Activity bar navigation
   • Sidebar panel switching
   • editor group management
   • Panel resize/collapse
   • Status bar updates

2. Integration Tests

   • File open/save flow
   • Git operations
   • Task execution
   • Search functionality
   • Real-time sync

3. Performance Tests

   • 1000 file tree rendering
   • 1M log entry scrolling
   • 50 concurrent users
   • Large file editing
   • Memory leak detection

9.2 Performance Benchmarks

Test	Target	Method
Initial load	<3 sec	Lighthouse
File open	<100ms	Performance API
Search results	<500ms	End-to-end
Log filter	<200ms	Virtual scroll

9.3 Test Coverage Requirements

Component	Unit	Integration	E2E
Activity Bar	≥90%	≥80%	≥70%
editor Area	≥95%	≥85%	≥75%
File Explorer	≥90%	≥80%	≥70%
Sync Engine	≥95%	≥90%	≥80%

↑ Back to Top

10. Security Considerations 🔴 REQUIRED

10.1 Authentication & Authorization

Multi-layered security:

• JWT tokens with workspace context
• Role-based access control (RBAC)
• Fine-grained permissions per activity
• Session timeout management
• SSO integration support

10.2 Data Protection

Client-side security:

• All API calls over HTTPS
• Content Security Policy (CSP)
• XSS protection mechanisms
• Input sanitization
• Encrypted IndexedDB storage

10.3 Threat Model

Threat	Likelihood	Impact	Mitigation
XSS attacks	Medium	High	CSP, sanitization
CSRF attacks	Low	High	CSRF tokens
Data leakage	Medium	Critical	Encryption, access control
Session hijacking	Low	High	Secure cookies, timeout

↑ Back to Top

11. Real-World Scenario: A Day with CODITECT

8:00 AM - Starting the Day Sarah opens CODITECT. Her workspace StatefulSet pod is already running (it persisted from yesterday), so she's instantly back where she left off - same terminal sessions, same file tabs, same layout. The dashboard shows overnight AI agent activity. ORCHESTRATOR completed 3 tasks while she slept. She clicks the notification badge on the Git activity - the AI agents have created a PR for review.

9:00 AM - Specification Writing She opens ADR-018 in the split-pane editor. The left shows her narrative in plain English, the right shows the technical specification. As she types, real-time validation ensures her ADR meets the 100% quality score.

10:00 AM - Code Review The Git panel shows changes from the AI agents. She reviews the diff directly in the editor, makes comments, and approves the PR - all without leaving CODITECT.

11:00 AM - Task Execution She drags a YAML task file from the explorer to the Task Runner. It executes with real-time progress, logs streaming in the panel below. When it fails, she clicks the error to jump directly to the problematic line.

2:00 PM - Debugging A test is failing. She opens the Test Viewer, sees the failure stack trace, clicks to open the file, sets a breakpoint, and runs the debugger - all in the same interface.

3:00 PM - Monitoring She switches to the Logs activity. The log viewer shows 1.5 million entries from today. Using virtual scrolling, she filters by "ERROR", finds an issue, and creates a task for the AI agents to fix it. Even if her pod restarts, all her filtered views and scroll positions are preserved in the PersistentVolume.

4:00 PM - Collaboration Her teammate needs help. She starts a CodeTogether session, sharing her entire workspace. They pair program on the ADR, seeing each other's cursors in real-time.

↑ Back to Top

12. Performance Characteristics 🔴 REQUIRED

12.1 Expected Metrics

Operation	Target	Actual	Notes
workspace ready	<5 sec	TBD	StatefulSet pod startup
File open	<100ms	TBD	Cached in PersistentVolume
Tab switch	<16ms	TBD	60 FPS target
Search	<500ms	TBD	Web Worker search
Log scroll	60 FPS	TBD	Virtual scrolling
State restore	<1 sec	TBD	From PersistentVolume

12.2 Scalability

Horizontal scaling:

• CDN for static assets
• WebSocket load balancing
• Stateless API servers
• Read replicas for search
• GKE Autopilot auto-scaling
• Spot instance usage for 80% cost savings

Client optimizations:

• Code splitting by route
• Lazy loading components
• Service Worker caching
• PersistentVolume for workspace state
• IndexedDB for browser-side cache

12.3 Technical Challenges Solved

Performance at Scale:

• Virtual scrolling for millions of items
• Web Workers offload computation
• IndexedDB for offline capability
• Progressive loading strategies

Real-Time Synchronization:

• WebSocket with reconnection
• Operational Transform algorithms
• Event sourcing architecture
• Optimistic UI with rollback

Bottlenecks:

• Browser memory limits (~2GB)
• WebSocket connection limits
• IndexedDB storage quotas
• Main thread blocking

↑ Back to Top

13. Operational Considerations 🔴 REQUIRED

13.1 Monitoring

Metric	Alert Threshold	Action
Load time	>5 sec	Check bundle size
Memory usage	>1GB	Investigate leaks
WebSocket drops	>5/min	Check connection
Error rate	>1%	Review logs

13.2 Maintenance

Regular tasks:

• Update Monaco editor monthly
• Clear old IndexedDB data
• Review extension compatibility
• Performance profiling
• Accessibility audits

13.3 Emergency Procedures

High memory usage:

1. Identify memory leaks
2. Force garbage collection
3. Restart affected services
4. Clear browser cache

WebSocket failures:

1. Fallback to polling
2. Queue offline changes
3. Sync when reconnected
4. Notify users of status

↑ Back to Top

14. Migration Strategy 🔴 REQUIRED

14.1 Phase 1: Core Framework (Weeks 1-2)

• Activity bar navigation
• Basic sidebar panels
• editor tab management
• Status bar framework

14.2 Phase 2: Essential Features (Weeks 3-4)

• File Explorer implementation
• Monaco editor integration
• Git panel basic operations
• terminal multiplexing

14.3 Phase 3: Advanced Features (Weeks 5-6)

• Task Runner UI
• AI Agent Monitor
• Log Viewer with virtual scroll
• Test Runner integration

14.4 Phase 4: Polish & Performance (Weeks 7-8)

• Keyboard shortcut system
• Settings synchronization
• Theme customization
• Performance optimization

14.5 Rollback Plan

If issues arise:

1. Maintain legacy UI in parallel
2. Feature flag new workspace
3. Gradual user migration
4. Quick fallback option

↑ Back to Top

15. Consequences 🔴 REQUIRED

15.1 Positive Outcomes

✅ Productivity gains:

• 50% reduction in context switching
• 30% faster task completion
• Single source of truth
• Unified keyboard shortcuts

✅ Developer satisfaction:

• Familiar VS Code interface
• Customizable workspace
• Integrated AI assistance
• Real-time collaboration

✅ Business benefits:

• Reduced tool licensing costs
• Simplified onboarding
• Better security posture
• Complete audit trails

15.2 Negative Impacts

⚠️ Technical challenges:

• Browser memory constraints
• Network dependency
• Complex state management
• Performance optimization needs

⚠️ Development effort:

• 8-week initial build
• Ongoing maintenance
• Extension compatibility
• Cross-browser testing

⚠️ User adjustment:

• Learning new interface
• Migration from desktop tools
• Potential feature gaps
• Internet requirement

↑ Back to Top

16. References & Standards 🔴 REQUIRED

16.1 Related ADRs

• ADR-001-v4: Container architecture for workspaces
• ADR-003-v4: Multi-tenant isolation
• ADR-009-v4: CODI interface integration
• ADR-016-v4: Backend services

16.2 External Standards

• WCAG 2.1: Accessibility guidelines
• Material Design: UI/UX patterns
• Monaco editor: editor framework
• VS Code API: Extension architecture

16.3 Best Practices

• React Best Practices: Component patterns
• Web Performance: Optimization techniques
• WebSocket Protocol: Real-time communication

↑ Back to Top

17. Review & Approval 🔴 REQUIRED

Approval Signatures

Role	Name	Date	Signature
CTO	_______	_______	___________
Lead Architect	_______	_______	___________
UX Director	_______	_______	___________
Engineering Manager	_______	_______	___________

Review History

Version	Date	Reviewer	Status	Comments
1.0.0	2025-08-29	Initial	DRAFT	Original version
2.0.0	2025-09-01	SESSION4	DRAFT	Complete rewrite to v4.2
3.0.0	2025-09-03	DOCUMENT-DEV-2	UPDATED	Replaced ephemeral containers with GKE StatefulSets

Approval Workflow

↑ Back to Top

18. Appendix

18.1 Glossary

Term	Definition
Activity Bar	Left navigation panel for major functions
Monaco editor	VS Code's editor component for web
Virtual Scrolling	Rendering only visible items for performance
Operational Transform	Algorithm for real-time collaboration
IndexedDB	Browser database for offline storage
Web Workers	Background threads for heavy computation
WASM	WebAssembly for near-native performance
PWA	Progressive Web App capabilities
CDN	Content Delivery Network for assets
OT	Operational Transform for conflict resolution

18.2 Comparison Matrix

Feature	VS Code	GitHub Codespaces	CODITECT workspace
Code Editing	✅ Excellent	✅ Good	✅ Excellent
Task Management	❌ Extensions only	❌ Limited	✅ Built-in
AI Integration	⚠️ Copilot only	⚠️ Copilot only	✅ Full orchestration
Test Runner	⚠️ Extension-based	⚠️ Extension-based	✅ Native
Log Analysis	❌ Basic	❌ Basic	✅ Advanced
ADR Editing	❌ No	❌ No	✅ Specialized
Multi-tenant	❌ No	⚠️ workspace-based	✅ Full isolation

18.3 Success Metrics

Performance targets:

• Initial load: < 3 seconds
• File open: < 100ms
• Search results: < 500ms
• Log filtering: < 200ms for 1M entries

Usability goals:

• 90% of actions within 2 clicks
• 100% keyboard navigable
• Mobile responsive for tablets
• WCAG 2.1 AA compliant

↑ Back to Top

19. QA Review Block

Status: AWAITING INDEPENDENT QA REVIEW

This section will be completed by an independent QA reviewer according to ADR-QA-REVIEW-GUIDE-v4.2.

Document ready for review as of: 2025-09-03
Version ready for review: 3.0.0

---

Changes in v3.0.0

• Replaced all references to ephemeral containers with GKE StatefulSets
• Updated workspace persistence model to use PersistentVolumeClaims
• Modified performance targets to reflect StatefulSet pod startup times
• Added GKE Autopilot and Spot instance references for cost optimization
• Updated architecture diagrams to include StatefulSets and PersistentVolumes
• Enhanced real-world scenario to highlight persistent workspace benefits
• Modified by: DOCUMENT-DEV-2 (SESSION14) on 2025-09-03

---

Next: See Part 2: Technical Implementation - To be created for complete implementation details.