Vyasa Extension Refactor Audit and Execution Plan

Architecture Decision FrameworkURL copied

Real Seams And Hypothetical SeamsURL copied

The rule is: one adapter means a hypothetical seam; two adapters means a real seam. Do not introduce an exposed interface unless there are real alternatives.

Real seams in Vyasa:

• Markdown fence rendering: adapters include Mermaid, D2, Cytograph, Cryptograph, Tasks, and future fences.

• Layout rendering: adapters include default layout, blog layout, slides layout, and future app/document layouts.

• Asset bundles: adapters include shared shell assets and extension assets.

• Search providers: adapters include default text search, future vector search, future remote search, and disabled search.

• Theme selection: adapters include multiple theme folders selected by one extension.

• Storage namespaces: adapters include bookmarks DB, annotations DB, future task state DB, and future user preference DB.

• Document actions: adapters include print, slides, graph view, task extract, and future export actions.

Hypothetical seams to avoid:

• One file per theme Python module. Use theme data plus one selector extension.

• One route helper module per tiny route if no alternate route adapter exists.

• One class per Markdown helper if the caller still must know the whole rendering sequence.

• One storage abstraction around SQLite if only SQLite exists and tests can use a temp SQLite DB.