Architecture Diagrams

Visual guides to AACWorkflow's system architecture, task lifecycle, security boundaries, and agent collaboration flows.

Reference diagrams for AACWorkflow's architecture, task dispatch, security model, and agent collaboration patterns.

System Architecture

AACWorkflow Cloud connects a web UI, agents running on user machines via daemons, and a central backend.

graph TB
    subgraph cloud ["AACWorkflow Cloud"]
        api["API Server<br/>(Go + PostgreSQL)"]
        ws["WebSocket<br/>Real-time Updates"]
        auth["Auth Service<br/>(OAuth, PAT)"]
    end

    subgraph local ["User Machine (Local Runtime)"]
        daemon["Daemon<br/>(Long-running)"]
        ai["AI Coding Tool<br/>(Claude Code, Cursor, etc.)"]
        cwd["Code Directory<br/>(Git repo)"]
    end

    subgraph ui ["Web UI"]
        board["Issue Board"]
        settings["Settings &<br/>Member List"]
        comments["Comments"]
    end

    board -->|assign issue| api
    api -->|dispatch task| ws
    ws -->|task event| daemon
    daemon -->|poll every 30s| api
    daemon -->|invoke| ai
    ai -->|read/write| cwd
    ai -->|report result| daemon
    daemon -->|upload result| api
    api -->|update| ws
    ws -->|refresh| board
    settings -->|create agent| api
    comments -->|post comment| api
    auth -.->|verify PAT| daemon
    auth -.->|verify session| ui

Key flows:

Task dispatch: Issue assignment → API → WebSocket → Daemon (within 30 seconds)
Execution: Daemon invokes AI tool locally; tool reads code, runs commands, edits files
Result upload: Agent reports completion to API; WebSocket notifies web UI in real-time
Auth boundary: PAT (personal access token) for daemon; session cookies for web UI

Task Lifecycle

A task moves through distinct states from creation to completion, with retries and webhooks along the way.

graph LR
    queued["📋 Queued<br/>(Issue created)"]
    dispatched["🚀 Dispatched<br/>(Daemon picked it up)"]
    running["⚙️ Running<br/>(AI tool executing)"]
    completed["✅ Completed<br/>(Result uploaded)"]
    failed["❌ Failed<br/>(Error or timeout)"]
    retry["🔄 Retrying<br/>(Automatic retry)"]

    queued -->|daemon polls| dispatched
    dispatched -->|daemon invokes AI| running
    running -->|success| completed
    running -->|error| failed
    failed -->|retry policy| retry
    retry -->|running| running
    retry -->|final failure| failed

    completed -->|webhook| slack["Slack Notification"]
    failed -->|webhook| slack

State timing:

Queued → Dispatched: ≤ 30 seconds (daemon poll interval)
Dispatched → Running: ≤ 5 seconds (AI tool startup)
Running duration: seconds to hours (depends on task complexity)
Failed → Retry: configurable backoff (exponential by default)

Security & Trust Boundary

AACWorkflow enforces clear boundaries between cloud, daemon, and local execution.

graph TB
    subgraph cloud ["AACWorkflow Cloud<br/>(Fully Trusted)"]
        api["API<br/>(Manages auth, dispatch,<br/>webhooks)"]
        db["PostgreSQL<br/>(Stores issues, agents,<br/>audit logs)"]
    end

    subgraph untrusted ["User Machine<br/>(Partially Trusted)"]
        daemon["Daemon<br/>(Runs with user<br/>permissions)"]
        ai["AI Tool<br/>(Untrusted execution<br/>context)"]
        code["Code Directory<br/>(All code readable<br/>by AI tool)"]
    end

    subgraph external ["External Services<br/>(OAuth, Git, Webhooks)"]
        github["GitHub"]
        slack["Slack"]
    end

    api -->|PAT validation| daemon
    api -->|task dispatch| daemon
    daemon -->|result telemetry| api
    api -->|webhook| slack
    api -->|API| github
    ai -->|fork + exec| code
    daemon -->|invoke + stream| ai

    style cloud fill:#90EE90
    style untrusted fill:#FFB6C1
    style external fill:#ADD8E6

Trust assumptions:

