# shd101wyy/crossnote architecture

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

- Interactive diagram: https://gitdiagram.com/shd101wyy/crossnote
- Repository: https://github.com/shd101wyy/crossnote

## Overview

Crossnote is a Markdown notebook engine and local preview/export application. The main workflow is to initialize a notebook over note directories, parse and render a note through its Markdown engine, then preview or export it; the CLI also offers a live multi-root server and a read-only wiki snapshot. The graph includes documented rendering, notebook-navigation, and server-app capabilities. Some subsystem links are based on README descriptions and directory structure because their implementation was not sampled.

Main entry points: [`src/markdown-engine/index.ts`](https://github.com/shd101wyy/crossnote/blob/develop/src/markdown-engine/index.ts) (Markdown engine), [`src/notebook/index.ts`](https://github.com/shd101wyy/crossnote/blob/develop/src/notebook/index.ts) (Notebook index), [`src/wiki/index.ts`](https://github.com/shd101wyy/crossnote/blob/develop/src/wiki/index.ts) (Wiki builder), [`src/serve/index.ts`](https://github.com/shd101wyy/crossnote/blob/develop/src/serve/index.ts) (Preview server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI commands<br/>[index.ts]"]
  node_library["Library API<br/>[index.ts]"]
end

subgraph group_notebook["Notebook and rendering"]
  node_notes[("Notebook index<br/>[index.ts]")]
  node_markdown["Markdown engine<br/>[index.ts]"]
  node_transform["Markdown transform<br/>[transformer.ts]"]
  node_features["Markdown extensions"]
  node_enhance["Render enhancers"]
  node_renderers["Diagram renderers"]
  node_code["Code chunks<br/>[code-chunk.ts]"]
  node_search["Search and links<br/>[search.ts]"]
end

subgraph group_outputs["Preview and export"]
  node_webview["Preview interface<br/>[preview.tsx]"]
  node_previewstate["Preview interactions<br/>[preview.ts]"]
  node_converters["Export converters"]
end

subgraph group_apps["Serve and wiki"]
  node_serve["Preview server<br/>[index.ts]"]
  node_serverui["Serve app<br/>[App.tsx]"]
  node_wiki["Wiki builder<br/>[index.ts]"]
end

node_user(("Note author"))
node_browser(("Browser"))
node_disk[("Note files")]

node_user -->|"runs command"| node_cli
node_user -->|"uses API"| node_library
node_cli -->|"starts server"| node_serve
node_cli -->|"builds snapshot"| node_wiki
node_library -->|"initializes"| node_notes
node_notes -->|"reads notes"| node_disk
node_notes -->|"creates engine"| node_markdown
node_notes -->|"indexes notes"| node_search
node_markdown -->|"transforms text"| node_transform
node_transform -->|"uses extensions"| node_features
node_markdown -->|"enhances output"| node_enhance
node_markdown -->|"renders diagrams"| node_renderers
node_markdown -->|"processes chunks"| node_code
node_markdown -->|"provides preview"| node_webview
node_markdown -->|"exports content"| node_converters
node_webview -->|"handles interactions"| node_previewstate
node_serve -->|"creates notebooks"| node_notes
node_serve -->|"serves app"| node_serverui
node_serve -->|"serves files"| node_disk
node_serverui -->|"renders interface"| node_browser
node_wiki -->|"creates notebooks"| node_notes
node_wiki -->|"renders notes"| node_markdown
node_wiki -->|"reads note files"| node_disk
node_wiki -->|"produces HTML"| node_browser

click node_cli "https://github.com/shd101wyy/crossnote/blob/develop/src/cli/index.ts"
click node_library "https://github.com/shd101wyy/crossnote/blob/develop/src/index.ts"
click node_notes "https://github.com/shd101wyy/crossnote/blob/develop/src/notebook/index.ts"
click node_markdown "https://github.com/shd101wyy/crossnote/blob/develop/src/markdown-engine/index.ts"
click node_transform "https://github.com/shd101wyy/crossnote/blob/develop/src/markdown-engine/transformer.ts"
click node_features "https://github.com/shd101wyy/crossnote/tree/develop/src/custom-markdown-it-features"
click node_enhance "https://github.com/shd101wyy/crossnote/tree/develop/src/render-enhancers"
click node_renderers "https://github.com/shd101wyy/crossnote/tree/develop/src/renderers"
click node_code "https://github.com/shd101wyy/crossnote/blob/develop/src/code-chunk/code-chunk.ts"
click node_search "https://github.com/shd101wyy/crossnote/blob/develop/src/notebook/search.ts"
click node_webview "https://github.com/shd101wyy/crossnote/blob/develop/src/webview/preview.tsx"
click node_previewstate "https://github.com/shd101wyy/crossnote/blob/develop/src/webview/containers/preview.ts"
click node_converters "https://github.com/shd101wyy/crossnote/tree/develop/src/converters"
click node_serve "https://github.com/shd101wyy/crossnote/blob/develop/src/serve/index.ts"
click node_serverui "https://github.com/shd101wyy/crossnote/blob/develop/src/server-app/App.tsx"
click node_wiki "https://github.com/shd101wyy/crossnote/blob/develop/src/wiki/index.ts"

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_cli,node_library,node_browser toneBlue
class node_notes,node_markdown,node_transform,node_features,node_enhance,node_renderers,node_code,node_search,node_disk toneAmber
class node_webview,node_previewstate,node_converters toneMint
class node_serve,node_serverui,node_wiki toneRose
class node_user toneIndigo
```

## Components

### Entry points

- [CLI commands](https://github.com/shd101wyy/crossnote/blob/develop/src/cli/index.ts): `src/cli/index.ts`
- [Library API](https://github.com/shd101wyy/crossnote/blob/develop/src/index.ts): `src/index.ts`

### Notebook and rendering

- [Notebook index](https://github.com/shd101wyy/crossnote/blob/develop/src/notebook/index.ts): `src/notebook/index.ts`
- [Markdown engine](https://github.com/shd101wyy/crossnote/blob/develop/src/markdown-engine/index.ts): `src/markdown-engine/index.ts`
- [Markdown transform](https://github.com/shd101wyy/crossnote/blob/develop/src/markdown-engine/transformer.ts): `src/markdown-engine/transformer.ts`
- [Markdown extensions](https://github.com/shd101wyy/crossnote/tree/develop/src/custom-markdown-it-features): `src/custom-markdown-it-features`
- [Render enhancers](https://github.com/shd101wyy/crossnote/tree/develop/src/render-enhancers): `src/render-enhancers`
- [Diagram renderers](https://github.com/shd101wyy/crossnote/tree/develop/src/renderers): `src/renderers`
- [Code chunks](https://github.com/shd101wyy/crossnote/blob/develop/src/code-chunk/code-chunk.ts): `src/code-chunk/code-chunk.ts`
- [Search and links](https://github.com/shd101wyy/crossnote/blob/develop/src/notebook/search.ts): `src/notebook/search.ts`

### Preview and export

- [Preview interface](https://github.com/shd101wyy/crossnote/blob/develop/src/webview/preview.tsx): `src/webview/preview.tsx`
- [Preview interactions](https://github.com/shd101wyy/crossnote/blob/develop/src/webview/containers/preview.ts): `src/webview/containers/preview.ts`
- [Export converters](https://github.com/shd101wyy/crossnote/tree/develop/src/converters): `src/converters`

### Serve and wiki

- [Preview server](https://github.com/shd101wyy/crossnote/blob/develop/src/serve/index.ts): `src/serve/index.ts`
- [Serve app](https://github.com/shd101wyy/crossnote/blob/develop/src/server-app/App.tsx): `src/server-app/App.tsx`
- [Wiki builder](https://github.com/shd101wyy/crossnote/blob/develop/src/wiki/index.ts): `src/wiki/index.ts`

### Other components

- **Note author**
- **Browser**
- **Note files**

## Connections

- Note author → CLI commands: runs command
- Note author → Library API: uses API
- CLI commands → Preview server: starts server
- CLI commands → Wiki builder: builds snapshot
- Library API → Notebook index: initializes
- Notebook index → Note files: reads notes
- Notebook index → Markdown engine: creates engine
- Notebook index → Search and links: indexes notes
- Markdown engine → Markdown transform: transforms text
- Markdown transform → Markdown extensions: uses extensions
- Markdown engine → Render enhancers: enhances output
- Markdown engine → Diagram renderers: renders diagrams
- Markdown engine → Code chunks: processes chunks
- Markdown engine → Preview interface: provides preview
- Markdown engine → Export converters: exports content
- Preview interface → Preview interactions: handles interactions
- Preview server → Notebook index: creates notebooks
- Preview server → Serve app: serves app
- Preview server → Note files: serves files
- Serve app → Browser: renders interface
- Wiki builder → Notebook index: creates notebooks
- Wiki builder → Markdown engine: renders notes
- Wiki builder → Note files: reads note files
- Wiki builder → Browser: produces HTML