# aqav/obsidian-canvas-links architecture

> Architecture diagram of the GitHub repository aqav/obsidian-canvas-links, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aqav/obsidian-canvas-links
- Repository: https://github.com/aqav/obsidian-canvas-links

## Overview

##### Project Type and Purpose
- This is an Obsidian plugin named “Canvas Links.”
- It runs entirely inside the Obsidian host application, extends the Canvas feature, and visualizes connections between Canvas nodes and vault files.

##### High-Level Architecture Components
a. Obsidian Host Environment
- Provides core APIs for plugins: command registration, Canvas access, vault/file access, UI panes.
b. Canvas Links Plugin
- Entry point (main.js compiled from main.ts)
- Manifest (plugin metadata)
- Styles (styles.css for link styling)
c. Internal Modules
- Command Handler: registers “Canvas Links: Open” and listens for invocation
- File Metadata Service: reads vault files & metadata via Obsidian’s Vault API
- Link Resolver & Renderer: computes relationships (file ↔ canvas node) and draws SVG/HTML overlays on Canvas
d. Build & Release Pipeline
- esbuild.config.mjs: bundles TypeScript into main.js
- version-bump.mjs & versions.json: manages plugin versioning
- GitHub Releases / Community Plugins: distribution

##### Relationships and Data Flows
- Obsidian → Plugin Loader: at startup, loads main.js, manifest.json, styles.css
- User invokes command → Command Handler
- Command Handler → Canvas Data Service & File Metadata Service (parallel calls)
- Services return data → Link Resolver processes relationships
- Renderer draws link overlays on Canvas using DOM/SVG (styled by styles.css)
- Build Pipeline (out-of-band): esbuild transforms source (main.ts, modules) → distributable main.js

##### Architectural Patterns & Principles
- Modular single-responsibility modules (command, data, rendering)
- Observer/Listener pattern for Obsidian commands & Canvas events
- Separation of concerns: data retrieval vs. UI rendering vs. build tasks
- Plugin manifest-driven metadata for safe loading by host

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host environment
    subgraph "Obsidian Host Environment"
        class HostContainer host
        CanvasAPI["Canvas API"]:::host
        CanvasUI["Canvas UI Pane"]:::host
        subgraph "Canvas Links Plugin"
            class PluginContainer plugin
            CommandHandler["Command Handler"]:::plugin
            CanvasDataService["Canvas Data Service"]:::plugin
            FileMetadataService["File Metadata Service"]:::plugin
            LinkResolverRenderer["Link Resolver & Renderer"]:::plugin
            manifest["manifest.json"]:::doc
            styles["styles.css"]:::doc
        end
    end

    %% External data source
    vault["Vault (Markdown Files)"]:::data

    %% Build & config pipeline
    subgraph "Build & Release Pipeline"
        class PipelineContainer build
        esbuild["esbuild.config.mjs"]:::config
        versionbump["version-bump.mjs"]:::config
        versions["versions.json"]:::config
        package["package.json"]:::config
        tsconfig["tsconfig.json"]:::config
    end

    %% Data flows
    vault -->|read file metadata| FileMetadataService
    CanvasAPI -->|query nodes| CanvasDataService
    CommandHandler -->|invoke| CanvasDataService
    CommandHandler -->|invoke| FileMetadataService
    CanvasDataService -->|supply data| LinkResolverRenderer
    FileMetadataService -->|supply data| LinkResolverRenderer
    LinkResolverRenderer -->|render overlays| CanvasUI
    esbuild -->|bundles main.ts into main.js| PluginContainer
    versionbump -->|update versions| versions
    versions -->|write metadata| manifest

    %% Click events
    click CommandHandler "https://github.com/aqav/obsidian-canvas-links/blob/master/main.ts"
    click CanvasDataService "https://github.com/aqav/obsidian-canvas-links/blob/master/main.ts"
    click FileMetadataService "https://github.com/aqav/obsidian-canvas-links/blob/master/main.ts"
    click LinkResolverRenderer "https://github.com/aqav/obsidian-canvas-links/blob/master/main.ts"
    click manifest "https://github.com/aqav/obsidian-canvas-links/blob/master/manifest.json"
    click styles "https://github.com/aqav/obsidian-canvas-links/blob/master/styles.css"
    click esbuild "https://github.com/aqav/obsidian-canvas-links/blob/master/esbuild.config.mjs"
    click versionbump "https://github.com/aqav/obsidian-canvas-links/blob/master/version-bump.mjs"
    click versions "https://github.com/aqav/obsidian-canvas-links/blob/master/versions.json"
    click package "https://github.com/aqav/obsidian-canvas-links/blob/master/package.json"
    click tsconfig "https://github.com/aqav/obsidian-canvas-links/blob/master/tsconfig.json"

    %% Styles
    classDef host fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef plugin fill:#ADD8E6,stroke:#1e6f9f,stroke-width:1px
    classDef build fill:#90EE90,stroke:#2e7d32,stroke-width:1px
    classDef data fill:#FFA500,stroke:#bf360c,stroke-width:1px
    classDef config fill:#98FB98,stroke:#388e3c,stroke-width:1px
    classDef doc fill:#FFFACD,stroke:#8d6e63,stroke-width:1px
```
