# sakararya43-web/ratchet architecture

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

- Interactive diagram: https://gitdiagram.com/sakararya43-web/ratchet
- Repository: https://github.com/sakararya43-web/ratchet

## Overview

RATCHET is an independent access-change security control plane. A request is assessed against post-change graph reachability and signed policy, routed for independent passkey approval when sensitive, guarded again before execution, then verified against target state and recorded for audit. The repository also includes a simulated target and Kubernetes connector paths, a separately governed security authority, and console workspaces. The graph centers on the documented workflow; several subsystem connections are shown as unverified because their implementation was not sampled.

Main entry points: [`internal/workflow/service.go`](https://github.com/sakararya43-web/ratchet/blob/main/internal/workflow/service.go) (Workflow Service), [`internal/bus/ingest.go`](https://github.com/sakararya43-web/ratchet/blob/main/internal/bus/ingest.go) (Message Ingest), [`internal/policy/engine.go`](https://github.com/sakararya43-web/ratchet/blob/main/internal/policy/engine.go) (Policy Engine), [`cmd/ratchet-connector/main.go`](https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-connector/main.go) (Connector Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Change Review"]
  node_workflow["Workflow Service<br/>[service.go]"]
  node_change["Change Domain<br/>[change.go]"]
  node_graph["Reachability Graph"]
  node_policy["Policy Engine<br/>[engine.go]"]
  node_approval["Approval Review"]
end

subgraph group_trust["Independent Trust"]
  node_passkey["Passkey Evidence<br/>[verify.go]"]
  node_authority["Security Authority<br/>[main.go]"]
  node_truststore[("Trust Store<br/>[store.go]")]
end

subgraph group_connectors["Target Connectors"]
  node_bus["Message Ingest<br/>[ingest.go]"]
  node_connector["Connector Runtime<br/>[main.go]"]
  node_simconnector["Simulator Adapter<br/>[adapter.go]"]
  node_simtarget["Simulated Target<br/>[server.go]"]
  node_k8sconnector["Kubernetes Connector<br/>[runtime.go]"]
end

subgraph group_operations["Operations and Console"]
  node_api["API Routes"]
  node_eventstore[("Event Store<br/>[store.go]")]
  node_ledger[("Audit Ledger<br/>[chain.go]")]
  node_web["Console UI"]
end

node_requester(("Requester"))

node_requester -.->|"submits change"| node_api
node_api -.->|"routes requests"| node_workflow
node_workflow -->|"evaluates changes"| node_change
node_workflow -->|"reads impact"| node_graph
node_workflow -->|"evaluates policy"| node_policy
node_workflow -->|"mutates records"| node_eventstore
node_policy -->|"returns decision"| node_change
node_approval -.->|"verifies evidence"| node_passkey
node_workflow -.->|"routes approvals"| node_approval
node_authority -->|"serves governance"| node_truststore
node_policy -->|"verifies trust"| node_truststore
node_connector -->|"publishes snapshots"| node_bus
node_bus -->|"ingests graph"| node_eventstore
node_bus -->|"refreshes graph"| node_graph
node_connector -->|"configures adapter"| node_simconnector
node_simconnector -.->|"reads and executes"| node_simtarget
node_k8sconnector -.->|"publishes state"| node_bus
node_workflow -.->|"records audit"| node_ledger
node_web -.->|"uses workspaces"| node_api
node_workflow -.->|"dispatches execution"| node_connector

click node_api "https://github.com/sakararya43-web/ratchet/tree/main/internal/api"
click node_workflow "https://github.com/sakararya43-web/ratchet/blob/main/internal/workflow/service.go"
click node_change "https://github.com/sakararya43-web/ratchet/blob/main/internal/domain/change.go"
click node_graph "https://github.com/sakararya43-web/ratchet/tree/main/internal/graph"
click node_policy "https://github.com/sakararya43-web/ratchet/blob/main/internal/policy/engine.go"
click node_approval "https://github.com/sakararya43-web/ratchet/tree/main/internal/approval"
click node_passkey "https://github.com/sakararya43-web/ratchet/blob/main/internal/passkeyevidence/verify.go"
click node_authority "https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-authority/main.go"
click node_truststore "https://github.com/sakararya43-web/ratchet/blob/main/internal/trust/store.go"
click node_eventstore "https://github.com/sakararya43-web/ratchet/blob/main/internal/eventstore/store.go"
click node_ledger "https://github.com/sakararya43-web/ratchet/blob/main/internal/ledger/chain.go"
click node_bus "https://github.com/sakararya43-web/ratchet/blob/main/internal/bus/ingest.go"
click node_connector "https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-connector/main.go"
click node_simconnector "https://github.com/sakararya43-web/ratchet/blob/main/internal/connector/sim/adapter.go"
click node_simtarget "https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-sim/server/server.go"
click node_k8sconnector "https://github.com/sakararya43-web/ratchet/blob/main/internal/connector/k8s/runtime.go"
click node_web "https://github.com/sakararya43-web/ratchet/tree/main/web/src/console"

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_workflow,node_change,node_graph,node_policy,node_approval toneBlue
class node_passkey,node_authority,node_truststore toneAmber
class node_bus,node_connector,node_simconnector,node_simtarget,node_k8sconnector,node_requester toneMint
class node_api,node_eventstore,node_ledger,node_web toneRose
```

## Components

### Change Review

- [Workflow Service](https://github.com/sakararya43-web/ratchet/blob/main/internal/workflow/service.go): `internal/workflow/service.go`
- [Change Domain](https://github.com/sakararya43-web/ratchet/blob/main/internal/domain/change.go): `internal/domain/change.go`
- [Reachability Graph](https://github.com/sakararya43-web/ratchet/tree/main/internal/graph): `internal/graph`
- [Policy Engine](https://github.com/sakararya43-web/ratchet/blob/main/internal/policy/engine.go): `internal/policy/engine.go`
- [Approval Review](https://github.com/sakararya43-web/ratchet/tree/main/internal/approval): `internal/approval`

### Independent Trust

- [Passkey Evidence](https://github.com/sakararya43-web/ratchet/blob/main/internal/passkeyevidence/verify.go): `internal/passkeyevidence/verify.go`
- [Security Authority](https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-authority/main.go): `cmd/ratchet-authority/main.go`
- [Trust Store](https://github.com/sakararya43-web/ratchet/blob/main/internal/trust/store.go): `internal/trust/store.go`

### Target Connectors

- [Message Ingest](https://github.com/sakararya43-web/ratchet/blob/main/internal/bus/ingest.go): `internal/bus/ingest.go`
- [Connector Runtime](https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-connector/main.go): `cmd/ratchet-connector/main.go`
- [Simulator Adapter](https://github.com/sakararya43-web/ratchet/blob/main/internal/connector/sim/adapter.go): `internal/connector/sim/adapter.go`
- [Simulated Target](https://github.com/sakararya43-web/ratchet/blob/main/cmd/ratchet-sim/server/server.go): `cmd/ratchet-sim/server/server.go`
- [Kubernetes Connector](https://github.com/sakararya43-web/ratchet/blob/main/internal/connector/k8s/runtime.go): `internal/connector/k8s/runtime.go`

### Operations and Console

- [API Routes](https://github.com/sakararya43-web/ratchet/tree/main/internal/api): `internal/api`
- [Event Store](https://github.com/sakararya43-web/ratchet/blob/main/internal/eventstore/store.go): `internal/eventstore/store.go`
- [Audit Ledger](https://github.com/sakararya43-web/ratchet/blob/main/internal/ledger/chain.go): `internal/ledger/chain.go`
- [Console UI](https://github.com/sakararya43-web/ratchet/tree/main/web/src/console): `web/src/console`

### Other components

- **Requester**

## Connections

- Requester → API Routes: submits change
- API Routes → Workflow Service: routes requests
- Workflow Service → Change Domain: evaluates changes (evidence: `internal/workflow/service.go`)
- Workflow Service → Reachability Graph: reads impact (evidence: `internal/workflow/service.go`)
- Workflow Service → Policy Engine: evaluates policy (evidence: `internal/workflow/service.go`)
- Workflow Service → Event Store: mutates records (evidence: `internal/workflow/service.go`)
- Policy Engine → Change Domain: returns decision (evidence: `internal/policy/engine.go`)
- Approval Review → Passkey Evidence: verifies evidence
- Workflow Service → Approval Review: routes approvals
- Security Authority → Trust Store: serves governance (evidence: `cmd/ratchet-authority/main.go`)
- Policy Engine → Trust Store: verifies trust (evidence: `internal/policy/engine.go`)
- Connector Runtime → Message Ingest: publishes snapshots (evidence: `cmd/ratchet-connector/main.go`)
- Message Ingest → Event Store: ingests graph (evidence: `internal/bus/ingest.go`)
- Message Ingest → Reachability Graph: refreshes graph (evidence: `internal/bus/ingest.go`)
- Connector Runtime → Simulator Adapter: configures adapter (evidence: `cmd/ratchet-connector/main.go`)
- Simulator Adapter → Simulated Target: reads and executes
- Kubernetes Connector → Message Ingest: publishes state
- Workflow Service → Audit Ledger: records audit
- Console UI → API Routes: uses workspaces
- Workflow Service → Connector Runtime: dispatches execution