> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture map

> Detailed map of Clawb system architecture, trust boundaries, control-plane flows, and data domains.

This document maps the current Clawb system architecture from the codebase.

## How to view visually

* GitHub: open this file in the repository UI (Mermaid renders automatically).
* VS Code: open this file and use Markdown Preview (`Cmd/Ctrl + Shift + V`).
* Mermaid Live Editor: copy/paste any diagram block into [https://mermaid.live](https://mermaid.live).

## 1) System Context

<CodeGroup>
  ```mermaid Mermaid theme={null}
  flowchart LR
    subgraph Human Boundary
      U[Enterprise operator]
      B[Browser]
    end

    subgraph App Boundary
      SITE[clawb.ai site]
      DASH[app.clawb.ai dashboard SPA]
    end

    subgraph Clawb Control Plane
      API[api.clawb.ai\nDjango + DRF]
      DB[(Postgres)]
      MAIL[Email backend]
      CRON[Status cron runner]
    end

    subgraph Agent Boundary
      AGENT[Agent runtime]
      SVC[Enterprise service/gateway]
    end

    subgraph External Boundary
      EXT[External APIs + SaaS]
    end

    U --> B
    B --> SITE
    B --> DASH

    DASH -->|magic-link session auth| API
    API --> DB
    API --> MAIL
    CRON --> API

    AGENT -->|signed request| SVC
    SVC -->|API key auth| API
    SVC --> EXT
    API --> EXT
  ```
</CodeGroup>

### Auth and trust boundaries

| Caller                     | Main auth mode                                                            | Primary endpoints                                                         |
| -------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Dashboard user (browser)   | Session cookie (magic link login)                                         | `/auth/*`, `/v1/workspaces`, `/v1/agents`, `/v1/policies`, `/v1/vault/*`  |
| Enterprise backend/gateway | Workspace API key                                                         | `/v1/check`, `/v1/workspace/*`, `/v1/identity/*`                          |
| Agent runtime              | Signature + nonce/timestamp via relying service or signed agent endpoints | `/v1/verify`, `/v1/telemetry/heartbeat`, vault signed endpoints           |
| Public approval links      | Opaque one-time tokens                                                    | `/v1/approval-links/*`, `/v1/agent-approval/*`, `/v1/policy-challenges/*` |

## 2) End-to-End Decision Loop (Verify + Policy)

<CodeGroup>
  ```mermaid Mermaid theme={null}
  sequenceDiagram
    participant Agent
    participant Gateway as Enterprise Gateway
    participant Clawb as Clawb API
    participant Human as Approver
    participant Target as Target Service

    Agent->>Gateway: Request + signature + nonce + timestamp
    Gateway->>Clawb: POST /v1/verify
    Clawb-->>Gateway: valid/invalid + identity context

    Gateway->>Clawb: POST /v1/check (action + context)
    alt allow
      Clawb-->>Gateway: decision=allow
      Gateway->>Target: execute action
    else challenge
      Clawb-->>Gateway: decision=challenge + challenge_id
      Human->>Clawb: approve/deny challenge link
      Gateway->>Clawb: re-check or poll decision
      Clawb-->>Gateway: allow or deny
    else deny
      Clawb-->>Gateway: decision=deny + reason_codes
    end
  ```
</CodeGroup>

## 3) Vault + JWT Credential Path

<CodeGroup>
  ```mermaid Mermaid theme={null}
  sequenceDiagram
    participant Admin as Dashboard Admin
    participant Clawb as Clawb API
    participant Agent
    participant External as External API

    Admin->>Clawb: Configure secret sets, versions, grants
    Agent->>Clawb: POST /v1/vault/leases/workflow
    Clawb-->>Agent: workflow lease token

    Agent->>Clawb: POST /v1/vault/leases/request/mint
    Clawb-->>Agent: short-lived request lease

    Agent->>Clawb: POST /v1/identity/credentials/mint
    Clawb-->>Agent: short-lived JWT/opaque credential

    Agent->>Clawb: POST /v1/vault/proxy/request (or /secrets/read)
    Clawb->>External: proxied call with injected secret/temporary credential
    External-->>Clawb: response
    Clawb-->>Agent: response + audit trace

    Note over Clawb: Revocation + kill switch can pause minting\nor revoke credential windows quickly.
  ```
</CodeGroup>

## 4) Control Plane Domains

<CodeGroup>
  ```mermaid Mermaid theme={null}
  flowchart TD
    subgraph Auth & Workspace
      L1[POST /auth/start-login] --> L2[Email magic link]
      L2 --> L3[GET/POST /auth/verify-login]
      L3 --> L4[Session cookie + active workspace in session]
      L4 --> L5[GET /auth/me]
      L5 --> L6[GET/POST /v1/workspaces]
      L6 --> L7[POST /v1/workspaces/select]
    end

    subgraph Agent Identity & Policy
      R1[POST /v1/agents/register] --> R2[Agent row + key + challenge]
      R2 --> R3[POST /v1/agents/attest]
      R3 --> R4[Agent active]
      A1[POST /v1/verify] --> P1[Signature + nonce + key checks]
      A2[POST /v1/check] --> P2[Policy eval allow/challenge/deny]
      P2 --> P3[PolicyChallenge + approval links if challenge]
    end

    subgraph Credential & Token
      T1[POST /v1/identity/credentials/mint] --> T2[AgentMintedCredential]
      T3[POST /v1/identity/credentials/revoke] --> T2
      T4[POST /v1/token/exchange] --> T5[Scoped token claims]
      T6[Kill switch endpoints] --> T2
    end

    subgraph Vault
      V1[POST /v1/vault/secret-sets] --> V2[Secret set + versions]
      V3[POST /v1/vault/grants] --> V4[Access grants]
      V5[POST /v1/vault/leases/workflow] --> V6[Workflow lease]
      V7[POST /v1/vault/leases/request/mint] --> V8[Request lease]
      V9[POST /v1/vault/secrets/read or /v1/vault/proxy/request] --> Ext2[Target API]
    end

    subgraph Status & Contact
      S1[GET status summary + checks + errors] --> S2[Status page /status]
      S3[POST /v1/status/checks/run or cron command] --> S4[StatusCheck rows]
      C1[POST /v1/contact/submit] --> C2[ContactSubmission + notify email]
    end
  ```
</CodeGroup>

## 5) Core Data Model Topology

<CodeGroup>
  ```mermaid Mermaid theme={null}
  erDiagram
    USER ||--o{ WORKSPACE : owns
    WORKSPACE ||--o{ AGENT : contains
    AGENT ||--o{ AGENT_KEY : has
    WORKSPACE ||--o{ POLICY : owns
    POLICY ||--o{ POLICY_VERSION : versions
    WORKSPACE ||--o{ WORKSPACE_API_KEY : has
    WORKSPACE ||--o{ POLICY_CHALLENGE : emits
    AGENT ||--o{ AGENT_MINTED_CREDENTIAL : mints
    WORKSPACE ||--o{ VAULT_SECRET_SET : owns
    VAULT_SECRET_SET ||--o{ VAULT_SECRET_SET_VERSION : versions
    AGENT ||--o{ VAULT_ACCESS_GRANT : receives
    WORKSPACE ||--o{ AUDIT_EVENT : logs
    WORKSPACE ||--o{ STATUS_COMPONENT : monitors
    STATUS_COMPONENT ||--o{ STATUS_CHECK : records
  ```
</CodeGroup>