# ruvnet/ruclip architecture

> Architecture diagram of the GitHub repository ruvnet/ruclip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruvnet/ruclip
- Repository: https://github.com/ruvnet/ruclip

## Overview

ruClip is a governance control plane for agent-run companies, not an agent framework. The main workflow is to define company, goal, and issue records; authorize employee actions; apply approval transitions; and persist the resulting state. Separate capabilities cover budget-gated heartbeats, notifications, dashboard snapshots, adaptive interaction profiles, human identity attestation, and runtime governance. The graph reflects documented capabilities and indexed module references; unsampled implementation details are not assumed.

Main entry points: [`src/control-plane/store/agentdb-adapter.ts`](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/agentdb-adapter.ts) (AgentDB adapter), [`src/control-plane/authorization/human-identity-attestation.ts`](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/human-identity-attestation.ts) (Human attestation), [`src/control-plane/store/bridge-client.ts`](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/bridge-client.ts) (AgentDB bridge client), [`services/ruclip-attester/src/attest-handler.ts`](https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/attest-handler.ts) (Attestation service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["Company domain"]
  node_schema["Domain schemas"]
  node_validation["Schema validation<br/>[validation.ts]"]
end

subgraph group_governance["Workflow governance"]
  node_approval["Approval transitions"]
  node_budget["Budget mutations"]
  node_autogenous["Autogenous client"]
end

subgraph group_identity["Identity and access"]
  node_claims["Claims authorization"]
  node_attestation["Human attestation"]
  node_credential["Actor credentials"]
  node_issuer["Credential issuer"]
  node_attester["Attestation service<br/>[attest-handler.ts]"]
  node_google["Google token verifier<br/>[google-token.ts]"]
  node_identitymap["Employee identity map<br/>[identity-map.ts]"]
end

subgraph group_operations["Company operations"]
  node_cli["CLI<br/>[ruclip.ts]"]
  node_heartbeat["Budgeted heartbeats<br/>[fire-heartbeat.ts]"]
  node_comms["AgentBBS notifications"]
  node_dashboard["Dashboard snapshot<br/>[build-snapshot.ts]"]
  node_profiles["Interaction profiles"]
end

subgraph group_storage["Persistence and integrations"]
  node_adapter[("AgentDB adapter<br/>[agentdb-adapter.ts]")]
  node_bridge["AgentDB bridge client<br/>[bridge-client.ts]"]
end

node_operator(("Human or agent"))
node_agentdb[("AgentDB")]
node_autogenousservice["Autogenous service"]
node_agentbbs["AgentBBS"]

node_operator -.->|"invokes"| node_cli
node_cli -->|"requests credentials"| node_attestation
node_attester -->|"verifies token"| node_google
node_attester -->|"looks up identity"| node_identitymap
node_attester -->|"mints attestation"| node_attestation
node_attestation -->|"verifies identity"| node_credential
node_attestation -->|"mints credential"| node_issuer
node_attestation -->|"recalls member"| node_adapter
node_attestation -->|"stores marker"| node_bridge
node_approval -->|"uses transition types"| node_schema
node_adapter -->|"validates writes"| node_validation
node_adapter -->|"verifies claims"| node_claims
node_adapter -->|"resolves actor"| node_credential
node_adapter -->|"calls bridge"| node_bridge
node_bridge -->|"sends JSON-RPC"| node_agentdb
node_heartbeat -->|"reads schedules"| node_adapter
node_heartbeat -.->|"emits notifications"| node_comms
node_comms -->|"calls bridge"| node_bridge
node_comms -.->|"sends notifications"| node_agentbbs
node_dashboard -->|"reads company data"| node_adapter
node_profiles -->|"reads member and transitions"| node_adapter
node_profiles -->|"persists profile"| node_bridge
node_budget -->|"reads governance data"| node_adapter
node_budget -->|"requests mutation"| node_autogenous
node_autogenous -->|"calls service"| node_autogenousservice

click node_cli "https://github.com/ruvnet/ruclip/blob/main/src/cli/ruclip.ts"
click node_schema "https://github.com/ruvnet/ruclip/tree/main/src/control-plane/schema"
click node_validation "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/schema/validation.ts"
click node_approval "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/approval/transition-approval-state.ts"
click node_claims "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/claims-authorization.ts"
click node_attestation "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/human-identity-attestation.ts"
click node_credential "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/actor-credential.ts"
click node_issuer "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/credential-issuer.ts"
click node_attester "https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/attest-handler.ts"
click node_google "https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/google-token.ts"
click node_identitymap "https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/identity-map.ts"
click node_heartbeat "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/heartbeat/fire-heartbeat.ts"
click node_comms "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/comms/agentbbs-notification-channel.ts"
click node_dashboard "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/dashboard/build-snapshot.ts"
click node_profiles "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/employee-augmentation/interaction-profile.ts"
click node_budget "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/governance/propose-budget-mutation.ts"
click node_autogenous "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/governance/autogenous-client.ts"
click node_adapter "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/agentdb-adapter.ts"
click node_bridge "https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/bridge-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema,node_validation toneBlue
class node_approval,node_budget,node_autogenous,node_agentdb toneAmber
class node_claims,node_attestation,node_credential,node_issuer,node_attester,node_google,node_identitymap toneMint
class node_cli,node_heartbeat,node_comms,node_dashboard,node_profiles toneRose
class node_adapter,node_bridge,node_operator,node_autogenousservice,node_agentbbs toneIndigo
```

## Components

### Company domain

- [Domain schemas](https://github.com/ruvnet/ruclip/tree/main/src/control-plane/schema): `src/control-plane/schema`
- [Schema validation](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/schema/validation.ts): `src/control-plane/schema/validation.ts`

### Workflow governance

- [Approval transitions](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/approval/transition-approval-state.ts): `src/control-plane/approval/transition-approval-state.ts`
- [Budget mutations](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/governance/propose-budget-mutation.ts): `src/control-plane/governance/propose-budget-mutation.ts`
- [Autogenous client](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/governance/autogenous-client.ts): `src/control-plane/governance/autogenous-client.ts`

### Identity and access

- [Claims authorization](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/claims-authorization.ts): `src/control-plane/authorization/claims-authorization.ts`
- [Human attestation](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/human-identity-attestation.ts): `src/control-plane/authorization/human-identity-attestation.ts`
- [Actor credentials](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/actor-credential.ts): `src/control-plane/authorization/actor-credential.ts`
- [Credential issuer](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/authorization/credential-issuer.ts): `src/control-plane/authorization/credential-issuer.ts`
- [Attestation service](https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/attest-handler.ts): `services/ruclip-attester/src/attest-handler.ts`
- [Google token verifier](https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/google-token.ts): `services/ruclip-attester/src/google-token.ts`
- [Employee identity map](https://github.com/ruvnet/ruclip/blob/main/services/ruclip-attester/src/identity-map.ts): `services/ruclip-attester/src/identity-map.ts`

### Company operations

- [CLI](https://github.com/ruvnet/ruclip/blob/main/src/cli/ruclip.ts): `src/cli/ruclip.ts`
- [Budgeted heartbeats](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/heartbeat/fire-heartbeat.ts): `src/control-plane/heartbeat/fire-heartbeat.ts`
- [AgentBBS notifications](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/comms/agentbbs-notification-channel.ts): `src/control-plane/comms/agentbbs-notification-channel.ts`
- [Dashboard snapshot](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/dashboard/build-snapshot.ts): `src/control-plane/dashboard/build-snapshot.ts`
- [Interaction profiles](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/employee-augmentation/interaction-profile.ts): `src/control-plane/employee-augmentation/interaction-profile.ts`

### Persistence and integrations

- [AgentDB adapter](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/agentdb-adapter.ts): `src/control-plane/store/agentdb-adapter.ts`
- [AgentDB bridge client](https://github.com/ruvnet/ruclip/blob/main/src/control-plane/store/bridge-client.ts): `src/control-plane/store/bridge-client.ts`

### Other components

- **Human or agent**
- **AgentDB**
- **Autogenous service**
- **AgentBBS**

## Connections

- Human or agent → CLI: invokes
- CLI → Human attestation: requests credentials (evidence: `src/cli/ruclip.ts`)
- Attestation service → Google token verifier: verifies token (evidence: `services/ruclip-attester/src/attest-handler.ts`)
- Attestation service → Employee identity map: looks up identity (evidence: `services/ruclip-attester/src/attest-handler.ts`)
- Attestation service → Human attestation: mints attestation (evidence: `services/ruclip-attester/src/attest-handler.ts`)
- Human attestation → Actor credentials: verifies identity (evidence: `src/control-plane/authorization/human-identity-attestation.ts`)
- Human attestation → Credential issuer: mints credential (evidence: `src/control-plane/authorization/human-identity-attestation.ts`)
- Human attestation → AgentDB adapter: recalls member (evidence: `src/control-plane/authorization/human-identity-attestation.ts`)
- Human attestation → AgentDB bridge client: stores marker (evidence: `src/control-plane/authorization/human-identity-attestation.ts`)
- Approval transitions → Domain schemas: uses transition types (evidence: `src/control-plane/approval/transition-approval-state.ts`)
- AgentDB adapter → Schema validation: validates writes (evidence: `src/control-plane/schema/validation.ts`)
- AgentDB adapter → Claims authorization: verifies claims (evidence: `src/control-plane/store/agentdb-adapter.ts`)
- AgentDB adapter → Actor credentials: resolves actor (evidence: `src/control-plane/store/agentdb-adapter.ts`)
- AgentDB adapter → AgentDB bridge client: calls bridge (evidence: `src/control-plane/store/agentdb-adapter.ts`)
- AgentDB bridge client → AgentDB: sends JSON-RPC (evidence: `src/control-plane/store/bridge-client.ts`)
- Budgeted heartbeats → AgentDB adapter: reads schedules (evidence: `src/control-plane/heartbeat/fire-heartbeat.ts`)
- Budgeted heartbeats → AgentBBS notifications: emits notifications
- AgentBBS notifications → AgentDB bridge client: calls bridge (evidence: `src/control-plane/comms/agentbbs-notification-channel.ts`)
- AgentBBS notifications → AgentBBS: sends notifications (evidence: `README.md`)
- Dashboard snapshot → AgentDB adapter: reads company data (evidence: `src/control-plane/dashboard/build-snapshot.ts`)
- Interaction profiles → AgentDB adapter: reads member and transitions (evidence: `src/control-plane/employee-augmentation/interaction-profile.ts`)
- Interaction profiles → AgentDB bridge client: persists profile (evidence: `src/control-plane/employee-augmentation/interaction-profile.ts`)
- Budget mutations → AgentDB adapter: reads governance data (evidence: `src/control-plane/governance/propose-budget-mutation.ts`)
- Budget mutations → Autogenous client: requests mutation (evidence: `src/control-plane/governance/propose-budget-mutation.ts`)
- Autogenous client → Autogenous service: calls service (evidence: `src/control-plane/governance/autogenous-client.ts`)
