cowork-local/docs/architecture/ADR-001-layered-architecture.md

ADR-001: 4-Tier Clean Architecture for Desktop Local Application

• Status: ACCEPTED / ENFORCED
• Date: 2026-08-21
• Deciders: Team Duy (Tech Lead & AI Runtime), Team Nam (Governance & Automation), Team Hoa (Workspace & Scheduling)
• Target Project: Cowork Local (Cowork-Local BamBOO)

---

1. Context and Problem Statement

Cowork Local is a desktop application written in Python using PySide6 (Qt) and designed for local-first execution. Historically, the codebase suffered from architectural coupling across layers:

1. God-Widget Problem: Monolithic UI widgets (e.g., ui/chat_panel.py >1,800 LOC, ui/co4e_tab.py >1,400 LOC) mixed UI rendering, network I/O, business rules, filesystem operations, and background worker lifecycle.
2. Untestable Business Logic: Core algorithms (model routing, conversation turn management, schedule calculation) were tightly coupled to PySide6 widgets or QTimer, making unit testing in headless CI environments impossible without a graphical display server.
3. Circular Dependencies & Global State Leaks: Uncontrolled module imports (model_pricing.py ↔ usage_tracker.py, agent_security.py ↔ agent_security_alert.py) and mutable global state (state.py::AppContext.active_project_id) caused race conditions in background task runs.

---

2. Decision: 4-Tier Clean Architecture

We enforce a strict 4-Tier Clean Architecture based on the Dependency Inversion Principle:

┌─────────────────────────────────────────────────────────────┐
│                      PRESENTATION                           │
│  (PySide6 Widgets, Dialogs, Qt Signals/Slots, View Models)   │
└──────────────────────────────┬──────────────────────────────┘
                               │ depends on
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                      APPLICATION                            │
│  (Use Case Services, Turn Orchestrators, Route Dispatchers) │
│             *** STRICTLY PURE PYTHON (0 Qt) ***             │
└──────────────────────────────┬──────────────────────────────┘
                               │ depends on
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   DOMAIN & RUNTIME CORE                     │
│  (Entities, Value Objects, Domain Events, Tool Descriptors)  │
│             *** STRICTLY PURE PYTHON (0 Qt) ***             │
└──────────────────────────────▲──────────────────────────────┘
                               │ implemented by
┌──────────────────────────────┴──────────────────────────────┐
│                     INFRASTRUCTURE                          │
│  (LLM Providers, Keyring Secrets, Atomic Persistence, MCP)  │
└─────────────────────────────────────────────────────────────┘

---

3. Layer Definitions and Responsibilities

Tier 1: Presentation Layer (presentation/)

• Responsibilities: UI component layout, user event capture, progress display, visual animations, confirmation dialog triggers.
• Allowed Imports: PySide6.*, application.*, domain.*.
• Forbidden: Direct database queries, raw LLM API calls, disk writes outside UI cache, executing tool commands directly.
• Constraints: Every widget file must strictly be under 400 lines of code (LOC).

Tier 2: Application Layer (application/)

• Responsibilities: Orchestrate single use cases (e.g. ConversationApplicationService, RoutingApplicationService, TaskApplicationService). Convert UI requests into domain requests, coordinate domain services with infrastructure adapters.
• Allowed Imports: domain.*, infrastructure.* interfaces/contracts, standard Python libraries.
• Forbidden: PySide6, PyQt5, PyQt6, ui.*, app.*.
• Nature: 100% Pure Python. Must be executable and testable in headless CI environments without a display driver.

Tier 3: Domain Layer (domain/)

• Responsibilities: Core domain models, frozen DTO snapshots (ConversationExecutionRequest), typed event streams (AgentEvent), descriptors (ToolDescriptor, ProviderDescriptor), deterministic calculation algorithms (ScheduleCalculator).
• Allowed Imports: Standard Python library only (dataclasses, typing, enum, datetime, pathlib, abc).
• Forbidden: PySide6, PyQt*, requests, sqlalchemy, filesystem mutations, OS network calls.
• Nature: Completely isolated and zero-dependency core.

Tier 4: Infrastructure Layer (infrastructure/)

• Responsibilities: Adapters for external systems (OpenAI/Anthropic/Ollama/FPT providers, OS Keyring via SecretStore, AtomicJsonFile persistence, MCP child processes, filesystem tools).
• Allowed Imports: Third-party SDKs, OS libraries, domain.*.
• Forbidden: presentation.*, PySide6.QtWidgets.

---

4. Architectural Rules and Non-Negotiable Invariants

1. Zero Qt in Business Logic:
   • domain/ and application/ must never import PySide6 or PyQt*.
   • Verified via AST parser script scripts/check_imports.py.
2. Immutable Request Snapshots:
   • Turns are initiated using immutable frozen dataclasses (ConversationExecutionRequest) to decouple runtime state from mutable UI state.
3. Thread Safety and Signal Decoupling:
   • AI generation and tool calls run asynchronously in worker threads.
   • UI updates occur strictly on the Qt main thread by consuming AgentEvent streams through Qt Signal bridges.
4. Single Responsibility and Modularity:
   • Production files must stay within 400 LOC.
5. English In-Code Comments:
   • Every modified or created line/block must include concise English comments explaining design decisions and processing logic.

---

5. Consequences and Compliance

• Positive:
  • Full testability: Unit tests run in milliseconds without GUI or network mocks.
  • Zero circular dependencies: Clear top-down data flow.
  • Resilience: UI crashes do not corrupt background tasks or files.
• Verification:
  • Automated CI gate: python scripts/check_imports.py and python scripts/check_loc.py.