Cloud API: No user input is trusted without validation; all code is safe by default
Daemon: Runs locally under user's OS permissions; has network-only access to cloud API
AI tool: Executes under daemon's OS user; has read/write access to code directory; may execute arbitrary commands
External services: GitHub/Slack webhooks are rate-limited and validated

Agent Skills & Capability Model

Agents can be enhanced with skills — pre-packaged instructions, tools, and context — to handle specialized tasks.

graph TB
    subgraph agent ["Agent"]
        name["Name & Provider<br/>(Claude Code, Cursor, etc.)"]
        model["Model Selection<br/>(gpt-4, claude-opus, etc.)"]
        instructions["Custom Instructions<br/>(System prompt)"]
    end

    subgraph skills ["Skills (Optional)"]
        skill1["Skill: Frontend<br/>React + Next.js<br/>guidelines"]
        skill2["Skill: Backend<br/>Go + sqlc<br/>patterns"]
        skill3["Skill: DevOps<br/>Terraform +<br/>Kubernetes"]
    end

    subgraph context ["Runtime Context"]
        files["Code Directory<br/>(Git repo)"]
        tools["Local Tools<br/>(git, npm, go,<br/>make, etc.)"]
        secrets["Env Vars & Secrets<br/>(API keys,<br/>credentials)"]
    end

    agent -->|attached to| skills
    agent -->|runs with| context
    skills -->|loaded before| instructions
    name -->|determines| model

    style skills fill:#FFE4B5

Skill loading:

Daemon loads skill content into agent's system prompt
Skill context (docs, guidelines, examples) precedes user task
Agent uses context to make better decisions (no need for explicit tool calls)
Skills stack — multiple skills on one agent combine their context

Squad Delegation

Squads are teams of agents led by a squad lead. Incoming issues can be automatically routed to the right agent based on labels, components, or keywords.

graph TB
    subgraph squad ["Squad: Backend"]
        lead["🏆 Squad Lead<br/>(Routes issues)"]
        agent1["Agent: Go Expert<br/>(sqlc, handlers)"]
        agent2["Agent: Testing<br/>(unit tests, mocks)"]
        agent3["Agent: DevOps<br/>(migrations, DB)"]
    end

    issue["Incoming Issue<br/>(label: 'backend')"]
    routing["Routing Rule<br/>(Squad + label)"]

    issue -->|matches| routing
    routing -->|dispatches to| squad
    lead -->|decides| agent1
    lead -->|or| agent2
    lead -->|or| agent3

    style squad fill:#E6E6FA
    style lead fill:#FFD700

When to use squads:

Multiple agents with different expertise (frontend, backend, QA, DevOps)
Automatic routing rules (e.g., "all backend/* labels → Backend squad")
Clear ownership and accountability
Reduce context switching by keeping agents focused

Autopilot Trigger Flow

Autopilots watch for events (issue creation, PR comments, etc.) and dispatch matching tasks automatically — no manual assignment needed.

graph TB
    subgraph event ["Events"]
        new_issue["New Issue Created"]
        pr_comment["PR Comment Posted"]
        schedule["Scheduled Time"]
    end

    subgraph rules ["Autopilot Rules"]
        rule1["Rule: New Issues<br/>with label 'bug'<br/>→ QA Agent"]
        rule2["Rule: PR Comment<br/>mentioning @bot<br/>→ Code Reviewer"]
        rule3["Rule: Daily 9am<br/>→ Digest Agent"]
    end

    subgraph dispatch ["Dispatch"]
        queue["Task Queue"]
        daemon["Daemon picks up<br/>(within 30s)"]
    end

    new_issue -->|event| rule1
    pr_comment -->|event| rule2
    schedule -->|event| rule3
    rule1 -->|matches| queue
    rule2 -->|matches| queue
    rule3 -->|matches| queue
    queue -->|poll| daemon

    style event fill:#E0FFFF
    style rules fill:#FFFACD
    style dispatch fill:#F0F8FF

Autopilot use cases:

Auto-assign bugs to QA squad for regression testing
Auto-draft release notes from merged PRs
Periodic tasks (daily health checks, weekly summaries)
Route all Terraform diffs to DevOps agent

Data Flow: Issue → Agent → PR → Resolution

End-to-end flow showing how an issue moves through assignment, execution, and PR linking.

