How to Build a Self-Hosted Mermaid.ai & Eraser.io Replacement with Your AI Coding Agent

1. Why Naive Prompts Fail at Building a Mermaid.ai / Eraser Replacement

-- Diagrams Storage
CREATE TABLE diagrams (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL DEFAULT 'Untitled Diagram',
    syntax_type VARCHAR(50) NOT NULL DEFAULT 'mermaid', -- 'mermaid' | 'plantuml' | 'markdown-table'
    content TEXT NOT NULL,
    viewport_state JSONB NOT NULL DEFAULT '{"zoom": 1.0, "x": 0, "y": 0}'::jsonb,
    is_public BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT timezone('utc', now()),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT timezone('utc', now())
);
CREATE INDEX idx_diagrams_updated ON diagrams(updated_at DESC);

3. Modular File System Architecture (Hard 200-Line Cap)

src/
├── app/
│   ├── page.tsx                           # < 95 lines (Hero & diagram launcher)
│   ├── editor/[id]/page.tsx               # < 130 lines (Split-pane layout container)
│   └── api/diagrams/route.ts              # < 120 lines (Save/load endpoints)
├── components/
│   ├── editor/
│   │   ├── code-editor-pane.tsx           # < 150 lines (CodeMirror/Monaco wrapper)
│   │   ├── syntax-error-banner.tsx        # < 70 lines (Friendly error recovery line marker)
│   │   └── template-selector.tsx          # < 110 lines (Flowchart, Sequence, ERD starters)
│   ├── canvas/
│   │   ├── diagram-canvas.tsx             # < 170 lines (SVG viewport & transform root)
│   │   ├── pan-zoom-controls.tsx          # < 95 lines (Zoom in, Zoom out, Fit-to-screen)
│   │   └── export-modal.tsx               # < 160 lines (SVG, High-DPI PNG, Clipboard copy)
│   └── ui/
│       ├── button.tsx, dialog.tsx         # Atomic UI primitives
├── hooks/
│   ├── use-mermaid-renderer.ts            # < 150 lines (Web worker debounced render)
│   └── use-canvas-transform.ts            # < 140 lines (Matrix math, pinch/zoom, pan)
├── workers/
│   └── mermaid-worker.ts                  # < 110 lines (Isolated graph parse & SVG stringify)
└── lib/
    ├── canvas-math.ts                     # < 90 lines (Matrix transform & boundary clamp)
    └── export-image.ts                    # < 130 lines (SVG to Canvas PNG converter)

4. Phase-by-Phase Prompts for Claude Code, Cursor & Windsurf

I have loaded the Mermaid.ai & Eraser.io Replacement technical blueprint. Do not write any code yet. Verify the Web Worker architecture and matrix transform equations, ask up to 3 clarifying questions, and then proceed with Phase 1.

Execute Phase 1: Set up the split-pane workspace layout using Tailwind and CodeMirror. Left pane: Code editor with syntax highlighting for Mermaid.js and template selector (Flowchart, Sequence, Architecture, ERD). Right pane: Canvas container with dark/light background grid dots. Keep all files under 200 lines.

Execute Phase 2: Build the diagram rendering pipeline. Create `workers/mermaid-worker.ts` running `@mermaid-js/mermaid` inside an isolated worker. Debounce editor changes by 250ms. If parsing fails, catch the error and display `syntax-error-banner.tsx` with line and column numbers while preserving the previous valid diagram on screen.

Execute Phase 3: Implement canvas navigation in `useCanvasTransform`. Add spacebar-click-and-drag panning, trackpad pinch-to-zoom, and mousewheel zoom. Add floating controls: Zoom In (+), Zoom Out (-), Reset (100%), and Fit to Screen (computes bounding box and centers the diagram).

Execute Phase 4: Implement the export modal. Support 3 export modes: 1. Pure SVG download with embedded fonts and styling. 2. High-DPI PNG download (2x scale) with optional transparent or solid background. 3. One-click "Copy Image to Clipboard" using the Async Clipboard API.

Execute Phase 5: Implement URL hash / database diagram saving and Vitest regression suites. Add unit tests verifying: valid flowchart AST parses cleanly, broken syntax string throws friendly recoverable error without killing the worker, and fit-to-screen matrix calculation correctly scales oversized diagrams into viewport bounds.