freeroute/docs/ARCHITECTURE.md

# Upstream FreeRouting architecture — a port map

This maps the parts of the FreeRouting Java source (cloned into the gitignored
`reference/freerouting/`) that matter for a Java-free Python port. It was
written by reading the actual source, not the Specctra spec. Package paths here
are verified against the clone (commit fetched via `--depth 1` on
2026-07-11) and **differ from the seed plan's guesses** — the DSN/SES code lives
under `io/specctra/`, not `designforms/specctra/`.

Java root in the clone: `src/main/java/app/freerouting/`.

## 1. Specctra DSN / SES I/O — `io/specctra/`

This is the I/O boundary the port must match: `kicad-cli` produces the `.dsn`
input and consumes the `.ses` output.

### Entry points (`io/specctra/`)
- `DsnReader.java` (294 lines) — the modern read entry point. `readBoard(stream,…)`
  validates the `(pcb <name>` header with a literal three-token check
  (`(` , `pcb` scope keyword, name string), then calls
  `Keyword.PCB_SCOPE.read_scope(par)` to parse the body. `readMetadata(stream)`
  is a fast path that parses only `parser`/`resolution`/`structure` and stops.
  Returns a typed `BoardReadResult` (Success / OutlineMissing / ParseError /
  IoError). Defaults captured here: it flips the scanner to `NAME` state to read
  the pcb name cleanly.
- `SesReader.java` (392) / `SesWriter.java` (430) — session-file read/write.
- `RulesReader.java` / `RulesWriter.java` — `.rules` sidecar files.
- `DsnWriter.java` (97) — DSN writer entry.

### Tokenizer + scope readers (`io/specctra/parser/`)
The lexer is **JFlex-generated** — `SpecctraDsnStreamReader.java` (1467 lines) is
a packed DFA; do **not** port the DFA. The human-readable grammar is in
`SpecctraFileDescription.flex` (312 lines) and that is what to reimplement.
Key lexical facts extracted from the flex file:
- Whitespace: `\r \n \f \t space`. Comments: `#…` to EOL, and `/* … */`.
- Two quote chars: `"` (STRING1) and `'` (STRING2). No escaping — inside a
  quoted string `\` is a literal backslash; the matching quote ends it.
- Keywords are matched case-insensitively (`%ignorecase`) and returned as
  singleton `Keyword` objects; `(` → `OPEN_BRACKET`, `)` → `CLOSED_BRACKET`.
- Non-keyword atoms are returned as `Integer`, `Double`, or `String`.
- **Lexical states are the tricky part.** Several keywords call `yybegin(NAME)`
  (or `LAYER_NAME`, `COMPONENT_NAME`, `SPEC_CHAR`, `IGNORE_QUOTE`) so the *next*
  token is forced to be read as a string even when it looks like a number
  (a net or layer literally named `0`). The Python port reconciles this by
  keeping every unquoted atom as a token that preserves both its raw text and a
  best-effort numeric value, and letting each scope reader decide which to use —
  exactly the decision the lexical state encodes.
- High-level scanner helpers (bottom of `SpecctraDsnStreamReader.java`):
  `next_string(ignoreNewline, leadingSep)`, `next_string_list(sep)`,
  `next_double()`, `next_closing_bracket()`. `next_string` skips leading
  whitespace, handles a leading `"`, and stops at whitespace / `(` / `)` (or a
  caller-supplied separator such as `-` for `Comp-Pin` splitting).

Scope-reader classes (each a recursive-descent reader over the token stream —
this is the structure the Python `reader.py` mirrors):
- `ScopeKeyword.java` — base class. `read_scope` loop: on `(` followed by a
  known `ScopeKeyword`, recurse; unknown scope → `skip_scope` (bracket
  counting). This tolerant skip is the backbone of the whole reader.
- `Parser.java` — `(parser (string_quote ") (host_cad …) (host_version …)
  (constant …) (write_resolution …) (generated_by_freerouting))`.
- `Resolution.java` — `(resolution <unit> <int>)`. Defaults: unit `mil`,
  resolution `100` (set in `ReadScopeParameter`).
