Skip to content

prd.md

Latest commit

 

History

History
324 lines (229 loc) · 10.2 KB

prd.md

File metadata and controls

324 lines (229 loc) · 10.2 KB

Product Requirements Document (PRD)

Project: Markdown‑Driven Diagram Rendering Engine (Text → SVG)

1. Overview

This project provides a standalone, pluggable, text‑to‑SVG diagram rendering engine.
It accepts diagram source text (e.g., Mermaid, Conceptual DSL, future formats) and outputs high‑quality SVG. It is built in .NET 10 and includes a library and a CLI runner that can be invoked via dnx.

The engine is:

  • Markdown‑friendly (but not tied to any Markdown processor)
  • Format‑agnostic (input is just diagram text)
  • Client‑agnostic (Marp, static site generators, PPTX converters, editors, etc.)
  • Extensible (pluggable parsers for new diagram syntaxes)
  • Focused on modern, slide‑friendly aesthetics

The engine does not parse Markdown itself.
Clients (e.g., MarpToPptx, Obsidian plugins, CLI tools) are responsible for extracting diagram text blocks and passing them to this renderer.

2. Goals & Non‑Goals

2.1 Goals

  • Provide a clean API: input = diagram text, output = SVG.
  • Support a subset of Mermaid as the initial diagram syntax.
  • Introduce a Conceptual Diagram DSL for SmartArt‑style conceptual diagrams.
  • Normalize all diagram inputs into a unified semantic model.
  • Render diagrams as modern, clean SVGs with:
    • Rounded corners
    • Modern palettes
    • Consistent spacing
    • Slide‑friendly proportions
  • Provide a pluggable parser architecture for future syntaxes (e.g., D2, DOT).
  • Remain independent of any specific client (Marp, PPTX, web apps, etc.).
  • Support for themes and palletes, both built-in and user supplied.
  • Leverage existing ecosystem. Refer to https://github.com/mermaid-js/mermaid for specification and transpile open source code (with attribution) if possible.

2.2 Non‑Goals

  • Full Mermaid feature parity.
  • D2 support in v1.
  • Native PowerPoint chart generation (handled by other systems).
  • Markdown parsing or extraction of code blocks.
  • Browser‑based rendering or JS runtime dependency.
  • Reproducing SmartArt exactly; instead, provide modern equivalents.
  • Adding Conceptual DSL diagram types that are already easy to express in Mermaid.

3. Target Users

  • Developers embedding diagrams in documentation or slide pipelines.
  • Tools that need deterministic, theme‑able SVG diagrams.
  • Markdown‑based workflows (Marp, MkDocs, Obsidian, static site generators).
  • Presentation pipelines that need conceptual diagrams without manual editing.

4. High‑Level Architecture

Diagram Text (Mermaid, Conceptual DSL, etc.)
   ↓
Parser (pluggable)
   ↓
Unified Semantic Diagram Model
   ↓
Layout Engine (slide‑optimized)
   ↓
SVG Renderer (.NET)
   ↓
Output: SVG string or stream

4.1 Pluggable Parser Architecture

Each parser implements:

  • IDiagramParser
  • IDiagramSemanticModelBuilder

Parsers convert raw text → semantic model.
Renderers never depend on specific syntaxes.

4.2 Unified Semantic Diagram Model

Core primitives:

  • Diagram
  • Node
  • Edge
  • Group / Container
  • Label
  • Shape (rectangle, circle, pill, diamond, etc.)
  • LayoutHints (direction, spacing, alignment)
  • Theme (colors, fonts, border radius)

4.3 Rendering Engine

  • Deterministic layout
  • Modern design defaults
  • Theme‑driven styling
  • SVG output only
  • No browser engines or JS runtimes

5. Supported Diagram Types (v1)

5.1 Mermaid Subset

  • Flowchart (LR, TB)
  • Hierarchy (flowchart or mindmap subset)
  • Timeline
  • Block diagram
  • Simple relationship diagrams

5.2 Conceptual Diagram DSL

SmartArt‑inspired conceptual diagrams:

  • Matrix (2×2, 3×3)
  • Pyramid (segmented, labeled)
  • Cycle (3–6 steps, radial layout)

Selection rule:

  • The Conceptual DSL is reserved for presentation-native layouts whose main value is their slide-oriented visual form, not generic node-and-edge semantics.
  • If a diagram is already straightforward to create with Mermaid, prefer Mermaid instead of adding a parallel conceptual type.

Examples that should use Mermaid rather than the Conceptual DSL:

  • Venn / overlapping sets
  • Generic relationship diagrams
  • Timelines and simple roadmaps

Examples that remain good candidates for the Conceptual DSL:

  • Matrix
  • Pyramid
  • Cycle ✓ (implemented)
  • Tree / hierarchy / org chart (indent-based syntax with optional style: orgchart preset; Mermaid flowchart/mindmap produces materially worse results for formal tree structures)
  • Funnel
  • Chevron process
  • Radial / hub-and-spoke
  • Pillars / stacked segments