sequenceDiagram
    participant user as User
    participant web as Web UI
    participant api as API Server
    participant daemon as Daemon
    participant ai as AI Tool
    participant code as Code Dir
    participant github as GitHub

    user->>web: Create Issue
    web->>api: POST /issues
    api->>api: Store issue (status: queued)

    user->>web: Assign to Agent
    web->>api: PATCH /issues/:id (assignee)
    api->>api: Dispatch task (status: dispatched)
    api-->>daemon: WebSocket: New task

    daemon->>daemon: Wake up from poll
    daemon->>ai: Invoke AI tool
    ai->>code: Read codebase, run commands

    ai->>ai: Generate solution
    ai->>code: Edit files, commit to branch
    ai->>github: Push branch, create PR

    daemon->>api: POST /tasks/:id/complete (with PR URL)
    api->>api: Update issue status (completed)
    api-->>web: WebSocket: Task complete

    user->>web: Link PR in issue
    web->>api: PATCH /issues/:id (link_pr_url)
    api->>api: Store PR link, sync PR comments

    github->>api: PR merged webhook
    api->>api: Update issue status (resolved)
    api-->>web: WebSocket: Issue resolved

    web-->>user: Show resolved badge

Workspace Multi-Tenancy

Each workspace is an isolated tenant with its own members, agents, issues, and audit logs.

graph TB
    subgraph ws1 ["Workspace: Acme Corp"]
        team1["Members: alice, bob,<br/>agent-backend"]
        issues1["Issues: AAC-1 to AAC-100"]
        agents1["Agents: 3"]
        board1["Board & Views"]
    end

    subgraph ws2 ["Workspace: StartupXYZ"]
        team2["Members: charlie, diana,<br/>agent-full-stack"]
        issues2["Issues: SXY-1 to SXY-50"]
        agents2["Agents: 2"]
        board2["Board & Views"]
    end

    subgraph ws3 ["Workspace: Open Source"]
        team3["Members: eve, frank,<br/>bot-ci, bot-release"]
        issues3["Issues: OS-1 to OS-200"]
        agents3["Agents: 5"]
        board3["Board & Views"]
    end

    db["PostgreSQL<br/>(Shared database<br/>with workspace_id<br/>partition key)"]

    ws1 -.->|workspace_id=1| db
    ws2 -.->|workspace_id=2| db
    ws3 -.->|workspace_id=3| db

Multi-tenancy guarantees:

Every query filters by workspace_id at the database layer
Cross-workspace data leaks are impossible by design
Audit logs track which member made which change in which workspace
Workspaces can be archived, renamed, or deleted independently

Provider Landscape

AACWorkflow integrates with 16 AI coding tools, each running its own model and offering different APIs.

graph TB
    aacw["AACWorkflow<br/>Platform"]

    subgraph claude_ecosystem ["Anthropic Ecosystem"]
        cc["Claude Code<br/>(macOS/Linux)"]
        opus["Model: Claude 3.5 Sonnet<br/>(via API)"]
    end

    subgraph cursor_eco ["Cursor Ecosystem"]
        cursor["Cursor IDE<br/>(macOS/Windows/Linux)"]
        gpt4["Model: GPT-4, Claude<br/>(configurable)"]
    end

    subgraph copilot_eco ["Microsoft Ecosystem"]
        copilot["GitHub Copilot<br/>(VS Code + Visual Studio)"]
        copilot_model["Model: GPT-4 Turbo<br/>(via GitHub)"]
    end

    subgraph others ["Other Providers"]
        hermes["Hermes"]
        antigravity["Antigravity"]
        kimi["Kimi"]
    end

    aacw -->|daemon invokes| cc
    aacw -->|daemon invokes| cursor
    aacw -->|daemon invokes| copilot
    aacw -->|daemon invokes| others
    cc -.->|uses| opus
    cursor -.->|uses| gpt4
    copilot -.->|uses| copilot_model

    style claude_ecosystem fill:#FFE4E1
    style cursor_eco fill:#E0F4FF
    style copilot_eco fill:#F0FFF0

All providers share the same assignment, execution, and result-reporting flow through AACWorkflow.

These diagrams are simplified for clarity. For detailed implementation:

Task lifecycle & retries: See Tasks
Agent creation & skills: See Agents and Skills
Daemon setup & troubleshooting: See Daemon and runtimes
Multi-tenancy & workspace isolation: See Workspaces

On this page