- `Structure.java` (1174) — the big one. Reads `layer`, `boundary`, `via`
  (routing via padstack names, incl. `(spare …)`), `rule` (default width/
  clearance), `keepout` / `via_keepout` / `place_keepout`, `plane`, `control
  (via_at_smd on|off)`, `snap_angle`, `autoroute_settings`, `flip_style`. Then
  `create_board` turns it into geometry. `layer`: `(layer <name> (type
  signal|power|jumper) (use_net …) (rule …))`. `boundary`: a shape on layer
  `pcb` is the bounding box; shapes on layer `signal` are the outline.
- `Shape.java` (575) — shape grammar shared everywhere:
  `(rect <layer> x1 y1 x2 y2)`, `(circle <layer> dia [x y])`,
  `(polygon <layer> aperture x1 y1 …)`, `(path <layer> width x1 y1 …)`.
  `read_area_scope` reads an optional name + a border shape + `(window …)` holes
  + optional `(clearance_class …)`.
- `Library.java` (323) — `(library (padstack …) (image …))`.
  `padstack`: name, one or more `(shape (<shape>))`, `(attach on|off)`,
  `(absolute on|off)`. `Package.java` (391) reads `(image <name> (side
  front|back) (pin <padstack> [ (rotate d) ] <pinname> x y) (outline …)
  (keepout …) …)`.
- `Placement.java` / `Component.java` (315) — `(placement (component <libname>
  (place <refdes> x y front|back rot [ (lock_type position) ] [ (PN part) ]
  …)))`. A `place` with no coords means "not yet placed".
- `Network.java` (1193) — `(network (net <name> [subnet] (pins Comp-Pin …)
  (fromto …) (rule …)) (class <name> net… (circuit (use_via …)) (rule …))
  (class_class …))`. Pin refs split component/pin on the first `-`.
- `NetClass.java`, `Net.java`, `Rule.java` (width/clearance rules),
  `AutorouteSettings.java` — supporting readers.
- Data holders: `Layer`, `Padstack`(core), `PinInfo`, `ComponentPlacement`,
  `Circle/Rectangle/Polygon/PolygonPath/PolylinePath`.

**Python port status:** items 1 (tokenizer), the shape grammar, and every
structure/library/network/placement/parser/resolution scope above are
implemented in `src/freeroute/dsn/` this session (see below).

## 2. Board data model — `board/`

Constructed by `Structure.create_board`. Central classes:
- `BasicBoard.java` — geometric item container: insert/delete/pick items,
  layer structure, bounding box, `insert_obstacle`, `insert_via_obstacle`,
  `insert_conduction_area`, `insert_component_obstacle`. `RoutingBoard.java`
  extends it with the routing operations the autorouter drives.
- `Item.java` + subclasses: `Trace`/`PolylineTrace` (a routed wire as a
  `Polyline`), `Via`, `DrillItem`, `Pin`, `ObstacleArea`/`ConductionArea`/
  `ComponentObstacleArea`/`ViaObstacleArea` (keepouts & planes), `BoardOutline`.
- `Component.java` / `Components.java` — placed component instances.
- `Layer.java` / `LayerStructure.java` — signal/power layers, index 0 = top.
- `SearchTreeManager.java` + `ShapeSearchTree*.java` — the spatial index
  (MinAreaTree R-tree variants, one per angle restriction) used for fast
  obstacle queries during routing.
- Shoving/tightening: `ShoveTraceAlgo`, `ForcedPadAlgo`, `ForcedViaAlgo`,
  `PullTightAlgo{,45,90,AnyAngle}`.
- `Unit.java` (mil/inch/mm/um), `CoordinateTransform` (dsn↔board scaling),
  `AngleRestriction` (NINETY / FORTYFIVE / NONE).

**Python translation:** a `board` package of dataclasses + a spatial index.
`Item` hierarchy → dataclasses with a shared base; the search tree → an rtree/
STRtree (shapely) or a hand-rolled bbox tree. Not started this session.

## 3. Planar geometry — `geometry/planar/` (34 files)

The math the router stands on. Key types and their Python analogues:
- `IntPoint` / `IntVector` — integer point/vector (board coords). `FloatPoint`
  (double tuple, not derived from `Point` because float math is inexact) for
  approximate work. `RationalPoint`/`RationalVector` — exact rational
  intersections of lines.
- `Line` / `LineSegment` / `Polyline` — a `Polyline` is a sequence of lines
  whose n lines define n−1 corners; traces are polylines. `Direction`,
  `FortyfiveDegreeDirection` encode the angle grid.
