sysatlas 0.2.0__py3-none-any.whl

sysatlas/LLM_GUIDE.md

@@ -0,0 +1,151 @@
+# sysatlas — LLM guide
+
+You are a coding assistant working in a project that has `sysatlas`
+installed. This file tells you how to use it. Read all of it before
+writing or editing any sysatlas-related code.
+
+## What sysatlas is
+
+A Python library for **interactive architecture diagrams**. Diagrams
+are defined in code (Pydantic-backed builders) and rendered to a
+self-contained HTML file with an embedded draw.io viewer.
+
+Two halves of the workflow exist in the same library:
+
+- **Forward flow** — a human (or you) writes builder calls to describe
+  a system that does not exist yet, or that exists only as a design.
+- **Backward flow** — `sysatlas.reflect(path)` reads existing Python
+  code and produces a diagram from its real structure.
+
+The realistic case is a mix: structure comes from reflection,
+semantics (qualities, traces, viewpoints, stakeholders) come from a
+human-authored "annotation overlay" that gets merged in.
+
+## Your responsibility in this project
+
+After you add, remove, or rename a module, class, or component, the
+diagrams under `docs/reflection/` (or wherever this project keeps
+them — check the project README) are stale. Regenerate them. The
+canonical commands:
+
+```python
+import sysatlas
+r = sysatlas.reflect("path/to/source/root")
+m = r.to_system_map(title="…")
+m.save("docs/reflection/module-map.html")
+```
+
+If the project has a hints file at the source root, `reflect()` will
+pick it up automatically — do not edit hints unless the user asks.
+Lookup order: `sysatlas.json` (always supported), then
+`sysatlas.yaml` / `sysatlas.yml` (only if PyYAML is installed).
+
+If the project has an "annotation overlay" `.py` file (typical
+location: `docs/reflection/_overlay.py`), call `r.merge_with(overlay)`
+before `save()` so user-authored qualities and traces are preserved.
+
+## Public API — the only symbols you should use
+
+```python
+import sysatlas
+
+sysatlas.SystemMap      # one architecture diagram
+sysatlas.System         # multi-view Architecture Description (ISO 42010)
+sysatlas.TreeMap        # tree / org-chart / mindmap
+sysatlas.SequenceMap    # UML sequence diagram
+sysatlas.ERMap          # Entity-Relationship diagram
+sysatlas.StateMap       # state machine / state chart
+sysatlas.ClassMap       # UML class diagram
+sysatlas.BPMNMap        # BPMN process diagram
+sysatlas.reflect(path)  # reverse flow: code → Reflection → SystemMap
+sysatlas.llm_guide()    # returns this file as a string
+```
+
+Do **not** import from `sysatlas._*` (private modules — `_ontology`,
+`_layout`, `_route`, etc.). The Pydantic schemas under
+`sysatlas._ontology` are the source of truth for field names, but you
+should reach them only through the builder methods.
+
+Each `*Map` is fluent and follows the same shape: chainable methods,
+`.diagram` for the validated Pydantic instance, `.show()` / `.save()`
+to render. For the per-kind **builder methods** check `docs/builders.md`
+and the matching `docs/ontology/<kind>.md` § Builder. The
+`sysatlas/_ontology/<kind>.py` files are the source of truth for
+*schema field names*, not for builder method names.
+
+## Forward flow — minimal example
+
+```python
+import sysatlas
+
+m = sysatlas.SystemMap(title="Storefront")
+m.group("services", color="#dcfce7")
+m.add_component("api", group="services", layer="services", tech="Envoy")
+m.add_component("catalog", group="services", layer="services", tech="Python")
+m.connect("api", "catalog", label="REST")
+m.save("storefront.html")
+```
+
+The builder is fluent. `layer` is a free-form string — the ontology
+does not enforce a fixed set. Recommended defaults for the default
+(`layered`) strategy are `edge`, `services`, `data`, `infra`,
+`external`; pick whatever vocabulary fits the diagram. Note that
+`strategy="hub"` reserves five layer names with specific placement
+meaning (`interfaces`, `write`, `hub`, `read`, `external`) — any
+other layer under the hub strategy is treated as `external`.
+`tech=` is metadata-only and is not rendered — if you want the tech
+visible, put it in `label=`.
+
+## Multi-view (`System`) — when one diagram is too dense
+
+Use `System` when you have more than ~10 components or more than one
+clear bounded context. Each view is a separate `SystemMap`. Components
+referenced across views auto-render as stub nodes.
+
+```python
+s = sysatlas.System(title="E-Commerce")
+s.viewpoint("container", model_kinds=["architecture"])
+sf = s.architecture_model("storefront")
+sf.add_component("Cart").add_component("Catalog").connect("Cart", "Catalog")
+pm = s.architecture_model("payments")
+pm.add_component("Payments")
+s.view("storefront-view", viewpoint="container", models=["storefront"])
+s.view("payments-view",   viewpoint="container", models=["payments"])
+s.trace("storefront#Cart", "payments#Payments", kind="depends_on")
+s.save("system.html")
+```
+
+## Backward flow — reflection
+
+```python
+r = sysatlas.reflect("src/")           # AST-only, never imports the code
+r.exclude("tests/*", "_vendor.py")
+m = r.to_system_map(title="src internals")
+m.save("docs/reflection/module-map.html")
+```
+
+`reflect()` does not execute the target code. Dynamic imports are
+invisible to it — accept the trade-off, do not try to work around it
+by adding `importlib` calls.
+
+## Hard rules
+
+- Use the public symbols above; do not import from `sysatlas._*`.
+- Use Pydantic; never `@dataclass`.
+- Field names must match the ontology exactly. If unsure, check the
+  matching Pydantic class under `sysatlas/_ontology/` (read-only):
+  `architecture.py`, `sequence.py`, `er.py`, `state_machine.py`,
+  `uml_class.py`, `bpmn.py`, `tree.py`.
+- One view = 5–10 components. If a diagram is bigger, split it across
+  views with `System`, do not fight the layout engine.
+- After any structural code change, regenerate the affected reflection
+  diagrams. This is your job, not the user's.
+- Do not invent fields. The ontology is closed (`ConfigDict(extra="forbid")`
+  on most models).
+
+## Where to find more
+
+- Full builder reference: `docs/builders.md` in the source repo.
+- Per-ontology specs: `docs/ontology/` in the source repo.
+- Design principles (bounded complexity, multi-view): `docs/design-principles.md`.
+- This guide on disk: `sysatlas.llm_guide_path()`.

