# pbakaus/impeccable architecture

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

- Interactive diagram: https://gitdiagram.com/pbakaus/impeccable
- Repository: https://github.com/pbakaus/impeccable
- Video tour (about a minute): https://gitdiagram.com/pbakaus/impeccable/video

## Overview

Impeccable equips coding agents to steer and review interface design, while also providing deterministic design detection and browser-based iteration. The main workflow is an agent command applied to a target, informed by project context; separate workflows scan source or rendered pages and let users review or accept live variants. The README documents these product capabilities; sampled-source relationships are cited where visible, and unsampled subsystems are represented only at paths supported by the tree.

Main entry points: [`crates/context/src/context_cli.rs`](https://github.com/pbakaus/impeccable/blob/main/crates/context/src/context_cli.rs) (Agent commands), [`crates/detect/src/engines.rs`](https://github.com/pbakaus/impeccable/blob/main/crates/detect/src/engines.rs) (Engine seams), [`crates/html/src/static_engine.rs`](https://github.com/pbakaus/impeccable/blob/main/crates/html/src/static_engine.rs) (Static HTML scan), [`crates/browser/src/snapshot_engine.rs`](https://github.com/pbakaus/impeccable/blob/main/crates/browser/src/snapshot_engine.rs) (Browser URL scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent guidance"]
  node_agent["Agent commands<br/>[context_cli.rs]"]
  node_context["Project context<br/>[context.rs]"]
  node_command_skills["Command playbooks"]
  node_critique[("Critique storage")]
end

subgraph group_detection["Design detection"]
  node_detector_cli["Detect CLI<br/>[cli.rs]"]
  node_engine_router["Engine seams<br/>[engines.rs]"]
  node_static_engine["Static HTML scan<br/>[static_engine.rs]"]
  node_html_engine["HTML rule engine<br/>[engine.rs]"]
  node_static_dom["Static DOM and cascade<br/>[dom.rs]"]
  node_url_engine["Browser URL scan<br/>[snapshot_engine.rs]"]
  node_browser_cdp["Chrome DevTools<br/>[cdp.rs]"]
  node_rule_core["Design rules<br/>[text_context.rs]"]
end

subgraph group_live["Live iteration"]
  node_live_server["Live session server<br/>[server.rs]"]
  node_live_edit["Live edit workflow<br/>[live_generate.rs]"]
  node_live_accept["Accept variants<br/>[live_accept.rs]"]
end

subgraph group_review["Component review"]
  node_review_server["Review server<br/>[server.rs]"]
  node_review_ui["Component review UI<br/>[review.ts]"]
  node_plan_ui["Plan and asset review<br/>[plan-review.ts]"]
end

subgraph group_integration["Tool integrations"]
  node_extension["Browser extension<br/>[service-worker.js]"]
  node_hook["Design hook sessions<br/>[hook_sessions.rs]"]
end

node_user(("Designer or developer"))
node_dev_browser(("Running browser page"))
node_coding_agent(("Coding agent"))

node_user -->|"runs command"| node_agent
node_agent -->|"reads and writes"| node_context
node_agent -->|"loads playbook"| node_command_skills
node_agent -.->|"stores reviews"| node_critique
node_user -->|"starts scan"| node_detector_cli
node_detector_cli -->|"selects engine"| node_engine_router
node_engine_router -->|"uses HTML engine"| node_static_engine
node_static_engine -->|"adapts scan"| node_html_engine
node_html_engine -->|"queries document"| node_static_dom
node_engine_router -->|"uses URL engine"| node_url_engine
node_url_engine -->|"drives browser"| node_browser_cdp
node_static_engine -.->|"runs analyzers"| node_rule_core
node_url_engine -.->|"applies rules"| node_rule_core
node_user -->|"starts live mode"| node_live_server
node_live_server -->|"opens overlay"| node_dev_browser
node_dev_browser -->|"selects element"| node_live_edit
node_live_edit -->|"submits variant"| node_live_accept
node_live_accept -->|"writes source"| node_dev_browser
node_user -.->|"opens review"| node_review_server
node_review_server -.->|"serves review"| node_review_ui
node_review_ui -->|"mounts plan review"| node_plan_ui
node_user -->|"opens overlay"| node_extension
node_coding_agent -->|"checks edits"| node_hook

click node_agent "https://github.com/pbakaus/impeccable/blob/main/crates/context/src/context_cli.rs"
click node_context "https://github.com/pbakaus/impeccable/blob/main/crates/context/src/context.rs"
click node_command_skills "https://github.com/pbakaus/impeccable/tree/main/skill"
click node_critique "https://github.com/pbakaus/impeccable/blob/main/crates/context/src/critique_storage.rs"
click node_detector_cli "https://github.com/pbakaus/impeccable/blob/main/crates/detect/src/cli.rs"
click node_engine_router "https://github.com/pbakaus/impeccable/blob/main/crates/detect/src/engines.rs"
click node_static_engine "https://github.com/pbakaus/impeccable/blob/main/crates/html/src/static_engine.rs"
click node_html_engine "https://github.com/pbakaus/impeccable/blob/main/crates/html/src/engine.rs"
click node_static_dom "https://github.com/pbakaus/impeccable/blob/main/crates/html/src/dom.rs"
click node_url_engine "https://github.com/pbakaus/impeccable/blob/main/crates/browser/src/snapshot_engine.rs"
click node_browser_cdp "https://github.com/pbakaus/impeccable/blob/main/crates/browser/src/cdp.rs"
click node_rule_core "https://github.com/pbakaus/impeccable/blob/main/crates/core/src/checks/text_context.rs"
click node_live_server "https://github.com/pbakaus/impeccable/blob/main/crates/live/src/server.rs"
click node_live_edit "https://github.com/pbakaus/impeccable/blob/main/crates/live/src/live_generate.rs"
click node_live_accept "https://github.com/pbakaus/impeccable/blob/main/crates/live/src/live_accept.rs"
click node_review_server "https://github.com/pbakaus/impeccable/blob/main/crates/context/src/component_review/server.rs"
click node_review_ui "https://github.com/pbakaus/impeccable/blob/main/ui/component-review/review.ts"
click node_plan_ui "https://github.com/pbakaus/impeccable/blob/main/ui/component-review/plan-review.ts"
click node_extension "https://github.com/pbakaus/impeccable/blob/main/extension/background/service-worker.js"
click node_hook "https://github.com/pbakaus/impeccable/blob/main/crates/hook/src/hook_sessions.rs"

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_agent,node_context,node_command_skills,node_critique,node_dev_browser toneBlue
class node_detector_cli,node_engine_router,node_static_engine,node_html_engine,node_static_dom,node_url_engine,node_browser_cdp,node_rule_core toneAmber
class node_live_server,node_live_edit,node_live_accept toneMint
class node_review_server,node_review_ui,node_plan_ui toneRose
class node_extension,node_hook,node_user,node_coding_agent toneIndigo
```

## Components

### Agent guidance

- [Agent commands](https://github.com/pbakaus/impeccable/blob/main/crates/context/src/context_cli.rs): `crates/context/src/context_cli.rs`
- [Project context](https://github.com/pbakaus/impeccable/blob/main/crates/context/src/context.rs): `crates/context/src/context.rs`
- [Command playbooks](https://github.com/pbakaus/impeccable/tree/main/skill): `skill`
- [Critique storage](https://github.com/pbakaus/impeccable/blob/main/crates/context/src/critique_storage.rs): `crates/context/src/critique_storage.rs`

### Design detection

- [Detect CLI](https://github.com/pbakaus/impeccable/blob/main/crates/detect/src/cli.rs): `crates/detect/src/cli.rs`
- [Engine seams](https://github.com/pbakaus/impeccable/blob/main/crates/detect/src/engines.rs): `crates/detect/src/engines.rs`
- [Static HTML scan](https://github.com/pbakaus/impeccable/blob/main/crates/html/src/static_engine.rs): `crates/html/src/static_engine.rs`
- [HTML rule engine](https://github.com/pbakaus/impeccable/blob/main/crates/html/src/engine.rs): `crates/html/src/engine.rs`
- [Static DOM and cascade](https://github.com/pbakaus/impeccable/blob/main/crates/html/src/dom.rs): `crates/html/src/dom.rs`
- [Browser URL scan](https://github.com/pbakaus/impeccable/blob/main/crates/browser/src/snapshot_engine.rs): `crates/browser/src/snapshot_engine.rs`
- [Chrome DevTools](https://github.com/pbakaus/impeccable/blob/main/crates/browser/src/cdp.rs): `crates/browser/src/cdp.rs`
- [Design rules](https://github.com/pbakaus/impeccable/blob/main/crates/core/src/checks/text_context.rs): `crates/core/src/checks/text_context.rs`

### Live iteration

- [Live session server](https://github.com/pbakaus/impeccable/blob/main/crates/live/src/server.rs): `crates/live/src/server.rs`
- [Live edit workflow](https://github.com/pbakaus/impeccable/blob/main/crates/live/src/live_generate.rs): `crates/live/src/live_generate.rs`
- [Accept variants](https://github.com/pbakaus/impeccable/blob/main/crates/live/src/live_accept.rs): `crates/live/src/live_accept.rs`

### Component review

- [Review server](https://github.com/pbakaus/impeccable/blob/main/crates/context/src/component_review/server.rs): `crates/context/src/component_review/server.rs`
- [Component review UI](https://github.com/pbakaus/impeccable/blob/main/ui/component-review/review.ts): `ui/component-review/review.ts`
- [Plan and asset review](https://github.com/pbakaus/impeccable/blob/main/ui/component-review/plan-review.ts): `ui/component-review/plan-review.ts`

### Tool integrations

- [Browser extension](https://github.com/pbakaus/impeccable/blob/main/extension/background/service-worker.js): `extension/background/service-worker.js`
- [Design hook sessions](https://github.com/pbakaus/impeccable/blob/main/crates/hook/src/hook_sessions.rs): `crates/hook/src/hook_sessions.rs`

### Other components

- **Designer or developer**
- **Running browser page**
- **Coding agent**

## Connections

- Designer or developer → Agent commands: runs command (evidence: `README.md`)
- Agent commands → Project context: reads and writes (evidence: `README.md`)
- Agent commands → Command playbooks: loads playbook (evidence: `README.md`)
- Agent commands → Critique storage: stores reviews
- Designer or developer → Detect CLI: starts scan (evidence: `README.md`)
- Detect CLI → Engine seams: selects engine (evidence: `crates/detect/src/engines.rs`)
- Engine seams → Static HTML scan: uses HTML engine (evidence: `crates/html/src/static_engine.rs`)
- Static HTML scan → HTML rule engine: adapts scan (evidence: `crates/html/src/static_engine.rs`)
- HTML rule engine → Static DOM and cascade: queries document (evidence: `crates/html/src/engine.rs`)
- Engine seams → Browser URL scan: uses URL engine (evidence: `crates/detect/src/engines.rs`)
- Browser URL scan → Chrome DevTools: drives browser (evidence: `crates/browser/src/snapshot_engine.rs`)
- Static HTML scan → Design rules: runs analyzers
- Browser URL scan → Design rules: applies rules
- Designer or developer → Live session server: starts live mode (evidence: `README.md`)
- Live session server → Running browser page: opens overlay (evidence: `README.md`)
- Running browser page → Live edit workflow: selects element (evidence: `README.md`)
- Live edit workflow → Accept variants: submits variant (evidence: `README.md`)
- Accept variants → Running browser page: writes source (evidence: `README.md`)
- Designer or developer → Review server: opens review
- Review server → Component review UI: serves review
- Component review UI → Plan and asset review: mounts plan review (evidence: `ui/component-review/review.ts`)
- Designer or developer → Browser extension: opens overlay (evidence: `README.md`)
- Coding agent → Design hook sessions: checks edits (evidence: `README.md`)