- `Shape` (interface) → `PolylineShape` (straight-line borders) → `TileShape`
  (convex, half-plane intersection) → `Simplex` (general convex) and
  `IntBox`/`IntOctagon` (axis- and 45°-aligned boxes). `ConvexShape`,
  `RegularTileShape` interfaces. `Circle`, `Ellipse` for round pads.
- `Area` / `PolylineArea` — a shape possibly with holes (border + hole shapes).
- `split_to_convex()` (decompose into `TileShape[]`), `convex_hull()`,
  `offset()`, `contains()`, `intersection()` are the workhorse ops.
- `Limits.java` (`CRIT_INT` overflow guard used when picking the coord scale).

**Python translation:** this is the highest-risk port (exact rational geometry,
convex decomposition). Options: lean on `shapely` for polygon ops and add a thin
45°/octagon layer, or port `Simplex`/`TileShape` directly for bit-exact parity
with the JAR oracle. Decide when the board model lands. Not started this session.

## 4. Autorouter core — `autoroute/`

- `BatchAutorouter.java` / `BatchAutorouterThread.java` — the top loop: pick the
  next unrouted connection, route it, rip up and retry on failure, repeat over
  passes. `BatchAutorouterV19.java` is a newer variant; `BatchFanout`,
  `BatchOptimizer{,MultiThreaded}` are the fanout/optimize passes.
- `AutorouteEngine.java` — per-board routing state (expansion rooms, drill pages,
  the maze search driver). Holds the `CompleteFreeSpaceExpansionRoom` graph.
- `MazeSearchAlgo.java` — the A*/Dijkstra maze search over expansion rooms
  ("route an incomplete connection via a maze search"). `MazeSearchElement`,
  `MazeListElement`, `MazeShoveTraceAlgo` (shove obstacles while searching).
- `LocateFoundConnectionAlgo{,45Degree,AnyAngle}.java` — turn a found maze path
  back into concrete trace geometry at the right angle restriction.
- `ExpansionRoom` / `FreeSpaceExpansionRoom` / `ObstacleExpansionRoom` /
  `ExpansionDoor` / `ExpansionDrill` — the free-space decomposition the maze
  search walks. `SortedRoomNeighbours{,45Degree,Orthogonal}` order neighbours.
- `AutorouteControl.java` — cost function parameters (via costs, preferred-
  direction trace costs, ripup costs, start pass number).
- `InsertFoundConnectionAlgo.java` — commit the located connection to the board.

**Python translation:** the last and largest piece. An MVP can start grid/
Manhattan-45° maze routing decoupled from the exact expansion-room model, then
converge toward FreeRouting's free-space rooms. Not started this session.

## 5. Supporting packages (context)
- `rules/` — `BoardRules`, `ClearanceMatrix`, `NetClass`, `Net`, `ViaInfo`,
  `DefaultItemClearanceClasses`. The clearance matrix is class×class×layer.
- `core/` — `Padstack`, `Padstacks`, `Package`, `Packages`, `BoardLibrary`,
  `RoutingJob`. `settings/RouterSettings` holds autoroute config.
- `datastructures/` — `UndoableObjects`, `IndentFileWriter` (the DSN/SES pretty
  printer), `IdentifierType` (quoting on write), identification-number generators.
- `drc/` — design-rule checks. `logger/FRLogger` — logging (warnings collected
  into the read result).

## Port order (this file drives the roadmap)
1. **DSN parser** — done this session (`src/freeroute/dsn/`).
2. **SES writer** — next. Start with an empty/no-op session to prove the loop
   end-to-end through `kicad-cli pcb import specctra-ses`. See `SesWriter.java`
   and `SpecctraSesFileWriter.java`: `(session <name> (base_design <name>)
   (placement …) (was_is) (routes (resolution …) (network_out (net <name>
   (wire (path <layer> <width> x1 y1 …)) (via <padstack> x y)))))`.
3. **Geometry primitives** — `geometry/planar` subset needed by the board model.
4. **Board model** — `board` items + spatial index.
5. **Autorouter** — maze/rip-up core, then optimize pass.
6. **CLI + kicad-mcp integration** — `freeroute board.dsn -o board.ses`.
</content>
</invoke>