sysatlas/__init__.py

@@ -0,0 +1,50 @@
+"""sysatlas — interactive architecture diagrams in two directions.
+
+Forward flow: write builder calls (`SystemMap`, `System`, `TreeMap`)
+to describe a system as a design. Backward flow: `sysatlas.reflect(path)`
+reads existing Python and produces the same diagram types from real code.
+
+If you are an LLM helping a user with this library, call
+`sysatlas.llm_guide()` first — it is the canonical usage contract.
+"""
+
+from pathlib import Path
+
+from sysatlas._reflection.reflection import Reflection, reflect, reflect_rust
+from sysatlas.bpmn_map import BPMNMap
+from sysatlas.class_map import ClassMap
+from sysatlas.er_map import ERMap
+from sysatlas.sequence_map import SequenceMap
+from sysatlas.state_map import StateMap
+from sysatlas.system import System
+from sysatlas.system_map import SystemMap
+from sysatlas.tree_map import TreeMap
+
+__all__ = [
+    "SystemMap",
+    "System",
+    "TreeMap",
+    "SequenceMap",
+    "ERMap",
+    "StateMap",
+    "ClassMap",
+    "BPMNMap",
+    "Reflection",
+    "reflect",
+    "reflect_rust",
+    "llm_guide",
+    "llm_guide_path",
+]
+__version__ = "0.2.0"
+
+_LLM_GUIDE = Path(__file__).parent / "LLM_GUIDE.md"
+
+
+def llm_guide() -> str:
+    """Return the bundled LLM usage guide as a markdown string."""
+    return _LLM_GUIDE.read_text(encoding="utf-8")
+
+
+def llm_guide_path() -> str:
+    """Return the absolute path of the bundled LLM usage guide."""
+    return str(_LLM_GUIDE)

sysatlas/_bpmn_layout.py

