Miro Phase 2: Core — drift detection, layout engine, board renderer

[gx-ai-architect]

Phase 2: Core

Build the three core modules that transform analyzed data into Miro board content.

Files to create

File	Description
factory/miro/drift.py	Architecture drift detector
factory/miro/layout.py	Coordinate math / grid layout engine
factory/miro/board.py	Board renderer (Miro API calls)

Key implementation details

drift.py:

• Parses CLAUDE.md ## Architecture sections, README.md, .factory/archive/decisions/, .factory/archive/patterns/
• Regex/heading-based parsing → DocumentedStructure dataclass
• Diffs ProjectStructure (from analyzer) vs DocumentedStructure
• Three drift categories:
  • Undocumented (in code, not docs): red border #FF4444
  • Phantom (in docs, not code): dashed gray #CCCCCC
  • Drifted (structural mismatch): orange border #FF8C00
• Output: list[DriftItem] with category, description, source location

layout.py:

• Pure computation — NO API calls
• 3x2 frame grid positioning
• Top-down flow layout within frames (20px padding)
• 40px gap between frames
• Functions: compute_frame_positions(), layout_items_in_frame(), route_connector()
• Returns positioned items with (x, y, width, height) coordinates

board.py:

• Creates frames FIRST, then items (April 2025 Miro bug — items before parent frame are orphaned)
• Six frames: Project Overview, Agent Pipeline, Architecture Map, Drift Report, Experiment Timeline, Strategy State
• Architecture Map: one shape per module, colored by type using COMPONENT_COLORS
• Connectors from import dependencies
• Uses Miro parent field to bind shapes to frames
• Depends on: client.py, layout.py, templates.py

Conventions

• @dataclass for DocumentedStructure, DriftItem, layout result types
• All types use X | Y syntax
• log = structlog.get_logger() at module level

Dependencies

Requires Phase 1 (client.py, analyzer.py, templates.py).