mdmdcraft.aiSimple markdown conversion
All docsLog inSign Up
HomeAll docs

Documentation

MVP architecture

mdcraft.ai MVP Architecture#

Goal#

Document the chosen Phase 1 architecture that prioritizes preview/export parity, visual quality, and a practical path to scoped reverse conversion.

Chosen stack#

  • Frontend and app shell: Next.js App Router
  • Styling: Tailwind CSS
  • Markdown pipeline: unified ecosystem
  • PDF engine: browser-grade HTML to PDF via Chromium or Playwright
  • Reverse conversion: PDF -> Markdown with deterministic extraction, heuristics, and optional OCR fallback
  • Platform layer: Prisma + PostgreSQL + NextAuth

High-level flow#

flowchart LR userInput[UserInput] --> workbench[WorkbenchStudio] accountState[AuthProfileUsage] --> workbench workbench --> mdPipeline[MarkdownPipeline] mdPipeline --> preview[PreviewRenderer] preview --> pdfExport[PdfExport] preview --> htmlGroundwork[HtmlExportGroundwork] workbench --> pdfReverse[PdfReversePipeline] pdfReverse --> reviewFix[ReviewAndFixUi] reviewFix --> markdownOutput[MarkdownOutput]

Architectural principles#

  1. One shared rendering path
    • Parse markdown once into a normalized representation.
    • Reuse it for preview, HTML groundwork, and PDF export.
  2. HTML-first rendering for quality
    • Treat HTML as the canonical visual layer.
    • Generate PDFs from that same layout to reduce drift.
  3. Review-first reverse conversion
    • Keep PDF -> Markdown explicitly scoped to text-first files.
    • Do not optimize for every file type in v1.
  4. Productized failure handling
    • Confidence warnings and review tools are part of the architecture, not only UX copy.
  5. Account-backed studio controls
    • Profile defaults, usage limits, and billing scaffolding live alongside the studio instead of in a separate product layer.

Suggested directory ownership#

  • src/app
    • marketing site
    • studio, docs, auth, account, and API routes
  • src/lib
    • product copy
    • content models
    • rendering configuration
  • docs
    • source-of-truth product and launch specs

MVP service boundaries#

Browser-friendly responsibilities#

  • marketing site
  • upload flow
  • markdown editing
  • preview rendering
  • theme configuration
  • reverse-conversion review UI
  • account state consumption and homepage-to-workbench handoff

Server-side responsibilities#

  • heavy PDF generation
  • PDF parsing and OCR-provider fallback
  • file validation and sanitization
  • auth/session lookup
  • usage metering and entitlement checks
  • temporary processing of uploaded assets
  • future batch jobs, billing webhooks, and API endpoints

Security and privacy guardrails#

  • minimize file retention
  • document when files are processed client-side versus server-side
  • prefer ephemeral processing for reverse conversion
  • document browser-side staging and optional third-party OCR processing clearly
  • avoid expanding into workspace storage or collaboration systems before the core workflow is proven

Current implementation milestones#

  1. Marketing site and docs surface are live.
  2. The shared markdown rendering pipeline is live.
  3. PDF generation and HTML export groundwork are live from the same render tree.
  4. PDF -> Markdown beta and review UI are live.
  5. Auth, account defaults, usage tracking, and billing scaffolding are live.

Why this architecture fits the plan#

  • It supports the premium export thesis.
  • It reduces preview/export mismatch.
  • It keeps reverse conversion honest and extensible.
  • It leaves room for batch jobs, richer billing, and APIs later without overbuilding the first release.