@@ -0,0 +1,157 @@
+"""BPMN diagram layout.
+
+Pools contain horizontal lanes. Inside each lane, nodes (events,
+activities, gateways) are placed left-to-right in BFS order from start
+events. Pools stack vertically.
+"""
+from __future__ import annotations
+
+from collections import defaultdict, deque
+
+POOL_HEADER_W = 30
+LANE_HEADER_W = 24
+LANE_H = 120
+NODE_GAP = 60
+LANE_PAD_X = 20
+LANE_PAD_Y = 16
+MARGIN = 30
+
+ACTIVITY_W = 110
+ACTIVITY_H = 60
+EVENT_R = 28
+GATEWAY_W = 44
+
+
+def node_size(kind: str) -> tuple[int, int]:
+    if kind in ("start", "end", "intermediate", "timer", "message", "error"):
+        return EVENT_R * 2, EVENT_R * 2
+    if kind in ("exclusive", "parallel", "inclusive", "event_based"):
+        return GATEWAY_W, GATEWAY_W
+    return ACTIVITY_W, ACTIVITY_H
+
+
+def compute_bpmn_layout(diagram):
+    """Return (positions, sizes, pool_rects, lane_rects, routes, all_nodes)."""
+    pools = list(diagram.pools.values())
+    lanes_by_pool: dict[str, list] = defaultdict(list)
+    for lane in diagram.lanes.values():
+        lanes_by_pool[lane.pool].append(lane)
+
+    all_nodes: dict[str, tuple[str, str]] = {}  # name -> (kind_category, kind)
+    node_lane: dict[str, str | None] = {}
+    for e in diagram.events.values():
+        all_nodes[e.name] = ("event", e.kind)
+        node_lane[e.name] = e.lane
+    for a in diagram.activities.values():
+        all_nodes[a.name] = ("activity", a.kind)
+        node_lane[a.name] = a.lane
+    for g in diagram.gateways.values():
+        all_nodes[g.name] = ("gateway", g.kind)
+        node_lane[g.name] = g.lane
+
+    nodes_by_lane: dict[str | None, list[str]] = defaultdict(list)
+    for name, lane in node_lane.items():
+        nodes_by_lane[lane].append(name)
+
+    adj: dict[str, list[str]] = defaultdict(list)
+    in_deg: dict[str, int] = defaultdict(int)
+    for f in diagram.flows:
+        if f.kind == "sequence" or f.kind == "default" or f.kind == "conditional":
+            adj[f.source].append(f.target)
+            in_deg[f.target] += 1
+
+    order: dict[str, int] = {}
+    starts = [n for n in all_nodes if in_deg[n] == 0 and all_nodes[n][0] == "event"]
+    if not starts:
+        starts = [n for n in all_nodes if in_deg[n] == 0]
+    queue: deque[str] = deque()
+    for s in starts:
+        order[s] = 0
+        queue.append(s)
+    while queue:
+        cur = queue.popleft()
+        for nb in adj.get(cur, []):
+            new_order = order[cur] + 1
+            if nb not in order or new_order > order[nb]:
+                order[nb] = new_order
+                queue.append(nb)
+    next_o = max(order.values(), default=-1) + 1
+    for n in all_nodes:
+        if n not in order:
+            order[n] = next_o
+            next_o += 1
+
+    pool_rects: list[dict] = []
+    lane_rects: list[dict] = []
+    pos: dict[str, tuple[int, int]] = {}
+    size: dict[str, tuple[int, int]] = {}
+
+    pool_y = MARGIN
+    inner_x = LANE_HEADER_W + LANE_PAD_X
+    column_pitch = max(ACTIVITY_W, EVENT_R * 2, GATEWAY_W) + NODE_GAP
+    max_order = max(order.values(), default=0)
+    lane_inner_w = inner_x + (max_order + 1) * column_pitch + LANE_PAD_X
+
+    for pool in pools:
+        lanes = lanes_by_pool.get(pool.name, [])
+        if not lanes:
+            from sysatlas._ontology.bpmn import Lane
+            lanes = [Lane(name=f"__default_{pool.name}__", pool=pool.name)]
+            lanes_by_pool[pool.name] = lanes
+
+        pool_h = LANE_H * len(lanes)
+        pool_w = POOL_HEADER_W + lane_inner_w
+        pool_x = MARGIN
+        pool_rects.append({
+            "name": pool.name,
+            "label": pool.label or pool.name,
+            "x": pool_x, "y": pool_y,
+            "w": pool_w, "h": pool_h,
+        })
+
+        for i, lane in enumerate(lanes):
+            lx = pool_x + POOL_HEADER_W
+            ly = pool_y + i * LANE_H
+            lane_rects.append({
+                "name": lane.name,
+                "label": lane.label or lane.name,
+                "x": lx, "y": ly,
+                "w": lane_inner_w, "h": LANE_H,
+            })
+            lane_center_y = ly + LANE_H // 2
+            nodes_here = sorted(nodes_by_lane.get(lane.name, []), key=lambda n: order[n])
+            for n in nodes_here:
+                cat, kind = all_nodes[n]
+                w, h = node_size(kind)
+                nx = lx + LANE_HEADER_W + LANE_PAD_X + order[n] * column_pitch
+                ny = lane_center_y - h // 2
+                pos[n] = (nx, ny)
+                size[n] = (w, h)
+        pool_y += pool_h + MARGIN
+
+    # Place nodes with no lane assignment into a fallback row
+    orphans = nodes_by_lane.get(None, [])
+    if orphans:
+        ly = pool_y
+        lane_rects.append({
+            "name": "__orphan__", "label": "(no lane)",
+            "x": MARGIN, "y": ly,
+            "w": lane_inner_w + POOL_HEADER_W, "h": LANE_H,
+        })
+        for n in sorted(orphans, key=lambda x: order[x]):
+            cat, kind = all_nodes[n]
+            w, h = node_size(kind)
+            nx = MARGIN + POOL_HEADER_W + LANE_PAD_X + order[n] * column_pitch
+            ny = ly + LANE_H // 2 - h // 2
+            pos[n] = (nx, ny)
+            size[n] = (w, h)
+
+    routes: list[dict] = []
+    for f in diagram.flows:
+        if f.source not in pos or f.target not in pos:
+            continue
+        routes.append({
+            "source": f.source, "target": f.target,
+            "kind": f.kind, "label": f.label,
+        })
+    return pos, size, pool_rects, lane_rects, routes, all_nodes

