Skip to content

README.md

Latest commit

 

History

History
249 lines (167 loc) · 8.27 KB

README.md

File metadata and controls

249 lines (167 loc) · 8.27 KB

Architecture Documentation

Purpose: Technical architecture documentation for the Coding system

Overview

This section contains architectural documentation for developers who need to understand or modify the Coding system's internal structure.

Note: Most system architecture is already covered in other sections:

Architecture Topics

Core Architecture Concepts

Already documented in other sections:

Legacy Architecture Docs

The following architecture files are preserved for reference but have been superseded by the consolidated documentation:

  • agent-agnostic.md - Agent-agnostic design (see System Overview)
  • agent-detection.md - Agent detection implementation details
  • cross-project-knowledge.md - Cross-project knowledge sharing (see Knowledge Management)
  • fallback-services.md - Fallback services for CoPilot integration
  • unified-knowledge-flow.md - Knowledge flow architecture
  • unified-memory-systems.md - Multi-database synchronization
  • unified-system-overview.md - Unified system architecture

These files will be moved to .obsolete/docs/architecture/ during Phase 2H cleanup.

Key Architectural Principles

1. Agent-Agnostic Design

The system supports multiple AI coding assistants through a unified adapter pattern with shared infrastructure:

Agent-Agnostic Architecture - Components

Architecture Layers:

  1. Agent Layer - AI coding assistants (Claude, CoPilot, OpenCode, future agents)
  2. Tmux Wrapper Layer - All agents wrapped in tmux sessions via shared tmux-session-wrapper.sh for unified status bar (with optional pipe-pane capture for non-native agents)
  3. Config Layer - Agent definitions in config/agents/<name>.sh (10-30 lines each)
  4. Orchestration Layer - launch-agent-common.sh handles all shared startup logic (Docker detection, service startup, monitoring, session management)
  5. Common Setup Layer - Shared initialization (agent-common-setup.sh) for LSL, monitoring, gitignore
  6. Shared Services - VKB, Semantic Analysis, Constraint Monitor, LSL
  7. Adapter Layer - Abstract interface + agent implementations (dynamic import by convention)

Benefits:

  • No vendor lock-in
  • Consistent features across agents
  • Team flexibility

2. Knowledge Persistence

Multi-tier knowledge storage for reliability and performance:

Runtime (Fast):
- MCP Memory (Claude)
- Graphology Graph (CoPilot)

Persistence (Reliable):
- shared-memory-*.json (git-tracked)
- .specstory/history/*.md (session logs)

3. Real-Time Quality Enforcement

PreToolUse hooks intercept tool calls BEFORE execution:

Claude attempts tool → PreToolUse Hook → Constraint Monitor
                                        ↓
                                    Violation? → Block
                                        ↓
                                       No → Allow

4. Monitoring & Observability

4-layer health monitoring with progressive escalation:

Layer 4: Service-Level Health (ukb, vkb, semantic-analysis)
Layer 3: System Verifier (LSL, constraints)
Layer 2: System Coordinator (overall health, metrics)
Layer 1: System Watchdog (critical failures, alerts)

Development Patterns

Pattern: Constraint-Based Development

Define constraints before implementation:

constraints:
  - id: no-parallel-versions
    pattern: /(v\d+|enhanced|improved|new|fixed)_/
    severity: CRITICAL
    message: Never create parallel versions - edit originals

Pattern: Agent Detection

Automatic detection with fallback:

const detector = new AgentDetector();
const available = await detector.detectAll();
// { claude: true, copilot: false }

const best = await detector.getBest();
// 'claude'

Pattern: Knowledge Capture

Structured insight capture:

# Auto-analysis from git commits
ukb

# Structured interactive capture
ukb --interactive

# Visualization
vkb

Adding New Agents

Adding a new agent requires only a single config file — zero changes to shared code.

Agent Integration Flow

Minimum integration (1 file):

  1. Create config/agents/<name>.sh defining AGENT_NAME, AGENT_COMMAND, AGENT_REQUIRES_COMMANDS, and optional hook functions

That's it. Agent detection, launcher routing, and tmux wrapping all happen automatically.

Optional enhancements:

  • lib/agent-api/adapters/<name>-adapter.js — for programmatic API access (memory, browser, logging)
  • scripts/launch-<name>.sh — thin wrapper if you need to customize sourcing order

Proof: The OpenCode agent (config/agents/opencode.sh) is a 25-line file that provides full integration with zero shared code changes.

See the Agent Integration Guide for detailed instructions and API contract.

Deployment Modes

The Coding system supports two deployment modes:

Native Mode (Default)

MCP servers run as native stdio processes, started and managed by Claude CLI:

  • Pros: Simple setup, no Docker required, lower memory footprint
  • Cons: Processes restart with each session
  • Best for: Individual developers, single-machine setups

Docker Mode (Containerized)

MCP servers run as HTTP/SSE services in Docker containers:

Docker Architecture

Architecture:

  • Host: Claude CLI + lightweight stdio proxies
  • Container: MCP SSE servers (semantic-analysis:3848, constraint-monitor:3849, code-graph-rag:3850)
  • Databases: Qdrant:6333, Redis:6379, Memgraph:7687

Pros:

  • Persistent services across sessions
  • Shared browser automation across parallel Claude sessions
  • Better resource isolation
  • Easy database management

Cons: Docker required, slightly higher memory footprint

Best for: Teams, multi-session workflows, CI/CD environments

Enable Docker mode:

# Create marker file
touch .docker-mode

# Or set environment variable
export CODING_DOCKER_MODE=true

# Start services
coding --claude

See docker/README.md for detailed Docker deployment instructions.

Architecture Diagrams

Key architecture diagrams are located in docs/puml/:

  • Docker Architecture - puml | png
  • Agent-Agnostic Architecture (Components) - puml | png
  • Agent-Agnostic Architecture (Sequence) - puml | png
  • Agent Integration Flow - puml | png
  • 4-Layer Monitoring - puml
  • LSL Classification - puml
  • Constraint Monitor - puml

Additional diagrams available in docs/puml/:

  • 4-layer-monitoring-architecture.png - Health monitoring layers
  • lsl-4-layer-classification.png - LSL classification system
  • constraint-monitor-components.png - Constraint monitoring architecture
  • status-line-system.png - Status line architecture
  • statusline-architecture.png - Detailed status line flow

All diagrams have corresponding PlantUML sources in docs/puml/.

See Also