Architecture

Instructions

When this skill is invoked:

1. Parse arguments: first arg is the Jira ticket (e.g., TT-105), remaining args form the title
2. Construct the filename: docs/plans/features/<ticket>-<slugified-title>-architecture.html
3. Read docs/plans/features/architecture-compare-template.html as the base template
4. Ask the main agent to provide the architecture data (or build it from the approved plan). Each node needs:

Node Properties

Edge Properties

5. Replace the four data arrays in the template:

   • BEFORE_NODES — components in the current architecture
   • BEFORE_EDGES — data flow connections in current architecture
   • AFTER_NODES — components after the change (with change annotations)
   • AFTER_EDGES — data flow connections after the change

6. Update identifiers:

   • <title> tag — TICKET — TITLE: Before / After Architecture
   • <h1> — TICKET TITLE
   • AUTOSAVE_KEY — ticket-arch-compare-autosave (lowercase)
   • LAYOUTS_FILE — TICKET-architecture-compare-layouts.json

7. Start the devserver if not running: cd docs/plans/features && python3 docs/architecture-map/_devserver.py <port> &

8. Return the URL: http://localhost:<port>/<filename>.html

Features

The generated playground includes:

• Split/Before/After views — toggle between side-by-side comparison or individual panes
• Draggable nodes — reposition components to clarify layout (positions auto-saved)
• Hover tooltips — show component description
• Click detail panel — shows file path, code snippet, badge, notes
• Change highlighting — After pane nodes marked new (green), modified (amber), removed (red)
• Edge animations — optional flow animation toggle
• Layout persistence — positions saved to localStorage and optionally to a JSON file via PUT

Workflow

This skill fits into the development workflow as:

1. /plan-review TT-XXX Title — high-level plan, section-by-section approval
2. /architecture TT-XXX Title — solidify implementation details with visual architecture
3. Implementation begins

Node Layout Guidelines

Arrange nodes as a top-down tree, not a circular web. The user expects a clear directional flow:

1. Source nodes at the top — data origins (e.g., Brokerage WS, API) get the highest y values (smallest numbers)
2. Processing nodes in the middle — orchestrators, services that transform or route data
3. Sink nodes at the bottom — databases, message buses, terminal outputs get the largest y values
4. Fan-out horizontally — when a node writes to multiple sinks, spread them across the x axis on the same row
5. Center the primary flow — the main data path should run down the center; secondary paths branch left/right

Typical spacing: ~170px vertical gap between tiers, ~200px horizontal gap between siblings.

Before pane example (3-tier):

Source:     x:150, y:30   (centered)
Process:    x:100, y:200  (centered)
Sinks:      x:-90/130/360, y:420  (fanned out left-to-right)

After pane with new intermediate tier:

Source:     x:310, y:44
Process:    x:260, y:206
Middle:     x:466, y:372 / x:466, y:511  (new nodes between process and sinks)
Sinks:      x:-70/96/288, y:682  (fanned out, pushed down)

Avoid circular layouts where edges loop back up. Every edge should flow downward or horizontally — never upward except for explicit feedback/hydration paths.

Layer Colors

Examples

See existing architecture diagrams for reference:

• docs/plans/features/TT-85-architecture-compare.html — Shared InfluxDB processor refactor
• docs/plans/features/TT-64-architecture-compare.html — Reconnect signal refactor
• docs/plans/features/TT-60-architecture-compare.html — Order events scoping