sysatlas/_bpmn_render.py

@@ -0,0 +1,154 @@
+"""Render a BPMNDiagram to draw.io / mxGraph XML."""
+from __future__ import annotations
+
+import json
+import xml.etree.ElementTree as ET
+
+from sysatlas._bpmn_layout import compute_bpmn_layout
+from sysatlas._render import _FIT_JS, _VIEWER_CONFIG, _html_shell, _viewer_tag
+
+_POOL_STYLE = (
+    "shape=swimlane;startSize=30;horizontal=0;fillColor=#f8fafc;"
+    "strokeColor=#475569;fontSize=11;fontStyle=1;align=center;"
+)
+_LANE_STYLE = (
+    "shape=swimlane;startSize=24;horizontal=0;fillColor=#ffffff;"
+    "strokeColor=#94a3b8;fontSize=10;align=center;"
+)
+_ACTIVITY_STYLE = {
+    "task":         "rounded=1;arcSize=18;whiteSpace=wrap;html=1;fillColor=#dbeafe;strokeColor=#1e40af;fontSize=10;",
+    "user_task":    "rounded=1;arcSize=18;whiteSpace=wrap;html=1;fillColor=#dcfce7;strokeColor=#15803d;fontSize=10;",
+    "service_task": "rounded=1;arcSize=18;whiteSpace=wrap;html=1;fillColor=#fef3c7;strokeColor=#a16207;fontSize=10;",
+    "subprocess":   "rounded=1;arcSize=18;whiteSpace=wrap;html=1;fillColor=#e9d5ff;strokeColor=#7e22ce;fontSize=10;strokeWidth=2;",
+    "call_activity":"rounded=1;arcSize=18;whiteSpace=wrap;html=1;fillColor=#fce7f3;strokeColor=#be185d;fontSize=10;strokeWidth=2;",
+}
+_EVENT_STYLE = {
+    "start":        "ellipse;whiteSpace=wrap;html=1;fillColor=#dcfce7;strokeColor=#15803d;strokeWidth=2;fontSize=9;",
+    "end":          "ellipse;whiteSpace=wrap;html=1;fillColor=#fecaca;strokeColor=#b91c1c;strokeWidth=3;fontSize=9;",
+    "intermediate": "ellipse;whiteSpace=wrap;html=1;fillColor=#fef3c7;strokeColor=#a16207;strokeWidth=2;fontSize=9;",
+    "timer":        "ellipse;whiteSpace=wrap;html=1;fillColor=#fef3c7;strokeColor=#a16207;strokeWidth=2;fontSize=9;",
+    "message":      "ellipse;whiteSpace=wrap;html=1;fillColor=#dbeafe;strokeColor=#1e40af;strokeWidth=2;fontSize=9;",
+    "error":        "ellipse;whiteSpace=wrap;html=1;fillColor=#fecaca;strokeColor=#b91c1c;strokeWidth=2;fontSize=9;",
+}
+_GATEWAY_STYLE = {
+    "exclusive":   "rhombus;whiteSpace=wrap;html=1;fillColor=#fef9c3;strokeColor=#a16207;fontSize=14;fontStyle=1;",
+    "parallel":    "rhombus;whiteSpace=wrap;html=1;fillColor=#dcfce7;strokeColor=#15803d;fontSize=14;fontStyle=1;",
+    "inclusive":   "rhombus;whiteSpace=wrap;html=1;fillColor=#fce7f3;strokeColor=#be185d;fontSize=14;fontStyle=1;",
+    "event_based": "rhombus;whiteSpace=wrap;html=1;fillColor=#dbeafe;strokeColor=#1e40af;fontSize=14;fontStyle=1;",
+}
+_GATEWAY_GLYPH = {
+    "exclusive": "✕", "parallel": "+", "inclusive": "O", "event_based": "◇",
+}
+_FLOW_STYLE = {
+    "sequence":    "endArrow=block;endFill=1;html=1;rounded=0;strokeColor=#1f2937;fontSize=10;",
+    "message":     "endArrow=open;dashed=1;html=1;rounded=0;strokeColor=#6366f1;fontSize=10;",
+    "default":     "endArrow=block;endFill=1;html=1;rounded=0;strokeColor=#1f2937;startArrow=oval;startFill=0;startSize=8;fontSize=10;",
+    "conditional": "endArrow=block;endFill=1;html=1;rounded=0;strokeColor=#1f2937;startArrow=diamondThin;startFill=0;startSize=10;fontSize=10;",
+}
+
+
+def build_bpmn_xml(diagram) -> str:
+    pos, size, pool_rects, lane_rects, routes, all_nodes = compute_bpmn_layout(diagram)
+
+    root_el = ET.Element(
+        "mxGraphModel",
+        dx="1422", dy="762", grid="1", gridSize="10", guides="1", tooltips="1",
+        connect="1", arrows="1", fold="1", page="1", pageScale="1",
+        pageWidth="1169", pageHeight="827", math="0", shadow="0",
+    )
+    root = ET.SubElement(root_el, "root")
+    ET.SubElement(root, "mxCell", id="0")
+    ET.SubElement(root, "mxCell", id="1", parent="0")
+
+    cell_id = 2
+
+    for p in pool_rects:
+        c = ET.SubElement(root, "mxCell", id=str(cell_id), value=p["label"],
+                          style=_POOL_STYLE, vertex="1", parent="1")
+        ET.SubElement(c, "mxGeometry", x=str(p["x"]), y=str(p["y"]),
+                      width=str(p["w"]), height=str(p["h"]), **{"as": "geometry"})
+        cell_id += 1
+
+    for l in lane_rects:
+        c = ET.SubElement(root, "mxCell", id=str(cell_id), value=l["label"],
+                          style=_LANE_STYLE, vertex="1", parent="1")
+        ET.SubElement(c, "mxGeometry", x=str(l["x"]), y=str(l["y"]),
+                      width=str(l["w"]), height=str(l["h"]), **{"as": "geometry"})
+        cell_id += 1
+
+    node_cell_ids: dict[str, str] = {}
+    for name, (cat, kind) in all_nodes.items():
+        if name not in pos:
+            continue
+        x, y = pos[name]
+        w, h = size[name]
+        if cat == "event":
+            style = _EVENT_STYLE.get(kind, _EVENT_STYLE["intermediate"])
+            label = diagram.events[name].label or name
+        elif cat == "activity":
+            style = _ACTIVITY_STYLE.get(kind, _ACTIVITY_STYLE["task"])
+            label = diagram.activities[name].label or name
+        else:
+            style = _GATEWAY_STYLE.get(kind, _GATEWAY_STYLE["exclusive"])
+            label = _GATEWAY_GLYPH.get(kind, "")
+        c = ET.SubElement(root, "mxCell", id=str(cell_id), value=label,
+                          style=style, vertex="1", parent="1")
+        ET.SubElement(c, "mxGeometry", x=str(x), y=str(y),
+                      width=str(w), height=str(h), **{"as": "geometry"})
+        node_cell_ids[name] = str(cell_id)
+        cell_id += 1
+
+    for r in routes:
+        s_id = node_cell_ids.get(r["source"])
+        t_id = node_cell_ids.get(r["target"])
+        if not s_id or not t_id:
+            continue
+        style = _FLOW_STYLE.get(r["kind"], _FLOW_STYLE["sequence"])
+        c = ET.SubElement(root, "mxCell", id=str(cell_id), value=r["label"],
+                          style=style, edge="1",
+                          source=s_id, target=t_id, parent="1")
+        ET.SubElement(c, "mxGeometry", relative="1", **{"as": "geometry"})
+        cell_id += 1
+
+    return ET.tostring(root_el, encoding="unicode", xml_declaration=False)
+
+
+def render_bpmn(diagram, title: str = "", viewer: str = "cdn") -> str:
+    xml = build_bpmn_xml(diagram)
+    xml_json = json.dumps(xml)
+    config_json = json.dumps(_VIEWER_CONFIG)
+    css = """
+  body { display: flex; align-items: center; justify-content: center; }
+  #diagram {
+    border: 1px solid #cbd5e1;
+    box-shadow: 0 4px 16px rgba(0,0,0,0.12);
+    background: #ffffff;
+    overflow: hidden;
+    position: relative;
+  }
+"""
+    body = '<div id="diagram"></div>'
+    script = f"""
+{_FIT_JS}
+var xmlStr = {xml_json};
+var config = {config_json};
+var container = document.getElementById('diagram');
+function setSize() {{
+  container.style.width  = Math.round(window.innerWidth  * 0.85) + 'px';
+  container.style.height = Math.round(window.innerHeight * 0.85) + 'px';
+}}
+setSize();
+if (typeof GraphViewer === 'undefined' || typeof mxUtils === 'undefined') {{
+  container.innerHTML = '<div style="padding:32px;font-family:sans-serif;color:#7f1d1d;">' +
+    '<strong>draw.io viewer not loaded.</strong></div>';
+}} else {{
+  var xmlDoc = mxUtils.parseXml(xmlStr);
+  var viewer = new GraphViewer(container, xmlDoc.documentElement, config);
+  setTimeout(function() {{ fitGraph(viewer, container); }}, 50);
+  window.addEventListener('resize', function() {{
+    setSize();
+    fitGraph(viewer, container);
+  }});
+}}
+"""
+    return _html_shell(title, body, _viewer_tag(viewer), script, css)

