Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
232 lines (182 loc) · 10.8 KB

ARCHITECTURE.md

File metadata and controls

232 lines (182 loc) · 10.8 KB
Raw

PCB Flow Repository Architecture

New to PCB Flow? Don't start here — start with the handbook. This document is a deeper structural reference for when you want to understand how the workspace is organized (useful for contributors and the curious, not required to use PCB Flow).

This document explains the shape of the repository: why each directory exists, who uses it, how the AI agents plug into it, where engineering knowledge lives, and how a new project inherits everything learned before it.

Read this once and the whole repo becomes navigable.

The mental model

PCB Flow separates four things that most PCB repos tangle together:

Concern Lives in Nature
The process — the 12 gated phases workflow/ stable, versioned, reused every project
The workers — AI agent roles agents/ stable definitions the orchestrator invokes
The tools — the code that touches EDA automation/ reusable engines (EasyEDA / browser / KiCad / shared)
The learnings — engineering knowledge knowledge/ + docs/ compounds across every project
The work — an actual board projects/<name>/ disposable build artifacts + that board's decisions
The blanks — source-of-truth templates templates/ copied into each project

The governing principle behind the split (see knowledge/principles.md → docs/00_PHILOSOPHY.md): knowledge is the source, geometry is the build artifact. The first four rows are the durable source; the projects/ row is the regenerable build output. That is why they are physically separated — you protect and version the source, and you can throw away and regenerate the build.

   knowledge/ + docs/   ─┐
   workflow/            ─┤   the DURABLE FRAMEWORK  (one copy, reused for every board)
   agents/  automation/ ─┤   → improves with every project
   templates/           ─┘
          │  copied + driven
          ▼
   projects/<board>/     the BUILD  (per-board; schematic, placement, routing, gerbers)
          │  new lessons flow back up
          └───────────────────────────────► knowledge/learning-db.md

That last arrow is the point of the whole design: every project makes the framework smarter.

Directory by directory

workflow/ — the 12-phase pipeline (the process)

The canonical, gated engineering process, one file per phase (01-requirement-analysis.md … 12-final-verification.md) plus a README with the pipeline overview and gate table.

Each phase file states, in the same shape: objective · inputs · outputs · validation · deliverables · engineering checklist · automation · human review · exit gate · owning agent. A phase does not start until the previous phase's exit gate passes ("place nothing over wrong").

  • Contributors refine a phase by editing its file — the improvement applies to every future project automatically.
  • AI agents read the current phase's file to know exactly what to produce and what gate to satisfy.
  • Engineers read it to understand the method without touching any AI.

This is where your 12-phase workflow becomes executable structure rather than a description. It supersedes the older 10-phase conceptual view in docs/01_METHODOLOGY.md, which is retained as background reading.

agents/ — the AI worker roles

One definition per agent role (feasibility-analyst, bom-planner, schematic-generator, schematic-auditor, placement-planner, router, verification-engineer) plus an orchestrator and a README mapping agents → phases. Each definition states the agent's mission, the phase it owns, its tools, its inputs/outputs, its autonomy tier, and its output contract (a structured verdict, not prose).

  • AI agents are instantiated from these files — the orchestrator dispatches the right agent for the current phase.
  • Contributors add a new capability by adding an agent definition; the workflow references it by name.

automation/ — the tools that touch the EDA world

The reusable engines, split by backend because each backend has different strengths and hard limits:

  • easyeda/ — schematic generation + placement via the Standalone-Script API. Holds the board-agnostic generator engine.

  • browser/ — the headless CDP driver + netlist reconstruction that lets agents read the real board back.

  • kicad/ — the routing + verification engine. Routing is done here, not in EasyEDA, because KiCad's pcbnew/kicad-cli API can script pours, zones, stitching, and DRC (EasyEDA's cannot). Holds drc.sh (DRC ground truth), the stitcher, and the router.

  • shared/ — backend-agnostic math: IPC-2221 trace widths, unit conversion, congestion grid.

  • AI agents call these tools; they don't reinvent them per project.

  • Contributors improve a tool once and every project benefits.

knowledge/ — the engineering brain (the part that compounds)

