# jovianw/ripple architecture

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

- Interactive diagram: https://gitdiagram.com/jovianw/ripple
- Repository: https://github.com/jovianw/ripple

## Overview

Ripple is a self-improving circuit-board design harness with a web interface. Its documented core loop takes a board spec, generates and evaluates a design against hidden checks, then uses failures to revise the design; planning and queued subcircuit work are additional capabilities. The sampled worker excerpt shows the loop coordinating agents, design tools, and memory, while the index identifies further evaluation and storage modules. Web routes, queue internals, and several worker subsystems were not sampled, so their detailed runtime connections are left out.

Main entry points: [`apps/worker/src/agents/coder-loop.ts`](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder-loop.ts) (Coder loop), [`apps/worker/src/agents/coder.ts`](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder.ts) (Board coder), [`apps/worker/src/harness/memory.ts`](https://github.com/jovianw/ripple/blob/main/apps/worker/src/harness/memory.ts) (Lessons and reuse), [`apps/worker/src/agents/critic/index.ts`](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/critic/index.ts) (Design critic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_webui["Web UI<br/>[page.tsx]"]
  node_boardapi["Board APIs<br/>[route.ts]"]
  node_specapi["Spec APIs<br/>[route.ts]"]
  node_runapi["Run APIs<br/>[route.ts]"]
end

subgraph group_orchestration["Design orchestration"]
  node_queue["Work queue<br/>[queue.ts]"]
  node_loop["Coder loop<br/>[coder-loop.ts]"]
  node_db[("Worker database<br/>[db.ts]")]
end

subgraph group_agents["Design agents"]
  node_planner["Spec planner<br/>[index.ts]"]
  node_coder["Board coder<br/>[coder.ts]"]
  node_critic["Design critic<br/>[index.ts]"]
end

subgraph group_design["Board construction"]
  node_router["Model router<br/>[router.ts]"]
  node_placement["Placement<br/>[placement.ts]"]
  node_outline["Board outline<br/>[board-outline.ts]"]
  node_normalize["Design normalization<br/>[normalize.ts]"]
end

subgraph group_evaluation["Evaluation and learning"]
  node_drc["Design-rule checks<br/>[drc.ts]"]
  node_evaluate["Circuit evaluation<br/>[evaluate.ts]"]
  node_metrics["Board metrics<br/>[metrics.ts]"]
  node_hiddenchecks["Hidden checks<br/>[run-checks.ts]"]
  node_memory["Lessons and reuse<br/>[memory.ts]"]
  node_deliverables["Board exports<br/>[deliverables.ts]"]
end

node_user(("Board designer"))

node_user -->|"uses"| node_webui
node_planner -->|"returns work items"| node_queue
node_loop -->|"generates design"| node_coder
node_loop -->|"requests review"| node_critic
node_loop -->|"fits board"| node_outline
node_loop -->|"evaluates source"| node_evaluate
node_loop -->|"checks rules"| node_drc
node_loop -->|"computes metrics"| node_metrics
node_loop -->|"bakes placement"| node_normalize
node_loop -->|"retrieves lessons"| node_memory
node_loop -->|"stores learning"| node_memory
node_coder -->|"requests models"| node_router
node_coder -->|"evaluates design"| node_evaluate
node_coder -->|"normalizes design"| node_normalize
node_coder -->|"places parts"| node_placement
node_critic -->|"uses placement"| node_placement
node_memory -->|"reads and writes"| node_db
node_loop -->|"records runs"| node_db
node_loop -.->|"checks design"| node_hiddenchecks
node_user -.->|"submits spec"| node_specapi
node_user -.->|"views boards"| node_boardapi
node_user -.->|"views runs"| node_runapi

click node_webui "https://github.com/jovianw/ripple/blob/main/apps/web/app/page.tsx"
click node_boardapi "https://github.com/jovianw/ripple/blob/main/apps/web/app/api/boards/route.ts"
click node_specapi "https://github.com/jovianw/ripple/blob/main/apps/web/app/api/spec/route.ts"
click node_runapi "https://github.com/jovianw/ripple/blob/main/apps/web/app/api/runs/route.ts"
click node_planner "https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/planner/index.ts"
click node_queue "https://github.com/jovianw/ripple/blob/main/apps/worker/src/harness/queue.ts"
click node_loop "https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder-loop.ts"
click node_coder "https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder.ts"
click node_critic "https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/critic/index.ts"
click node_router "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/router.ts"
click node_placement "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/placement.ts"
click node_outline "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/board-outline.ts"
click node_normalize "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/normalize.ts"
click node_drc "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/drc.ts"
click node_evaluate "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/evaluate.ts"
click node_metrics "https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/metrics.ts"
click node_hiddenchecks "https://github.com/jovianw/ripple/blob/main/checks/run-checks.ts"
click node_memory "https://github.com/jovianw/ripple/blob/main/apps/worker/src/harness/memory.ts"
click node_db "https://github.com/jovianw/ripple/blob/main/apps/worker/src/db.ts"
click node_deliverables "https://github.com/jovianw/ripple/blob/main/apps/worker/src/export/deliverables.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_webui,node_boardapi,node_specapi,node_runapi toneBlue
class node_queue,node_loop,node_db toneAmber
class node_planner,node_coder,node_critic toneMint
class node_router,node_placement,node_outline,node_normalize toneRose
class node_drc,node_evaluate,node_metrics,node_hiddenchecks,node_memory,node_deliverables,node_user toneIndigo
```

## Components

### Web interface

- [Web UI](https://github.com/jovianw/ripple/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Board APIs](https://github.com/jovianw/ripple/blob/main/apps/web/app/api/boards/route.ts): `apps/web/app/api/boards/route.ts`
- [Spec APIs](https://github.com/jovianw/ripple/blob/main/apps/web/app/api/spec/route.ts): `apps/web/app/api/spec/route.ts`
- [Run APIs](https://github.com/jovianw/ripple/blob/main/apps/web/app/api/runs/route.ts): `apps/web/app/api/runs/route.ts`

### Design orchestration

- [Work queue](https://github.com/jovianw/ripple/blob/main/apps/worker/src/harness/queue.ts): `apps/worker/src/harness/queue.ts`
- [Coder loop](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder-loop.ts): `apps/worker/src/agents/coder-loop.ts`
- [Worker database](https://github.com/jovianw/ripple/blob/main/apps/worker/src/db.ts): `apps/worker/src/db.ts`

### Design agents

- [Spec planner](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/planner/index.ts): `apps/worker/src/agents/planner/index.ts`
- [Board coder](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/coder.ts): `apps/worker/src/agents/coder.ts`
- [Design critic](https://github.com/jovianw/ripple/blob/main/apps/worker/src/agents/critic/index.ts): `apps/worker/src/agents/critic/index.ts`

### Board construction

- [Model router](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/router.ts): `apps/worker/src/tools/router.ts`
- [Placement](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/placement.ts): `apps/worker/src/tools/placement.ts`
- [Board outline](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/board-outline.ts): `apps/worker/src/tools/board-outline.ts`
- [Design normalization](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/normalize.ts): `apps/worker/src/tools/normalize.ts`

### Evaluation and learning

- [Design-rule checks](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/drc.ts): `apps/worker/src/tools/drc.ts`
- [Circuit evaluation](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/evaluate.ts): `apps/worker/src/tools/evaluate.ts`
- [Board metrics](https://github.com/jovianw/ripple/blob/main/apps/worker/src/tools/metrics.ts): `apps/worker/src/tools/metrics.ts`
- [Hidden checks](https://github.com/jovianw/ripple/blob/main/checks/run-checks.ts): `checks/run-checks.ts`
- [Lessons and reuse](https://github.com/jovianw/ripple/blob/main/apps/worker/src/harness/memory.ts): `apps/worker/src/harness/memory.ts`
- [Board exports](https://github.com/jovianw/ripple/blob/main/apps/worker/src/export/deliverables.ts): `apps/worker/src/export/deliverables.ts`

### Other components

- **Board designer**

## Connections

- Board designer → Web UI: uses (evidence: `README.md`)
- Spec planner → Work queue: returns work items (evidence: `apps/worker/src/agents/planner/index.ts`)
- Coder loop → Board coder: generates design (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Design critic: requests review (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Board outline: fits board (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Circuit evaluation: evaluates source (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Design-rule checks: checks rules (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Board metrics: computes metrics (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Design normalization: bakes placement (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Lessons and reuse: retrieves lessons (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Lessons and reuse: stores learning (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Board coder → Model router: requests models (evidence: `apps/worker/src/agents/coder.ts`)
- Board coder → Circuit evaluation: evaluates design (evidence: `apps/worker/src/agents/coder.ts`)
- Board coder → Design normalization: normalizes design (evidence: `apps/worker/src/agents/coder.ts`)
- Board coder → Placement: places parts (evidence: `apps/worker/src/agents/coder.ts`)
- Design critic → Placement: uses placement
- Lessons and reuse → Worker database: reads and writes (evidence: `apps/worker/src/harness/memory.ts`)
- Coder loop → Worker database: records runs (evidence: `apps/worker/src/agents/coder-loop.ts`)
- Coder loop → Hidden checks: checks design
- Board designer → Spec APIs: submits spec
- Board designer → Board APIs: views boards
- Board designer → Run APIs: views runs