# dillonsmart/docket architecture

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

- Interactive diagram: https://gitdiagram.com/dillonsmart/docket
- Repository: https://github.com/dillonsmart/docket

## Overview

Docket is a local-first tool that builds a signed, per-commit evidence record for agent-written code. The principal workflow observes edits and commands, parses agent sessions, replays edits against file history, attributes committed hunks, correlates checks and coverage, then stores the record in Git for review and verification. The README also documents setup hooks, range reviews, and quality gating. Relationships below rely on sampled excerpts, SOURCE INDEX references, or README statements; unsampled build internals are represented at their enclosing directory.

Main entry points: [`internal/cli/commands.go`](https://github.com/dillonsmart/docket/blob/main/internal/cli/commands.go) (User Commands), [`internal/build`](https://github.com/dillonsmart/docket/tree/main/internal/build) (Record Builder), [`internal/cer/cer.go`](https://github.com/dillonsmart/docket/blob/main/internal/cer/cer.go) (Evidence Record), [`internal/gate/gate.go`](https://github.com/dillonsmart/docket/blob/main/internal/gate/gate.go) (Quality Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Session Capture"]
  node_codex["Codex Parser<br/>[codex.go]"]
  node_opencode["OpenCode Parser<br/>[opencode.go]"]
  node_agentregistry["Agent Registry<br/>[agents.go]"]
  node_observer["Shell Observer<br/>[collect.go]"]
  node_transcript["Transcript Model<br/>[edits.go]"]
end

subgraph group_analysis["Provenance Analysis"]
  node_builder["Record Builder"]
  node_timeline["Edit Timeline<br/>[timeline.go]"]
  node_attribution["Hunk Attribution<br/>[attribute.go]"]
  node_evidence["Evidence Correlation<br/>[correlate.go]"]
  node_gate["Quality Gate<br/>[gate.go]"]
end

subgraph group_records["Records and Storage"]
  node_record["Evidence Record<br/>[cer.go]"]
  node_signing["Record Signing<br/>[sign.go]"]
  node_store[("Git Record Store<br/>[store.go]")]
end

subgraph group_interface["CLI and Review"]
  node_cli["CLI Dispatcher<br/>[cli.go]"]
  node_commands["User Commands<br/>[commands.go]"]
  node_hooks["Commit Hooks<br/>[hooks.go]"]
  node_setup["Repository Setup<br/>[init.go]"]
  node_renderer["Record Renderer<br/>[render.go]"]
  node_markdown["Markdown Review<br/>[markdown.go]"]
end

node_developer(("Developer"))
node_git[("Git Repository")]

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"builds records"| node_builder
node_hooks -->|"builds records"| node_builder
node_setup -->|"installs hooks"| node_git
node_setup -->|"installs agent hooks"| node_observer
node_agentregistry -->|"registers parser"| node_codex
node_agentregistry -->|"registers parser"| node_opencode
node_codex -->|"parses sessions"| node_transcript
node_opencode -->|"parses sessions"| node_transcript
node_observer -->|"records edits"| node_transcript
node_builder -.->|"replays edits"| node_timeline
node_timeline -->|"provides provenance"| node_attribution
node_builder -.->|"correlates checks"| node_evidence
node_evidence -->|"adds evidence"| node_record
node_attribution -.->|"attributes hunks"| node_record
node_builder -.->|"creates record"| node_record
node_record -->|"signs payload"| node_signing
node_commands -->|"reads and writes"| node_store
node_store -->|"stores on ref"| node_git
node_commands -->|"renders output"| node_renderer
node_commands -->|"renders reviews"| node_markdown
node_gate -->|"loads sessions"| node_builder
node_gate -->|"measures attribution"| node_attribution
node_commands -->|"runs quality gate"| node_gate
node_commands -->|"verifies records"| node_record

click node_cli "https://github.com/dillonsmart/docket/blob/main/internal/cli/cli.go"
click node_commands "https://github.com/dillonsmart/docket/blob/main/internal/cli/commands.go"
click node_hooks "https://github.com/dillonsmart/docket/blob/main/internal/cli/hooks.go"
click node_setup "https://github.com/dillonsmart/docket/blob/main/internal/cli/init.go"
click node_codex "https://github.com/dillonsmart/docket/blob/main/internal/agents/codex/codex.go"
click node_opencode "https://github.com/dillonsmart/docket/blob/main/internal/agents/opencode/opencode.go"
click node_agentregistry "https://github.com/dillonsmart/docket/blob/main/internal/agents/agents.go"
click node_observer "https://github.com/dillonsmart/docket/blob/main/internal/collect/collect.go"
click node_transcript "https://github.com/dillonsmart/docket/blob/main/internal/transcript/edits.go"
click node_builder "https://github.com/dillonsmart/docket/tree/main/internal/build"
click node_timeline "https://github.com/dillonsmart/docket/blob/main/internal/timeline/timeline.go"
click node_attribution "https://github.com/dillonsmart/docket/blob/main/internal/attribute/attribute.go"
click node_evidence "https://github.com/dillonsmart/docket/blob/main/internal/evidence/correlate.go"
click node_gate "https://github.com/dillonsmart/docket/blob/main/internal/gate/gate.go"
click node_record "https://github.com/dillonsmart/docket/blob/main/internal/cer/cer.go"
click node_signing "https://github.com/dillonsmart/docket/blob/main/internal/cer/sign.go"
click node_store "https://github.com/dillonsmart/docket/blob/main/internal/store/store.go"
click node_renderer "https://github.com/dillonsmart/docket/blob/main/internal/render/render.go"
click node_markdown "https://github.com/dillonsmart/docket/blob/main/internal/render/markdown.go"

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_codex,node_opencode,node_agentregistry,node_observer,node_transcript toneBlue
class node_builder,node_timeline,node_attribution,node_evidence,node_gate,node_git toneAmber
class node_record,node_signing,node_store toneMint
class node_cli,node_commands,node_hooks,node_setup,node_renderer,node_markdown toneRose
class node_developer toneIndigo
```

## Components

### Session Capture

- [Codex Parser](https://github.com/dillonsmart/docket/blob/main/internal/agents/codex/codex.go): `internal/agents/codex/codex.go`
- [OpenCode Parser](https://github.com/dillonsmart/docket/blob/main/internal/agents/opencode/opencode.go): `internal/agents/opencode/opencode.go`
- [Agent Registry](https://github.com/dillonsmart/docket/blob/main/internal/agents/agents.go): `internal/agents/agents.go`
- [Shell Observer](https://github.com/dillonsmart/docket/blob/main/internal/collect/collect.go): `internal/collect/collect.go`
- [Transcript Model](https://github.com/dillonsmart/docket/blob/main/internal/transcript/edits.go): `internal/transcript/edits.go`

### Provenance Analysis

- [Record Builder](https://github.com/dillonsmart/docket/tree/main/internal/build): `internal/build`
- [Edit Timeline](https://github.com/dillonsmart/docket/blob/main/internal/timeline/timeline.go): `internal/timeline/timeline.go`
- [Hunk Attribution](https://github.com/dillonsmart/docket/blob/main/internal/attribute/attribute.go): `internal/attribute/attribute.go`
- [Evidence Correlation](https://github.com/dillonsmart/docket/blob/main/internal/evidence/correlate.go): `internal/evidence/correlate.go`
- [Quality Gate](https://github.com/dillonsmart/docket/blob/main/internal/gate/gate.go): `internal/gate/gate.go`

### Records and Storage

- [Evidence Record](https://github.com/dillonsmart/docket/blob/main/internal/cer/cer.go): `internal/cer/cer.go`
- [Record Signing](https://github.com/dillonsmart/docket/blob/main/internal/cer/sign.go): `internal/cer/sign.go`
- [Git Record Store](https://github.com/dillonsmart/docket/blob/main/internal/store/store.go): `internal/store/store.go`

### CLI and Review

- [CLI Dispatcher](https://github.com/dillonsmart/docket/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [User Commands](https://github.com/dillonsmart/docket/blob/main/internal/cli/commands.go): `internal/cli/commands.go`
- [Commit Hooks](https://github.com/dillonsmart/docket/blob/main/internal/cli/hooks.go): `internal/cli/hooks.go`
- [Repository Setup](https://github.com/dillonsmart/docket/blob/main/internal/cli/init.go): `internal/cli/init.go`
- [Record Renderer](https://github.com/dillonsmart/docket/blob/main/internal/render/render.go): `internal/render/render.go`
- [Markdown Review](https://github.com/dillonsmart/docket/blob/main/internal/render/markdown.go): `internal/render/markdown.go`

### Other components

- **Developer**
- **Git Repository**

## Connections

- Developer → CLI Dispatcher: runs commands
- CLI Dispatcher → User Commands: dispatches (evidence: `internal/cli/cli.go`)
- User Commands → Record Builder: builds records (evidence: `internal/cli/commands.go`)
- Commit Hooks → Record Builder: builds records (evidence: `internal/cli/hooks.go`)
- Repository Setup → Git Repository: installs hooks (evidence: `README.md`)
- Repository Setup → Shell Observer: installs agent hooks (evidence: `README.md`)
- Agent Registry → Codex Parser: registers parser (evidence: `internal/agents/agents.go`)
- Agent Registry → OpenCode Parser: registers parser (evidence: `internal/agents/agents.go`)
- Codex Parser → Transcript Model: parses sessions (evidence: `internal/agents/codex/codex.go`)
- OpenCode Parser → Transcript Model: parses sessions (evidence: `internal/agents/opencode/opencode.go`)
- Shell Observer → Transcript Model: records edits (evidence: `internal/collect/collect.go`)
- Record Builder → Edit Timeline: replays edits
- Edit Timeline → Hunk Attribution: provides provenance (evidence: `internal/attribute/attribute.go`)
- Record Builder → Evidence Correlation: correlates checks
- Evidence Correlation → Evidence Record: adds evidence (evidence: `internal/evidence/correlate.go`)
- Hunk Attribution → Evidence Record: attributes hunks
- Record Builder → Evidence Record: creates record
- Evidence Record → Record Signing: signs payload (evidence: `internal/cer/sign.go`)
- User Commands → Git Record Store: reads and writes (evidence: `internal/cli/commands.go`)
- Git Record Store → Git Repository: stores on ref (evidence: `internal/store/store.go`)
- User Commands → Record Renderer: renders output (evidence: `internal/cli/commands.go`)
- User Commands → Markdown Review: renders reviews (evidence: `internal/cli/commands.go`)
- Quality Gate → Record Builder: loads sessions (evidence: `internal/gate/gate.go`)
- Quality Gate → Hunk Attribution: measures attribution (evidence: `internal/gate/gate.go`)
- User Commands → Quality Gate: runs quality gate (evidence: `internal/cli/commands.go`)
- User Commands → Evidence Record: verifies records (evidence: `internal/cli/commands.go`)
