# MarkdownConverter v5.0 - React + Tauri + PWA Architecture Design **Date:** 2026-03-15 **Status:** Approved **Target Platforms:** Desktop (Tauri), Web (PWA), Mobile (Future) --- ## Executive Summary This document outlines the architecture for MarkdownConverter v5.0, a complete rewrite using React, Tauri, and PWA technologies. The new architecture enables: - **Multi-platform support**: Single codebase for desktop, web, and future mobile - **Improved security**: Eliminates critical Electron vulnerabilities by design - **Reduced bundle size**: ~5-10MB desktop, ~137KB web (vs 150MB+ Electron) - **Better maintainability**: Component-based architecture with TypeScript - **Offline support**: Full PWA capabilities with IndexedDB storage --- ## 1. Project Structure ``` markdown-converter-v5/ ├── src/ │ ├── components/ │ │ ├── ui/ # Shadcn/ui components (button, dialog, etc.) │ │ ├── editor/ # CodeMirror wrapper, toolbar │ │ ├── preview/ # Markdown preview, theme rendering │ │ ├── sidebar/ # Explorer, Git, Snippets, Templates panels │ │ ├── tabs/ # Tab bar, tab management │ │ ├── dialogs/ # Export, batch converter, settings dialogs │ │ └── layout/ # Main layout, splitter panes │ │ │ ├── hooks/ │ │ ├── useEditor.ts # Editor state & actions │ │ ├── useTheme.ts # Theme management │ │ ├── useFileSystem.ts # File operations (uses adapter) │ │ ├── useConversion.ts # Conversion operations │ │ └── useKeyboardShortcuts.ts │ │ │ ├── stores/ │ │ ├── editorStore.ts # Content, tabs, cursor position │ │ ├── settingsStore.ts # User preferences │ │ ├── themeStore.ts # Active theme, custom themes │ │ └── sidebarStore.ts # Sidebar state, active panel │ │ │ ├── adapters/ │ │ ├── types.ts # Interface definitions │ │ ├── tauri/ │ │ │ ├── index.ts # Tauri adapter implementation │ │ │ ├── fs.ts # File system via Tauri │ │ │ ├── convert.ts # Pandoc, FFmpeg via Tauri │ │ │ └── system.ts # System info, paths │ │ ├── web/ │ │ │ ├── index.ts # Web adapter implementation │ │ │ ├── fs.ts # IndexedDB + File System Access API │ │ │ ├── convert.ts # WASM converters, cloud fallback │ │ │ └── system.ts # Browser capabilities │ │ └── index.ts # Platform detection & export │ │ │ ├── wasm/ │ │ ├── pdf.wasm # PDF generation │ │ ├── marked.wasm # Markdown parsing (if available) │ │ └── loader.ts # WASM module loader │ │ │ ├── lib/ │ │ ├── markdown.ts # Marked + plugins config │ │ ├── syntax.ts # Highlight.js config │ │ ├── mermaid.ts # Diagram rendering │ │ └── utils.ts # Helper functions │ │ │ ├── styles/ │ │ ├── globals.css # Tailwind imports, CSS variables │ │ ├── themes/ # Theme CSS files │ │ └── editor.css # CodeMirror styling │ │ │ ├── types/ │ │ ├── editor.ts # Editor-related types │ │ ├── conversion.ts # Conversion options types │ │ └── platform.ts # Platform capability types │ │ │ ├── App.tsx # Root component │ ├── main.tsx # Entry point │ └── vite-env.d.ts │ ├── src-tauri/ # Tauri backend (Rust) │ ├── src/ │ │ ├── main.rs # Tauri entry │ │ ├── commands/ # IPC command handlers │ │ │ ├── fs.rs # File system operations │ │ │ ├── convert.rs # Pandoc, FFmpeg wrappers │ │ │ └── system.rs # System utilities │ │ └── lib.rs │ ├── Cargo.toml │ └── tauri.conf.json │ ├── public/ │ ├── manifest.json # PWA manifest │ ├── sw.js # Service worker │ ├── fonts/ # JetBrains Mono, Inter │ └── icons/ # App icons │ ├── package.json ├── vite.config.ts ├── tailwind.config.ts ├── tsconfig.json └── components.json # Shadcn/ui config ``` --- ## 2. Component Architecture ```tsx // Component hierarchy // Root layout, theme provider ├── │ ├── // Draggable title bar (desktop only) │ ├── // Document tabs │ ├── │ │ ├── // Collapsible sidebar │ │ │ ├── │ │ │ ├── │ │ │ ├── │ │ │ └── │ │ ├── // Split view container │ │ │ ├── │ │ │ └── │ │ │ └── │ │ └── // REPL, terminal, output │ └── // Line count, encoding, status │ └── // Portal-based dialogs ├── ├── ├── ├── └── ``` **Key Components:** | Component | Props | Responsibility | |-----------|-------|----------------| | `CodeMirrorEditor` | `content`, `onChange`, `theme` | Wrap CodeMirror 6 with React | | `MarkdownPreview` | `content`, `theme` | Render sanitized HTML with themes | | `TabBar` | `tabs`, `activeId`, `onSelect`, `onClose` | Manage document tabs | | `Sidebar` | `activePanel`, `collapsed` | Collapsible sidebar container | | `ExportDialog` | `format`, `options` | Export configuration UI | --- ## 3. State Management (Zustand) ### Editor Store ```typescript interface Tab { id: string; title: string; content: string; filePath?: string; isDirty: boolean; cursorPosition: { line: number; column: number }; } interface EditorState { tabs: Tab[]; activeTabId: string | null; // Actions createTab: (title?: string) => string; closeTab: (id: string) => void; setActiveTab: (id: string) => void; updateContent: (id: string, content: string) => void; updateCursorPosition: (id: string, pos: { line: number; column: number }) => void; markSaved: (id: string, filePath?: string) => void; } ``` ### Settings Store ```typescript interface SettingsState { theme: string; fontSize: number; fontFamily: string; previewMode: 'split' | 'editor' | 'preview'; showLineNumbers: boolean; wordWrap: boolean; autoSave: boolean; autoSaveInterval: number; } ``` **Stores Summary:** | Store | State | Persisted | |-------|-------|-----------| | `editorStore` | Tabs, content, cursor | Tab metadata only | | `settingsStore` | User preferences | Yes | | `themeStore` | Active theme, custom themes | Yes | | `sidebarStore` | Panel state, width | Yes | --- ## 4. Platform Adapters ### Adapter Interface ```typescript export interface PlatformAdapter { name: 'tauri' | 'web'; // File System fs: { readFile: (path: string) => Promise; writeFile: (path: string, content: string) => Promise; deleteFile: (path: string) => Promise; listDirectory: (path: string) => Promise; exists: (path: string) => Promise; watchDirectory?: (path: string, callback: WatchCallback) => () => void; }; // Conversion convert: { toPdf: (content: string, options: PdfOptions) => Promise; toDocx: (content: string, options: DocxOptions) => Promise; toHtml: (content: string, options: HtmlOptions) => Promise; batchConvert: (files: string[], format: string) => Promise; }; // Capabilities capabilities: { hasPandoc: boolean; hasFfmpeg: boolean; hasLibreOffice: boolean; hasDirectFs: boolean; hasSystemNotifications: boolean; }; } ``` ### Platform Detection ```typescript // Auto-detect platform at startup const isTauri = typeof window !== 'undefined' && '__TAURI__' in window; export const adapter: PlatformAdapter = isTauri ? tauriAdapter : webAdapter; ``` ### Capability Differences | Feature | Tauri (Desktop) | Web (PWA) | |---------|-----------------|-----------| | File System | Direct access | IndexedDB + File System Access API | | PDF Export | Pandoc (native) | WASM converter | | DOCX Export | Pandoc (native) | Limited/not available | | Media Conversion | FFmpeg (native) | Cloud API or limited | | File Watching | Native events | Not available | | Offline | Always | Service Worker | --- ## 5. Build Configuration ### Vite Configuration - Target: ESNext - Minifier: esbuild - Code splitting by vendor chunks - Source maps enabled ### Tailwind Configuration - Dark mode: `class` strategy - Custom colors using CSS variables - Custom font families (JetBrains Mono, Inter) - Tailwindcss-animate plugin ### TypeScript Configuration - Target: ES2022 - Strict mode enabled - All strict checks enabled - Path aliases (`@/*`) ### Bundle Sizes (Estimated) | Chunk | Size (gzipped) | |-------|----------------| | `vendor-react` | ~12KB | | `vendor-editor` | ~45KB | | `vendor-markdown` | ~35KB | | `vendor-ui` | ~15KB | | `app` (your code) | ~30KB | | **Total PWA** | **~137KB** | | Tauri desktop | ~5-10MB (with WebView) | --- ## 6. Tauri Backend (Rust) ### IPC Commands **File System:** - `read_file` - Read file content - `write_file` - Write file content - `delete_file` - Delete file - `list_directory` - List directory contents - `path_exists` - Check path existence - `watch_directory` - Watch for file changes **Conversion:** - `to_pdf` - Convert to PDF via Pandoc - `to_docx` - Convert to DOCX via Pandoc - `to_html` - Convert to HTML via Pandoc - `batch_convert` - Batch conversion **System:** - `check_dependencies` - Check for Pandoc, FFmpeg, LibreOffice - `get_config_dir` - Get config directory path ### Security Comparison | Aspect | Electron (Current) | Tauri | |--------|-------------------|-------| | `nodeIntegration` | `true` (CVE) | Not possible | | `contextIsolation` | `false` (CVE) | Always enforced | | Bundle size | ~150MB | ~5-10MB | | Memory usage | Higher | Lower | | IPC security | Manual whitelist | Compile-time verified | --- ## 7. PWA Configuration ### Web App Manifest - Name: Markdown Converter - Display: Standalone - Theme color: #5661b3 - File handlers for .md, .markdown, .txt - Share target for receiving shared content ### Service Worker - Cache-first for static assets - Network-first for API calls - Stale-while-revalidate for dynamic content - Automatic update detection ### IndexedDB Storage **Stores:** - `files` - Offline file storage - `settings` - User preferences - `templates` - Custom templates ### PWA Features | Feature | Implementation | |---------|---------------| | Offline support | Service Worker + IndexedDB | | Install prompt | Web App Manifest | | File handling | File System Access API (Chrome) | | Share target | Share Target API | | Background sync | Background Sync API | --- ## 8. Migration Plan ### Timeline: 8 Weeks **Phase 1: Foundation (Week 1-2)** - Initialize new repo - Setup Vite + React + TypeScript - Configure Tailwind + Shadcn/ui - Setup Zustand stores - Create platform adapter interfaces - Setup Tauri project structure **Phase 2: Core Editor (Week 3-4)** - CodeMirrorEditor component - MarkdownPreview component - SplitPane layout - Theme system - Tab management - Keyboard shortcuts **Phase 3: Sidebar & Panels (Week 5)** - Sidebar container - ExplorerPanel - GitPanel - SnippetsPanel - TemplatesPanel - Bottom panel **Phase 4: Platform Adapters (Week 6)** - Web adapter implementation - Tauri adapter implementation - File system operations - PDF conversion - Capability detection **Phase 5: Export & Conversion (Week 7)** - ExportDialog - BatchConvertDialog - UniversalConverterDialog - ImageConverterDialog - AudioConverterDialog - VideoConverterDialog - PDF Editor Dialog **Phase 6: PWA & Polish (Week 8)** - Service Worker setup - Web App Manifest - IndexedDB storage - Offline mode indicator - Settings persistence - Accessibility audit - Performance optimization ### Parallel Development Strategy ``` Current Electron App (v4.x) New React+Tauri App (v5.0) │ │ │ Bug fixes only │ Active development │ Security patches │ Feature migration ▼ ▼ Stable release ────────────> Beta release (maintained) (new features) ``` --- ## 9. Design Decisions Summary | Decision | Choice | Rationale | |----------|--------|-----------| | Code Structure | Single repo with platform adapters | Lightest weight, clean separation | | State Management | Zustand | Minimal (~1KB), simple API | | UI Library | Shadcn/ui + Tailwind | Copy-paste ownership, excellent DX | | Build Tool | Vite | Industry standard, fast HMR | | TypeScript | Strict mode | Maximum type safety | | Desktop Features | Hybrid (WASM core, desktop advanced) | Best of both worlds | | Migration | Parallel development | Zero disruption to stable release | --- ## 10. Success Criteria - [ ] All core editor features functional on both Tauri and PWA - [ ] Bundle size under 150KB for PWA - [ ] All 13 themes migrated and working - [ ] Export to PDF works on both platforms - [ ] Offline mode fully functional in PWA - [ ] WCAG 2.1 AA accessibility compliance - [ ] TypeScript strict mode with no `any` types - [ ] All IPC channels have TypeScript types - [ ] Security audit passes with no critical issues --- ## Appendix: Dependencies ### Production Dependencies - `react` - UI library - `react-dom` - React DOM renderer - `zustand` - State management - `@radix-ui/react-*` - Headless UI primitives - `@codemirror/*` - Code editor - `marked` - Markdown parser - `highlight.js` - Syntax highlighting - `mermaid` - Diagram rendering - `dompurify` - HTML sanitization - `class-variance-authority` - Component variants - `clsx` + `tailwind-merge` - Class utilities - `lucide-react` - Icons ### Development Dependencies - `@tauri-apps/cli` - Tauri CLI - `typescript` - TypeScript compiler - `vite` - Build tool - `tailwindcss` - CSS framework - `eslint` - Linting - `prettier` - Formatting --- *Document generated: 2026-03-15* *Next step: Invoke writing-plans skill to create detailed implementation plan*