graph TB
    subgraph "Client Layer"
        UI["🌐 Web UI<br/>(Roadmap + Kanban)"]
        CA["🤖 Claude Session A<br/>(MCP Client)"]
        CB["🤖 Claude Session B<br/>(MCP Client)"]
        CC["🤖 Claude Session C<br/>(MCP Client)"]
    end

    subgraph "PeerCode Server"
        REST["🔌 REST API<br/>/api"]
        MCP["📡 MCP Server<br/>/mcp"]
        WS["⚡ WebSocket<br/>/ws"]
        BUS["🔄 Event Bus"]

        subgraph "Core Services"
            PS["📋 Project Service"]
            TS["📝 Task Service"]
            LS["🔒 Lock Service"]
            DS["📡 Delta Service"]
            DBS["⚔️ Debate Service"]
            PLN["🧠 Planning Service"]
            SYN["🔄 Sync Service"]
            PRS["👁️ Presence Service"]
        end
    end

    subgraph "Storage Layer"
        CH["💾 ClickHouse<br/>(Event Streams)"]
        MEM["🧠 In-Memory<br/>(Live State Fallback)"]
    end

    subgraph "External Integrations"
        ANTH["🧠 Anthropic API<br/>(Claude)"]
        NIM["🔍 Nimble<br/>(Web Search)"]
        DD["📊 Datadog<br/>(LLM Observability)"]
    end

    UI -->|HTTP| REST
    CA -->|Streamable HTTP| MCP
    CB -->|Streamable HTTP| MCP
    CC -->|Streamable HTTP| MCP
    UI -->|WS| WS
    CA -.->|WS subscribe| WS
    CB -.->|WS subscribe| WS
    CC -.->|WS subscribe| WS

    REST --> BUS
    MCP --> BUS
    BUS --> WS

    PS --> MEM
    TS --> MEM
    LS --> MEM
    DS --> MEM
    DBS --> MEM
    SYN --> MEM
    PLN --> ANTH
    DBS --> NIM

    BUS --> CH
    DS --> CH
    DBS --> CH

    MCP --> DD

sequenceDiagram
    participant A as 🤖 Claude A
    participant S as 🖥️ PeerCode Server
    participant B as 🤖 Claude B

    Note over A,B: 1. Sync Phase — Pull context before work
    A->>S: peercode_get_deltas(projectId)
    S-->>A: { deltas, requiresAction: false }
    A->>S: peercode_lock_file("src/auth.ts", 10-45)
    S-->>A: { lockId, success: true }

    Note over A,B: 2. Work Phase — Push discoveries
    Note over A: Discovers API contract change needed
    A->>S: peercode_push_delta(type: "contract_change", ...)
    S->>B: WS: delta_received 🔔

    Note over A,B: 3. Conflict Phase — Structured debate
    B->>S: peercode_get_deltas()
    S-->>B: { requiresAction: true ⚠️ }
    B->>S: peercode_start_debate(position, constraints)
    S->>A: WS: debate_update 🔔

    loop Debate Rounds (max 5)
        A->>S: peercode_respond_debate(message)
        S->>B: WS: debate_update 🔔
        B->>S: peercode_respond_debate(message)
        S->>A: WS: debate_update 🔔
    end

    Note over A,B: 4. Resolution
    B->>S: peercode_respond_debate(proposeResolution: true)
    S-->>A,B: Debate resolved ✅

    Note over A,B: 5. Sync Phase — Push to git
    A->>S: peercode_sync_github(action: "start")
    S-->>A: { status: "go", pullShas: [...] }
    Note over A: git pull → resolve → git push
    A->>S: peercode_sync_github(action: "complete", commitSha)
    S->>B: WS: sync_complete 🔔

    Note over A,B: 6. Cleanup
    A->>S: peercode_release_lock(lockId)

stateDiagram-v2
    [*] --> TODO
    TODO --> IN_PROGRESS: Assign & start
    IN_PROGRESS --> REVIEW: Work complete
    REVIEW --> MERGE_POINT: Approved
    MERGE_POINT --> DONE: Phase sync barrier reached
    MERGE_POINT --> IN_PROGRESS: Rejected

    note right of MERGE_POINT
        🔒 Contracts locked
        All sessions must sync
        to same peer-progress HEAD
    end note

flowchart LR
    A["🔍 Discovery<br/>by Agent"] --> B["📤 push_delta<br/>to server"]
    B --> C["💾 Stored in<br/>ClickHouse"]
    C --> D["🔔 WS broadcast<br/>to peers"]
    D --> E{"Peer evaluates<br/>conflict?"}
    E -->|No conflict| F["✅ ack_delta<br/>Auto-adapt"]
    E -->|Conflict!| G["⚔️ start_debate<br/>Negotiate"]
    G --> H{"Consensus<br/>reached?"}
    H -->|Yes| I["✅ Resolved<br/>Contract updated"]
    H -->|No, 5 rounds| J["🚨 Escalate<br/>to humans"]