# saifurrahmanshochib/markdown-viewer architecture

> Architecture diagram of the GitHub repository saifurrahmanshochib/markdown-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saifurrahmanshochib/markdown-viewer
- Repository: https://github.com/saifurrahmanshochib/markdown-viewer

## Overview

1. **Overall shape**
   - This is a **self-hosted Next.js Markdown editor/viewer**. The repository is dominated by a single interactive app rather than a multi-service backend.
   - The core architecture is **client-heavy**: editing, previewing, tools, and export are handled in the browser, with Next.js mainly providing the app shell, bundling, and deployment.

2. **Application shell**
   - `app/layout.tsx`, `app/page.tsx`, and `app/globals.css` define the root Next.js App Router shell.
   - `components/providers.tsx` likely wires global client-side concerns such as theme, toast notifications, and other context providers.
   - The app is styled with **Tailwind CSS** and uses a shared UI component system under `components/ui/`.

3. **Primary user experience: the editor workspace**
   - The main functional boundary is `components/editor/`, which contains the full Markdown editing workspace.
   - Key parts include the **editor surface** (`markdown-editor.tsx`, `textarea-editor.tsx`), **preview panel** (`markdown-preview.tsx`), and surrounding controls such as `editor-toolbar.tsx`, `editor-status-bar.tsx`, and `editor-loader.tsx`.
   - This suggests a split-view / mode-switching editor where the document is edited on one side and rendered on the other.

4. **Document flow: input → transform → preview**
   - User text enters the editor component, is processed through Markdown utilities in `lib/markdown.ts`, and then rendered in the preview component.
   - Supporting transformations live in `lib/html-to-markdown.ts` and `lib/emoji.ts`, implying bidirectional content handling for pasted HTML and emoji normalization.
   - The preview path likely includes enhanced Markdown features called out in the README: GFM, syntax highlighting, KaTeX math, and Mermaid rendering.

5. **Draft persistence and local state**
   - Drafts are stored client-side through `hooks/use-local-storage.ts`, which aligns with the README’s localStorage-based draft behavior.
   - `components/editor/drafts-bar.tsx` is the UI boundary for managing saved drafts, while `hooks/use-debounce.ts` likely reduces write frequency and expensive transforms while typing.
   - This is an important architectural point: **there is no central backend document store** in the repo; persistence is local to the browser.

6. **Editor tools and auxiliary analysis**
   - `components/editor/tools-sidebar.tsx` is the container for non-editing utilities such as outline, linting, stats, and tables.
   - `find-replace.tsx`, `editor-toolbar.tsx`, and `editor-status-bar.tsx` provide editor operations and live document metadata.
   - These tools consume the same document state as the editor and preview, but are visually and functionally separate subsystems.

7. **Specialized content blocks**
   - `components/editor/mermaid-block.tsx` indicates explicit handling for Mermaid diagrams as a first-class Markdown extension.
   - That implies the rendering pipeline has content-type-aware branches rather than treating the document as plain Markdown only.
   - This is a notable diagram boundary: standard Markdown rendering versus embedded diagram blocks.

8. **Export and output paths**
   - `lib/export.ts` provides the document output layer, supporting formats mentioned in the README such as Markdown, HTML, PDF, and print.
   - Export likely depends on the current editor state and rendered HTML, making it a downstream consumer of the same document model used by the preview.
   - This makes export a separate architectural branch from live editing, even though both originate from the same document content.

9. **Shared UI and interaction infrastructure**
   - `components/ui/` contains reusable primitives like dialog, button, tabs, toast, tooltip, input, switch, and scroll area.
   - These are the building blocks used across editor controls, confirmations, settings, and transient messages.
   - `hooks/use-toast.ts` plus `components/ui/toaster.tsx` provide the global notification path for user feedback.

10. **Platform/runtime and delivery**
   - The project targets **Node.js 18.17+** and uses **Docker** as a first-class packaging/deployment path (`Dockerfile`, `docker-compose.yml`).
   - `next.config.mjs`, `middleware.ts`, `tailwind.config.ts`, `postcss.config.mjs`, and `tsconfig.json` show a standard Next.js + TypeScript frontend stack with build-time optimization and request-level middleware.
   - `Dockerfile` is described as a multi-stage image using Next.js standalone output, which means the deployable artifact is a self-contained server bundle rather than a separate web server plus app.