sysatlas/_connectors.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+LONG_LAYER_THRESHOLD = 3   # edges spanning >= this many ranks become connectors
+
+
+def classify_edges(
+    edges: list[dict],
+    rank: dict[str, int],
+) -> tuple[list[dict], list[dict]]:
+    """Split edges into (direct, connector_pairs).
+
+    direct: regular edges to be routed normally.
+    connector_pairs: edges that should be drawn as two off-page connector glyphs
+                     instead of a single long line.
+    """
+    direct: list[dict] = []
+    connectors: list[dict] = []
+    for e in edges:
+        s, t = e["source"], e["target"]
+        if s not in rank or t not in rank:
+            direct.append(e)
+            continue
+        span = abs(rank[t] - rank[s])
+        if span >= LONG_LAYER_THRESHOLD and not e.get("no_connector"):
+            connectors.append(e)
+        else:
+            direct.append(e)
+    return direct, connectors

sysatlas/_hub_layout.py

@@ -0,0 +1,111 @@
+"""Hub-and-spoke placement for read/write-loop architectures.
+
+This module only computes node positions. Edge routing (A*, port
+assignment, obstacle avoidance, label placement) is delegated to the
+strategy-agnostic `_layout.finalize_routing` so the hub strategy gets
+the same routing quality as the layered strategy without duplicating
+work.
+
+Region assignment by `Component.layer`:
+
+    "interfaces"  → top band, horizontal stack
+    "write"       → left column, vertical stack (writes into hub)
+    "hub"         → centre, single component expected (rendered taller)
+    "read"        → right column, vertical stack (reads from hub)
+    "external"    → bottom band, horizontal stack
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+from sysatlas._layout import NODE_W, NODE_H, finalize_routing
+
+_GAP_X = 120
+_GAP_Y = 80
+_MARGIN = 100
+
+_HUB_W = 220
+_HUB_H = 140
+
+
+def _spread(xs_centre: int, names: list[str], gap: int = _GAP_X) -> list[int]:
+    if not names:
+        return []
+    total = len(names) * NODE_W + (len(names) - 1) * gap
+    start = xs_centre - total // 2
+    return [start + i * (NODE_W + gap) for i in range(len(names))]
+
+
+_RESERVED = ("interfaces", "write", "hub", "read", "external")
+
+
+def _place(nodes: dict[str, dict]) -> tuple[dict[str, tuple[int, int]], dict[str, int]]:
+    by_layer: dict[str, list[str]] = defaultdict(list)
+    for n, data in nodes.items():
+        layer = data.get("layer")
+        # Unknown layers fall into "external" so every node gets a position.
+        if layer not in _RESERVED:
+            layer = "external"
+        by_layer[layer].append(n)
+
+    interfaces = by_layer.get("interfaces", [])
+    writes     = by_layer.get("write", [])
+    hubs       = by_layer.get("hub", [])
+    reads      = by_layer.get("read", [])
+    externals  = by_layer.get("external", [])
+
+    rows_mid = max(1, len(writes), len(reads))
+    mid_band_h = rows_mid * NODE_H + (rows_mid - 1) * _GAP_Y
+
+    cx = _MARGIN + max(
+        NODE_W + _GAP_X + _HUB_W // 2,
+        len(interfaces) * (NODE_W + _GAP_X) // 2,
+        len(externals)  * (NODE_W + _GAP_X) // 2,
+    )
+
+    top_y    = _MARGIN
+    mid_top  = top_y + (NODE_H + _GAP_Y if interfaces else 0)
+    hub_y    = mid_top + (mid_band_h - _HUB_H) // 2
+    mid_end  = mid_top + mid_band_h
+    bot_y    = mid_end + _GAP_Y
+
+    pos: dict[str, tuple[int, int]] = {}
+    node_heights: dict[str, int] = {}
+
+    for x, name in zip(_spread(cx, interfaces), interfaces):
+        pos[name] = (x, top_y)
+    for x, name in zip(_spread(cx, externals), externals):
+        pos[name] = (x, bot_y)
+
+    write_x = cx - (_HUB_W // 2 + _GAP_X + NODE_W)
+    for i, name in enumerate(writes):
+        pos[name] = (write_x, mid_top + i * (NODE_H + _GAP_Y))
+
+    read_x = cx + _HUB_W // 2 + _GAP_X
+    for i, name in enumerate(reads):
+        pos[name] = (read_x, mid_top + i * (NODE_H + _GAP_Y))
+
+    if hubs:
+        hub_x = cx - _HUB_W // 2
+        pos[hubs[0]] = (hub_x, hub_y)
+        node_heights[hubs[0]] = _HUB_H
+        for k, name in enumerate(hubs[1:], start=1):
+            pos[name] = (hub_x, hub_y + k * (_HUB_H + _GAP_Y))
+            node_heights[name] = _HUB_H
+
+    return pos, node_heights
+
+
+def compute_hub_layout(
+    nodes: dict[str, dict],
+    edges: list[dict],
+    layer_order: list[str],
+    debug: bool = False,
+) -> tuple[dict[str, tuple[int, int]], dict[tuple[str, str], dict], dict[str, int]]:
+    """Place nodes hub-and-spoke, then route edges with the shared A* pipeline."""
+    pos, hub_heights = _place(nodes)
+    routes, node_heights = finalize_routing(pos, nodes, edges,
+                                            layer_order=layer_order,
+                                            fixed_heights=hub_heights,
+                                            debug=debug)
+    return pos, routes, node_heights