# runyao-zhang/crystal-vault architecture

> Architecture diagram of the GitHub repository runyao-zhang/crystal-vault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/runyao-zhang/crystal-vault
- Repository: https://github.com/runyao-zhang/crystal-vault

## Overview

Crystal Vault turns Markdown notes and folders into an interactive knowledge workspace, with a principal workflow of opening the vault, navigating crystals and their links, then reading source documents beside the structure and creating or editing cards in place. The graph includes the documented desktop, story-line, review, import, and file-backed layout capabilities. Some feature modules are unsampled; their nodes and links are included only where the README or source index supports them.

Main entry points: [`src/core/app.js`](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/app.js) (App Controller), [`src/adapter.js`](https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapter.js) (Adapter Contract), [`src/core/reader.js`](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/reader.js) (Document Reader), [`src/bridge/server.js`](https://github.com/runyao-zhang/crystal-vault/blob/main/src/bridge/server.js) (Bridge Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["App Controller<br/>[app.js]"]
  node_crystal_view["Crystal Browser<br/>[crystals.js]"]
  node_desk["Window Desk<br/>[desk.js]"]
  node_float_windows["Floating Windows<br/>[floatwin.js]"]
end

subgraph group_knowledge["Crystal Knowledge"]
  node_model["Knowledge Model<br/>[model.js]"]
  node_frontmatter["Card Metadata<br/>[frontmatter.js]"]
  node_storyline["Story Line<br/>[storyline.js]"]
  node_story_boxes["Folder Boxes<br/>[storyboxes.js]"]
  node_box_storage[("Box Sidecars<br/>[boxfile.js]")]
  node_link_sides["Link Directions<br/>[linksides.js]"]
end

subgraph group_reading["Reading Workspace"]
  node_reader["Document Reader<br/>[reader.js]"]
  node_embedded_story["Structure Window<br/>[embedstory.js]"]
  node_pdf_document["PDF Support<br/>[pdfdoc.js]"]
end

subgraph group_host["Host Adapters"]
  node_plugin_entry["Plugin Entry<br/>[entry-plugin.js]"]
  node_obsidian_entry["Obsidian Entry<br/>[entry-obsidian.js]"]
  node_adapter_contract["Adapter Contract<br/>[adapter.js]"]
  node_fake_adapter["Web Adapter<br/>[fake.js]"]
end

subgraph group_bridge["Companion Bridge"]
  node_companion["Floating Companion<br/>[companion.js]"]
  node_bridge_server["Bridge Server<br/>[server.js]"]
  node_bridge_protocol["Bridge Protocol<br/>[protocol.js]"]
  node_remote_adapter["Remote Adapter<br/>[remote.js]"]
end

node_user(("User"))

node_user -->|"opens vault"| node_plugin_entry
node_plugin_entry -->|"loads host"| node_obsidian_entry
node_obsidian_entry -->|"mounts"| node_app
node_obsidian_entry -->|"implements"| node_adapter_contract
node_app -->|"uses"| node_adapter_contract
node_app -->|"renders"| node_crystal_view
node_app -->|"refreshes relations"| node_model
node_crystal_view -->|"builds view from"| node_model
node_model -->|"parses card fields"| node_frontmatter
node_model -->|"resolves links through"| node_adapter_contract
node_user -->|"explores links"| node_storyline
node_storyline -->|"shows folder boxes"| node_story_boxes
node_story_boxes -->|"loads and saves"| node_box_storage
node_storyline -->|"uses link directions"| node_link_sides
node_user -->|"reads documents"| node_reader
node_reader -->|"loads PDF support"| node_pdf_document
node_reader -->|"opens structure window"| node_embedded_story
node_reader -->|"uses document desk"| node_desk
node_desk -->|"manages windows"| node_float_windows
node_reader -->|"reads and writes through"| node_adapter_contract
node_user -->|"creates and edits cards"| node_app
node_app -->|"updates card fields"| node_frontmatter
node_user -.->|"opens floating companion"| node_companion
node_companion -->|"connects to"| node_bridge_server
node_bridge_server -->|"checks contract"| node_bridge_protocol
node_bridge_server -->|"forwards host adapter"| node_adapter_contract
node_remote_adapter -->|"uses protocol"| node_bridge_protocol
node_remote_adapter -.->|"requests host services"| node_bridge_server
node_plugin_entry -->|"starts companion bridge"| node_bridge_server
node_user -.->|"uses web version"| node_fake_adapter
node_fake_adapter -->|"implements"| node_adapter_contract

click node_plugin_entry "https://github.com/runyao-zhang/crystal-vault/blob/main/src/entry-plugin.js"
click node_obsidian_entry "https://github.com/runyao-zhang/crystal-vault/blob/main/src/entry-obsidian.js"
click node_adapter_contract "https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapter.js"
click node_fake_adapter "https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapters/fake.js"
click node_app "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/app.js"
click node_crystal_view "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/crystals.js"
click node_desk "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/desk.js"
click node_float_windows "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/floatwin.js"
click node_model "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/model.js"
click node_frontmatter "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/frontmatter.js"
click node_storyline "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/storyline.js"
click node_story_boxes "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/storyboxes.js"
click node_box_storage "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/boxfile.js"
click node_link_sides "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/linksides.js"
click node_reader "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/reader.js"
click node_embedded_story "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/embedstory.js"
click node_pdf_document "https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/pdfdoc.js"
click node_companion "https://github.com/runyao-zhang/crystal-vault/blob/main/src/companion.js"
click node_bridge_server "https://github.com/runyao-zhang/crystal-vault/blob/main/src/bridge/server.js"
click node_bridge_protocol "https://github.com/runyao-zhang/crystal-vault/blob/main/src/bridge/protocol.js"
click node_remote_adapter "https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapters/remote.js"

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,node_crystal_view,node_desk,node_float_windows,node_user toneBlue
class node_model,node_frontmatter,node_storyline,node_story_boxes,node_box_storage,node_link_sides toneAmber
class node_reader,node_embedded_story,node_pdf_document toneMint
class node_plugin_entry,node_obsidian_entry,node_adapter_contract,node_fake_adapter toneRose
class node_companion,node_bridge_server,node_bridge_protocol,node_remote_adapter toneIndigo
```

## Components

### Workspace UI

- [App Controller](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/app.js): `src/core/app.js`
- [Crystal Browser](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/crystals.js): `src/core/crystals.js`
- [Window Desk](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/desk.js): `src/core/desk.js`
- [Floating Windows](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/floatwin.js): `src/core/floatwin.js`

### Crystal Knowledge

- [Knowledge Model](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/model.js): `src/core/model.js`
- [Card Metadata](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/frontmatter.js): `src/core/frontmatter.js`
- [Story Line](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/storyline.js): `src/core/storyline.js`
- [Folder Boxes](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/storyboxes.js): `src/core/storyboxes.js`
- [Box Sidecars](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/boxfile.js): `src/core/boxfile.js`
- [Link Directions](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/linksides.js): `src/core/linksides.js`

### Reading Workspace

- [Document Reader](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/reader.js): `src/core/reader.js`
- [Structure Window](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/embedstory.js): `src/core/embedstory.js`
- [PDF Support](https://github.com/runyao-zhang/crystal-vault/blob/main/src/core/pdfdoc.js): `src/core/pdfdoc.js`

### Host Adapters

- [Plugin Entry](https://github.com/runyao-zhang/crystal-vault/blob/main/src/entry-plugin.js): `src/entry-plugin.js`
- [Obsidian Entry](https://github.com/runyao-zhang/crystal-vault/blob/main/src/entry-obsidian.js): `src/entry-obsidian.js`
- [Adapter Contract](https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapter.js): `src/adapter.js`
- [Web Adapter](https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapters/fake.js): `src/adapters/fake.js`

### Companion Bridge

- [Floating Companion](https://github.com/runyao-zhang/crystal-vault/blob/main/src/companion.js): `src/companion.js`
- [Bridge Server](https://github.com/runyao-zhang/crystal-vault/blob/main/src/bridge/server.js): `src/bridge/server.js`
- [Bridge Protocol](https://github.com/runyao-zhang/crystal-vault/blob/main/src/bridge/protocol.js): `src/bridge/protocol.js`
- [Remote Adapter](https://github.com/runyao-zhang/crystal-vault/blob/main/src/adapters/remote.js): `src/adapters/remote.js`

### Other components

- **User**

## Connections

- User → Plugin Entry: opens vault (evidence: `README.md`)
- Plugin Entry → Obsidian Entry: loads host (evidence: `src/entry-plugin.js`)
- Obsidian Entry → App Controller: mounts (evidence: `src/entry-obsidian.js`)
- Obsidian Entry → Adapter Contract: implements (evidence: `src/entry-obsidian.js`)
- App Controller → Adapter Contract: uses (evidence: `src/core/app.js`)
- App Controller → Crystal Browser: renders (evidence: `src/core/app.js`)
- App Controller → Knowledge Model: refreshes relations (evidence: `src/core/app.js`)
- Crystal Browser → Knowledge Model: builds view from (evidence: `src/core/crystals.js`)
- Knowledge Model → Card Metadata: parses card fields (evidence: `src/core/model.js`)
- Knowledge Model → Adapter Contract: resolves links through (evidence: `src/core/model.js`)
- User → Story Line: explores links (evidence: `README.md`)
- Story Line → Folder Boxes: shows folder boxes (evidence: `README.md`)
- Folder Boxes → Box Sidecars: loads and saves (evidence: `src/core/storyboxes.js`)
- Story Line → Link Directions: uses link directions (evidence: `README.md`)
- User → Document Reader: reads documents (evidence: `README.md`)
- Document Reader → PDF Support: loads PDF support (evidence: `src/core/reader.js`)
- Document Reader → Structure Window: opens structure window (evidence: `src/core/reader.js`)
- Document Reader → Window Desk: uses document desk (evidence: `src/core/reader.js`)
- Window Desk → Floating Windows: manages windows (evidence: `README.md`)
- Document Reader → Adapter Contract: reads and writes through (evidence: `src/core/reader.js`)
- User → App Controller: creates and edits cards (evidence: `README.md`)
- App Controller → Card Metadata: updates card fields (evidence: `src/core/app.js`)
- User → Floating Companion: opens floating companion (evidence: `README.md`)
- Floating Companion → Bridge Server: connects to (evidence: `src/companion.js`)
- Bridge Server → Bridge Protocol: checks contract (evidence: `src/bridge/server.js`)
- Bridge Server → Adapter Contract: forwards host adapter (evidence: `src/bridge/server.js`)
- Remote Adapter → Bridge Protocol: uses protocol (evidence: `src/adapters/remote.js`)
- Remote Adapter → Bridge Server: requests host services
- Plugin Entry → Bridge Server: starts companion bridge (evidence: `src/entry-plugin.js`)
- User → Web Adapter: uses web version
- Web Adapter → Adapter Contract: implements (evidence: `src/adapters/fake.js`)