mxpic_EDA/docs/superpowers/specs/2026-05-31-required-mxpic-router-stack-design.md

# Required mxpic_router Stack Design

Date: 2026-05-31

## Goal

Unify layout preview and GDS generation behind the same Nazca/mxpic_router
pipeline. `mxpic_router` is no longer an optional routed-only helper. It is a
required runtime package for `mxpic_EDA`, and both repositories should be
released together as a matched pair.

## Current Problem

`Build Layout` currently has two backend preview paths:

- No `bundles.*.links`: `server.py` calls `create_layout_svg_from_gds`, which
  directly places PDK GDS with gdstk.
- With `bundles.*.links`: `server.py` calls `create_routed_layout_svg`, which
  delegates to `mxpic_router`, builds Nazca GDS, then converts that GDS to SVG.

This duplicates layout semantics. Placement-only cells and routed cells can
drift because they are built by different engines. Maintenance is harder
because every future layout feature must be considered in two paths.

## Decision

Use one canonical build path for both preview SVG and project GDS:

`saved YAML -> mxpic_router -> Nazca GDS -> gdstk SVG conversion when needed`

`mxpic_router` and its required build stack are hard dependencies. The Flask
server should verify the whole stack before startup, fail early if anything is
missing, and give an actionable message.

## Dependency Gate

Add `backend/router_dependency.py` as the single backend module responsible for
router dependency validation.

Responsibilities:

- Add the sibling checkout path `../mxpic_router` to `sys.path` when it exists,
  preserving the current local-development pattern.
- Import `mxpic_router.build_project_gds`.
- Import `nazca`, because router output is built as Nazca cells.
- Import `gdstk`, because preview SVG still converts router-generated GDS with
  `gdstk.read_gds(...).top_level()[0].write_svg(...)`.
- Probe the route backend by importing
  `mxpic_router.builder._import_mxpic_forge_route` and calling it. This uses the
  same `mxpic_forge`/`mxpic.Route` lookup that actual router builds use.
- Return a small structured result for startup logging and tests.
- Raise a clear `RuntimeError` when the stack is incomplete.

Server startup should call this check before `app.run`. In script mode, startup
should exit before Flask launches if the dependency gate fails.

## Build Layout Flow

`Build Layout` should always use the router-backed preview path:

`frontend/canvas.html handleBuildLayout` -> POST `/api/save-layout` ->
`backend/server.py save_layout` writes `<cell>.yml` and route sidecar ->
`create_routed_layout_svg(...)` -> `mxpic_router.build_project_gds(...)` with
`target_cell_name=<cell>` -> temporary `.gds` -> `gdstk.write_svg(...)` ->
saved `<cell>.svg`.

There should be no `layout_has_links` branch in `save_layout`. A no-link layout
is still a valid router input; the router builds placed instances and exports
the requested top cell without drawing routes.

`layout_preview.py` can remain in the tree only if it is still useful as a
manual diagnostic module. It should not be used by production preview requests.

## Build GDS Flow

`Build GDS` should always delegate to `mxpic_router`.

`backend/gds_builder.py build_project_gds` should:

- Load saved project YAML files only if needed for validation/error messages.
- Call `_build_with_mxpic_router(...)` as the canonical builder.
- Remove silent fallback to `_build_with_gdstk` and `_build_with_nazca`.
- Raise a clear error if the required router stack is unavailable, though this
  should normally be caught at server startup.

The old fallback functions may be removed if tests and imports no longer need
them. If kept temporarily, they must be clearly marked as unused diagnostics
and not reachable from the production API.

## Error Handling

Dependency failures should be early and explicit:

- Missing `mxpic_router`: tell the operator to install or place the matched
  sibling checkout.
- Missing `nazca`: tell the operator the router runtime cannot build GDS.
- Missing `gdstk`: tell the operator previews cannot convert GDS to SVG.
- Missing route backend: tell the operator routing primitives are unavailable.

Request-time failures should remain JSON API errors, but normal deployment
should fail at startup before users can reach these routes.

## Testing

Update static/backend tests to assert the new contract:

- `server.py` imports and calls the router dependency gate before startup.
- `/api/save-layout` calls `create_routed_layout_svg` unconditionally for
  previews.
- `/api/save-layout` no longer branches on `layout_has_links` to choose
  between gdstk and router preview builders.
- `gds_builder.py` delegates to `_build_with_mxpic_router` without gdstk/Nazca
  production fallback.
- The router dependency module checks `mxpic_router`, `nazca`, `gdstk`, and the
  route backend.
- `GDS_SVG_GENERATION_LOGIC.md` documents the unified path.

Add a runtime smoke test for the local development environment when the required
router stack is installed: a no-link saved YAML cell should generate SVG through
`create_routed_layout_svg`. If CI does not install Nazca/router dependencies,
keep that test explicitly skipped unless the dependency gate passes.

## Release Policy

`mxpic_EDA` and `mxpic_router` should be released simultaneously.

Recommended lightweight policy:

- Update deployment notes to state that both repositories must be deployed as a
  matched pair.
- Keep a visible compatibility note in `README.md` or deployment docs.
- Version compatibility checks are out of scope until both repositories expose
  explicit version constants; until then, deployment docs carry the matched-pair
  release requirement.

## Non-Goals

- Do not redesign the frontend YAML format in this change.
- Do not vendor/copy `mxpic_router` source into `mxpic_EDA`.
- Do not replace gdstk SVG conversion in this change; it remains the converter
  after router-generated GDS.
- Do not add fallback behavior that hides a missing or incompatible router
  stack.