Main entry points: [`components/editor/markdown-editor.tsx`](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-editor.tsx) (Editor), [`components/ui`](https://github.com/saifurrahmanshochib/markdown-viewer/tree/master/components/ui) (UI Primitives), [`components/editor/markdown-preview.tsx`](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-preview.tsx) (Preview), [`lib/markdown.ts`](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/markdown.ts) (Markdown Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App Shell"]
  node_app_layout["Layout<br/>[layout.tsx]"]
  node_app_page["Home<br/>Next.js page<br/>[page.tsx]"]
  node_app_styles["Global CSS<br/>App styles<br/>[globals.css]"]
  node_providers["Providers<br/>[providers.tsx]"]
end

subgraph group_editor_workspace["Editor Workspace"]
  node_markdown_editor["Editor"]
  node_textarea_editor["Textarea<br/>Input mode"]
  node_markdown_preview["Preview<br/>Render pane"]
  node_editor_toolbar["Toolbar<br/>Editor controls<br/>[editor-toolbar.tsx]"]
  node_status_bar["Status Bar<br/>Editor metadata"]
  node_drafts_bar["Drafts<br/>Persistence UI<br/>[drafts-bar.tsx]"]
  node_tools_sidebar["Tools<br/>Utilities panel<br/>[tools-sidebar.tsx]"]
  node_find_replace["Find/Replace<br/>Editor utility<br/>[find-replace.tsx]"]
end

subgraph group_content_pipeline["Content Pipeline"]
  node_mermaid_block["Mermaid Block<br/>Diagram renderer<br/>[mermaid-block.tsx]"]
  node_markdown_lib["Markdown Core<br/>Transform library<br/>[markdown.ts]"]
  node_html_to_markdown["HTML Import<br/>Transform library"]
  node_emoji_lib["Emoji<br/>Transform helper<br/>[emoji.ts]"]
  node_export_lib["Export<br/>Output pipeline<br/>[export.ts]"]
end

subgraph group_state_ui["State & UI"]
  node_local_storage_hook(("Local Storage<br/>State hook"))
  node_debounce_hook(("Debounce<br/>State hook<br/>[use-debounce.ts]"))
  node_toast_hook(("Toast<br/>Notification hook<br/>[use-toast.ts]"))
  node_ui_primitives["UI Primitives<br/>Component kit"]
  node_toaster["Toaster<br/>Notification host<br/>[toaster.tsx]"]
  node_editor_defaults["Defaults<br/>Editor config<br/>[editor-defaults.ts]"]
end

subgraph group_runtime_delivery["Runtime & Delivery"]
  node_next_config["Next Config<br/>Build config<br/>[next.config.mjs]"]
  node_middleware["Middleware<br/>[middleware.ts]"]
  node_dockerfile["Dockerfile<br/>Container build"]
  node_compose["Compose<br/>Deployment spec<br/>[docker-compose.yml]"]
end

node_app_page -->|"mounts"| node_markdown_editor
node_app_layout -->|"wraps"| node_providers
node_app_layout -->|"loads"| node_app_styles
node_providers -->|"provides"| node_toast_hook
node_providers -->|"renders"| node_toaster
node_markdown_editor -->|"uses"| node_textarea_editor
node_markdown_editor -->|"pairs with"| node_markdown_preview
node_markdown_editor -->|"controls"| node_editor_toolbar
node_markdown_editor -->|"shows"| node_status_bar
node_markdown_editor -->|"manages"| node_drafts_bar
node_markdown_editor -->|"augments"| node_tools_sidebar
node_markdown_editor -->|"supports"| node_find_replace
node_markdown_editor -->|"initializes"| node_editor_defaults
node_textarea_editor -->|"debounces"| node_debounce_hook
node_drafts_bar -->|"persists"| node_local_storage_hook
node_markdown_preview -->|"renders via"| node_markdown_lib
node_markdown_preview -->|"embeds"| node_mermaid_block
node_markdown_lib -->|"ingests"| node_html_to_markdown
node_markdown_lib -->|"normalizes"| node_emoji_lib
node_editor_toolbar -->|"uses"| node_ui_primitives
node_tools_sidebar -->|"uses"| node_ui_primitives
node_find_replace -->|"uses"| node_ui_primitives
node_status_bar -->|"uses"| node_ui_primitives
node_export_lib -->|"exports from"| node_markdown_lib
node_export_lib -->|"derives from"| node_markdown_preview
node_ui_primitives -->|"supports"| node_toaster
node_next_config -->|"packages"| node_dockerfile
node_middleware -->|"intercepts"| node_app_page
node_compose -->|"orchestrates"| node_dockerfile

click node_app_layout "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/layout.tsx"
click node_app_page "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/page.tsx"
click node_app_styles "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/globals.css"
click node_providers "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/providers.tsx"
click node_markdown_editor "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-editor.tsx"
click node_textarea_editor "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/textarea-editor.tsx"
click node_markdown_preview "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-preview.tsx"
click node_editor_toolbar "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/editor-toolbar.tsx"
click node_status_bar "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/editor-status-bar.tsx"
click node_drafts_bar "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/drafts-bar.tsx"
click node_tools_sidebar "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/tools-sidebar.tsx"
click node_find_replace "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/find-replace.tsx"
click node_mermaid_block "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/mermaid-block.tsx"
click node_markdown_lib "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/markdown.ts"
click node_html_to_markdown "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/html-to-markdown.ts"
click node_emoji_lib "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/emoji.ts"
click node_export_lib "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/export.ts"
click node_local_storage_hook "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-local-storage.ts"
click node_debounce_hook "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-debounce.ts"
click node_toast_hook "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-toast.ts"
click node_ui_primitives "https://github.com/saifurrahmanshochib/markdown-viewer/tree/master/components/ui"
click node_toaster "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/ui/toaster.tsx"
click node_editor_defaults "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/editor-defaults.ts"
click node_next_config "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/next.config.mjs"
click node_middleware "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/middleware.ts"
click node_dockerfile "https://github.com/saifurrahmanshochib/markdown-viewer/tree/master/Dockerfile"
click node_compose "https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_app_page,node_app_styles,node_providers toneBlue
class node_markdown_editor,node_textarea_editor,node_markdown_preview,node_editor_toolbar,node_status_bar,node_drafts_bar,node_tools_sidebar,node_find_replace toneAmber
class node_mermaid_block,node_markdown_lib,node_html_to_markdown,node_emoji_lib,node_export_lib toneMint
class node_local_storage_hook,node_debounce_hook,node_toast_hook,node_ui_primitives,node_toaster,node_editor_defaults toneRose
class node_next_config,node_middleware,node_dockerfile,node_compose toneIndigo
```

## Components

### App Shell

Next.js entry points and global styling

- [Layout](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/layout.tsx): Next.js layout · Root document shell and app-wide structure · `app/layout.tsx`
- [Home](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/page.tsx): Next.js page · Main app entry that mounts the editor experience · `app/page.tsx`
- [Global CSS](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/app/globals.css): App styles · Global Tailwind and base styling · `app/globals.css`
- [Providers](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/providers.tsx): Client providers · Global client-side context wiring · `components/providers.tsx`

### Editor Workspace

Primary Markdown editing surface and tools

- [Editor](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-editor.tsx): Editor surface · Main Markdown editing container · `components/editor/markdown-editor.tsx`
- [Textarea](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/textarea-editor.tsx): Input mode · Raw text editing implementation · `components/editor/textarea-editor.tsx`
- [Preview](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/markdown-preview.tsx): Render pane · Rendered Markdown preview panel · `components/editor/markdown-preview.tsx`
- [Toolbar](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/editor-toolbar.tsx): Editor controls · Formatting and document actions · `components/editor/editor-toolbar.tsx`
- [Status Bar](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/editor-status-bar.tsx): Editor metadata · Live document state and counts · `components/editor/editor-status-bar.tsx`
- [Drafts](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/drafts-bar.tsx): Persistence UI · Saved draft selection and management · `components/editor/drafts-bar.tsx`
- [Tools](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/tools-sidebar.tsx): Utilities panel · Outline, stats, lint, and other helper tools · `components/editor/tools-sidebar.tsx`
- [Find/Replace](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/find-replace.tsx): Editor utility · Search and replacement interactions · `components/editor/find-replace.tsx`

### Content Pipeline

Markdown transformation, preview, and export

- [Mermaid Block](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/editor/mermaid-block.tsx): Diagram renderer · Specialized Mermaid diagram handling inside Markdown · `components/editor/mermaid-block.tsx`
- [Markdown Core](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/markdown.ts): Transform library · Markdown parsing and rendering helpers · `lib/markdown.ts`
- [HTML Import](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/html-to-markdown.ts): Transform library · Converts pasted or imported HTML into Markdown · `lib/html-to-markdown.ts`
- [Emoji](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/emoji.ts): Transform helper · Emoji normalization and replacement · `lib/emoji.ts`
- [Export](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/export.ts): Output pipeline · Markdown, HTML, PDF, and print export flow · `lib/export.ts`

### State & UI

Shared hooks and reusable UI primitives

- [Local Storage](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-local-storage.ts): State hook · Browser persistence for drafts and settings · `hooks/use-local-storage.ts`
- [Debounce](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-debounce.ts): State hook · Throttles typing and expensive updates · `hooks/use-debounce.ts`
- [Toast](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/hooks/use-toast.ts): Notification hook · Global notification API · `hooks/use-toast.ts`
- [UI Primitives](https://github.com/saifurrahmanshochib/markdown-viewer/tree/master/components/ui): Component kit · Reusable dialogs, tabs, inputs, buttons, and overlays · `components/ui`
- [Toaster](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/components/ui/toaster.tsx): Notification host · Renders queued toast messages · `components/ui/toaster.tsx`
- [Defaults](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/lib/editor-defaults.ts): Editor config · Shared editor default settings and initial state · `lib/editor-defaults.ts`

### Runtime & Delivery

Build, middleware, and containerized deployment

- [Next Config](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/next.config.mjs): Build config · Next.js build and runtime configuration · `next.config.mjs`
- [Middleware](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/middleware.ts): Request middleware · Request-time application middleware · `middleware.ts`
- [Dockerfile](https://github.com/saifurrahmanshochib/markdown-viewer/tree/master/Dockerfile): Container build · Multi-stage production image build · `Dockerfile`
- [Compose](https://github.com/saifurrahmanshochib/markdown-viewer/blob/master/docker-compose.yml): Deployment spec · Local container orchestration · `docker-compose.yml`

## Connections

- Home → Editor: mounts · The home page mounts the editor workspace
- Layout → Providers: wraps · App layout applies global providers
- Layout → Global CSS: loads · Root layout loads global styling
- Providers → Toast: provides · Global notification infrastructure
- Providers → Toaster: renders · Provider tree includes the toast host
- Editor → Textarea: uses · Editor surface contains the text input mode
- Editor → Preview: pairs with · Editor surface drives rendered preview
- Editor → Toolbar: controls · Toolbar actions operate on the current document
- Editor → Status Bar: shows · Status bar reflects editor state
- Editor → Drafts: manages · Draft sidebar connects to editor state
- Editor → Tools: augments · Tools panel shares the active document
- Editor → Find/Replace: supports · Search and replace acts on editor content
- Editor → Defaults: initializes · Default editor configuration seeds the workspace
- Textarea → Debounce: debounces · Typing updates and derived work are throttled
- Drafts → Local Storage: persists · Draft storage is browser-local
- Preview → Markdown Core: renders via · Preview uses the Markdown rendering pipeline
- Preview → Mermaid Block: embeds · Preview handles Mermaid as a special block
- Markdown Core → HTML Import: ingests · Markdown pipeline accepts HTML conversion input
- Markdown Core → Emoji: normalizes · Markdown content passes through emoji handling
- Toolbar → UI Primitives: uses · Toolbar relies on shared UI components
- Tools → UI Primitives: uses · Sidebar utilities use the shared component kit
- Find/Replace → UI Primitives: uses · Search UI is built from shared primitives
- Status Bar → UI Primitives: uses · Status UI uses shared primitives
- Export → Markdown Core: exports from · Export flow consumes the document model and rendered content
- Export → Preview: derives from · Some export paths depend on rendered preview output
- UI Primitives → Toaster: supports · Shared UI underpins transient messaging and dialogs
- Next Config → Dockerfile: packages · Build configuration feeds the standalone deployment artifact
- Middleware → Home: intercepts · Request middleware sits in front of the app shell
- Compose → Dockerfile: orchestrates · Compose uses the container image for local deployment