5.3 Wireframe DSL

Low-fidelity wireframe diagrams based on the markdown-ui-dsl syntax. The wireframe parser implements a focused subset of the DSL to render UI mockups as self-contained SVG.

Supported component subset:

  • Container primitives: column, row, card, header, footer
  • Form elements: text input, checkbox, radio button, toggle, dropdown
  • Navigation: tab bar (active/inactive states)
  • Content: heading, body text, badge (inline with trailing text), image placeholder, divider
  • Actions: button (primary via link syntax, secondary via plain brackets)
  • Layout: === ROW === for horizontal arrangement, ::: CARD ::: for grouped content, *** dividers, indent-based nesting

Selection rule:

  • Use the wireframe DSL when the goal is a quick, theme-able, low-fidelity UI sketch inside a slide or document.
  • The wireframe DSL is not a UI framework; it renders static SVG of standard UI widget shapes.
  • All wireframe colors are derived from the four semantic theme properties (BackgroundColor, TextColor, SubtleTextColor, AccentColor) via WireframePalette, so every built-in theme works out of the box including dark themes.

5.4 Future Diagram Types (not in v1)

  • D2 subset
  • Architecture diagrams
  • Network diagrams
  • Swimlanes
  • Gantt charts

Future conceptual additions, if added, should prioritize slide-native layouts such as funnel, chevron process, radial / hub-and-spoke, and pillars rather than Mermaid-equivalent graph forms.

6. Conceptual Diagram DSL (Draft)

6.1 Example: Matrix

  diagram: matrix
  rows:
     - Engineering
     - Product
  columns:
     - Discovery
     - Delivery

7. Theming & Styling

7.1 Defaults

  • Rounded corners
  • Modern color palettes
  • Inter or Segoe UI font
  • Consistent spacing
  • Slide‑friendly proportions

7.2 Theme Overrides

Users can override:

  • Colors
  • Border radius
  • Spacing
  • Font family
  • Node shapes

8. Integration Model (Client‑Agnostic)

This engine does not parse Markdown.

Clients are responsible for:

  • Extracting diagram text blocks
  • Determining diagram type (e.g., "mermaid", "diagram")
  • Passing raw text to the renderer
  • Embedding the resulting SVG

Example clients:

  • MarpToPptx
  • Static site generators
  • CLI tools
  • Editors (VS Code, Obsidian)
  • Web apps

9. Roadmap

Phase 1 (MVP)

  • Mermaid subset parser
  • Conceptual DSL parser
  • Unified semantic model
  • Basic layout engine
  • SVG renderer
  • Public API: string → SVG

Phase 2

  • Advanced conceptual diagram types
  • Prioritize conceptual types that are not trivially represented in Mermaid (funnel, chevron process, cycle, radial, pillars)
  • Theme packs
  • Layout tuning for slide aesthetics
  • Plugin API for additional syntaxes

Phase 3

  • Optional D2 parser
  • Optional DOT parser
  • Optional natural‑language → diagram compiler

10. Risks & Mitigations

Risk Mitigation
Mermaid syntax complexity Support a well‑defined subset
Conceptual DSL scope creep Start with core SmartArt categories
Layout engine complexity Begin with simple deterministic layouts
SVG rendering inconsistencies Build a strict test suite with golden SVGs
Future syntax integration Pluggable parser architecture

11. Success Criteria

  • Input text reliably produces clean SVG output.
  • SVGs look modern and professional.
  • Mermaid subset renders correctly.
  • Conceptual DSL covers core SmartArt‑style diagrams.
  • Architecture supports future syntaxes without refactoring.

12. Engineering Standards

12.1 Solution Format

The repository uses the .slnx solution file format (XML‑based, introduced in .NET SDK tooling).
DiagramForge.slnx is the single entry point for building and testing the entire repo.

12.2 Dependency Management — Central Package Management (CPM)

All NuGet package versions are declared once in Directory.Packages.props at the repository root.
Individual .csproj files reference packages by name only — no Version attributes in project files.

Rules:

  • Add new packages to Directory.Packages.props first, then reference them in .csproj files.
  • Only packages with permissive OSS licenses (MIT preferred; Apache‑2.0 acceptable) are allowed.
  • Shared MSBuild properties (e.g., <TargetFramework>, <Nullable>) live in Directory.Build.props.

12.3 Testing — xUnit v3 + Microsoft Testing Platform (MTP)

The test project (tests/DiagramForge.Tests) uses:

  • xUnit v3 (xunit.v3, Apache‑2.0) — the test framework.
    xUnit v3 test projects compile to a self‑contained executable (<OutputType>Exe</OutputType>), embedding the test runner directly in the output binary.
  • Microsoft Testing Platform (MTP) — enabled via
    <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>.
    This routes dotnet test through the MTP host instead of the legacy VSTest adapter.
  • coverlet (coverlet.collector, MIT) — code‑coverage data collection.

Running tests:

dotnet test                          # MTP via dotnet test (CI-friendly)
dotnet run --project tests/...       # run the test executable directly