The living, growing, machine-usable knowledge that carries across projects:

  • principles.md — the first principles.
  • knowledge-graph.md — reusable heuristics (decisions, failures, quantified rules).
  • design-standards.md — IPC-2221 widths, via ampacity, stackup selection, clearance floors — the hard engineering rules.
  • learning-db.md — append-only. Every new failure→lesson from any project lands here in a fixed format and becomes available to all future projects.
  • knowledge-inheritance.md — the mechanism by which a new project starts with all prior learnings.

The deep prose reference (philosophy essays, patterns, bottleneck write-ups, lessons) lives in docs/ — the reference library. knowledge/ is the operational, growing layer; docs/ is the stable theory it's built on.

  • AI agents consult knowledge/ before acting and write back to learning-db.md when they discover something.
  • Contributors promote a repeated project-specific lesson into a general heuristic here.

projects/ — per-board workspaces (the build)

Each real board is a folder under projects/ scaffolded from _template/: one directory per phase (00_brief … 12_verification) plus a project.yaml manifest (board params, chosen stackup, current phase, verdicts). This is the only place board-specific geometry and decisions live — the framework itself stays board-agnostic.

  • Engineers work a board here, phase by phase.
  • AI agents read the manifest to know the current phase and drive it.
  • Geometry here is committed immediately (an uncommitted board is one mistake from gone) but is understood to be regenerable from the phase artifacts.

templates/ — source-of-truth blanks

The fill-in-the-blank artifacts copied into each project: build_sheet, net_connection, design_rules, route_sequence, trace_width_table, placement. These define a board completely; the schematic/placement/routing are generated from them. (The generator engine lives in automation/, not here — templates are data, engines are code.)

docs/ — the reference library

The stable, deep engineering essays: philosophy, the 5-layer system architecture, validation methodology, memory/state, human-in-the-loop tiers, design patterns, the honest lessons-learned ledger, and the V2 vision. The operational layers (workflow/, agents/, automation/, knowledge/) link into these for the "why." Contributors keep them evergreen; they change slowly.

Root files

How the pieces interact (one project's life)

  client brief
      │
      ▼
  projects/myboard/  ← scaffolded from templates/ + projects/_template/
      │
      │  the ORCHESTRATOR walks workflow/01 … workflow/12
      ▼
  for each phase:
     agents/<owner>  reads  workflow/<phase>  +  knowledge/*  +  the project manifest
         │  uses  automation/<backend>  to act on the board
         │  emits a structured VERDICT  (PASS / CONDITIONAL / FAIL)
         ▼
     verdict gates entry to the next phase   ← human signs the irreversible ones
      │
      ▼
  new lessons  ──►  knowledge/learning-db.md   (the framework gets smarter)

EasyEDA hosts phases 3–9 (schematic + placement); KiCad hosts phases 10–12 (routing + verification); the browser layer verifies the real board at every step.

How future projects inherit past learnings

This is the long-term payoff and it is deliberate, not incidental:

  1. The framework is shared, the board is not. workflow/, agents/, automation/, knowledge/, templates/ are one copy used by every project in projects/. Improve any of them once and the next board starts ahead.
  2. Lessons flow upward. When an agent hits a new failure on board B, it writes a Heuristic → Why → Instance → Validation → Prevention entry to knowledge/learning-db.md. Board C's agents read it before they act — so C cannot repeat B's mistake.
  3. Heuristics get promoted. A lesson seen on multiple boards graduates from learning-db.md into knowledge/knowledge-graph.md (a general rule) or knowledge/design-standards.md (a hard limit), sometimes into a workflow/ phase gate — the strongest form, where the mistake becomes structurally impossible.
  4. Verdicts are the audit trail. Every phase's dated verdict stays in the project, so a future engineer (or agent) can see exactly why the board is the way it is.

See knowledge/knowledge-inheritance.md for the full mechanism.

Why this is a redesign, not a rearrangement

The old layout was a flat pile of docs and templates — good reference, but it described the method without operationalizing it. This architecture adds the four layers that were missing: an executable process (workflow/), the workers that run it (agents/), the tools they use (automation/), and a place for the work that keeps the framework board-agnostic (projects/) — all wired to a knowledge base that compounds. The method didn't change; it became a machine you can run.