# alangrainger/share-note architecture

> Architecture diagram of the GitHub repository alangrainger/share-note, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alangrainger/share-note
- Repository: https://github.com/alangrainger/share-note

## Overview

##### Project Type & Purpose
- This is an Obsidian “plugin” (client-side extension) that:
- Reads a Markdown note (with theme, attachments, frontmatter) from the user’s vault
- Optionally encrypts the note
- Compresses & packages the content + theme assets
- Uploads via REST API to share.note.sx (or self-hosted server)
- Returns a shareable URL back to the user

##### File Structure
- Top level:
- src/ → TypeScript modules
– UI.ts (command-palette integration, settings modal)
– main.ts (plugin lifecycle hooks)
– api.ts (REST calls to server)
– crypto.ts (encrypt/decrypt routines)
– Compressor.ts (gzip or similar)
– NoteTemplate.ts (HTML/CSS templating)
– StatusMessage.ts (in-UI feedback)
– settings.ts (user preferences, encryption toggle)
- manifest.json (Obsidian plugin manifest)
- esbuild.config.mjs (bundling)
- styles.css (plugin UI styling)
- No backend code here; external service is separate (self-hosted Docker or note.sx cloud).

##### Readme Insights
- Encryption is optional per-note or global
- First share uploads theme assets once; subsequent shares reuse them
- External dependencies: Obsidian API, fetch/XHR, Web Crypto API

##### Main Components
A. Obsidian Host (Electron/Browser)
- Vault (file system)
- Obsidian Core API
B. Share Note Plugin
1. UI Module
- Triggers “Share Note” command
- Settings & status feedback
2. Core Modules
- NoteTemplate (render HTML)
- Compressor (minify/compress payload)
- crypto (AES-GCM or similar encryption)
3. API Client (api.ts)
- HTTP POST /upload
- REST endpoints for theme, note, attachments
C. External Service
- .sx Cloud (or self-hosted)
- Ingress API layer
- Storage (S3 or database)
- CDN for assets
- (Optional) Database for metadata
D. User’s Browser/Recipient
- Renders shared note via encrypted link + key

##### Relationships & Data Flows
- Vault → Plugin (reads .md, assets, CSS)
- Plugin pipeline:
UI → Core modules (template → encrypt? → compress) → API Client
- API Client → note.sx REST API → returns `id` & (if encrypted) no-content partial response
- Plugin → UI (copy share URL + key fragment)
- Recipient’s Browser → CDN/API (fetch encrypted payload + decrypt with key from URL)

##### Architectural Patterns & Design Principles
- Modular client architecture (separate UI, business logic, transport)
- Single Responsibility: each TS file has one concern
- Lazy theme upload (cache first, incremental updates)
- Pluggable encryption strategy (on/off via settings)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Obsidian Host
    subgraph "Obsidian Host"
        Vault["Vault (.md, assets)"]:::client
        ObsidianAPI["Obsidian Core API"]:::client
    end

    %% Share Note Plugin
    subgraph "Share Note Plugin"
        UI["UI Module"]:::client
        Main["Plugin Lifecycle"]:::client
        Settings["Settings & Preferences"]:::client
        Status["Status Feedback"]:::client
        NoteReader["Note Reader/Model"]:::client
        Template["Templating Engine"]:::client
        Decision{"Encrypt?"}:::decision
        Crypto["Crypto Module"]:::client
        Compressor["Compressor"]:::client
        APIClient["API Client"]:::client
        Types["Type Definitions"]:::client
        FileTypes["File Type Constants"]:::client
        Manifest["Plugin Manifest"]:::client
        Styles["Styling (UI CSS)"]:::client
    end

    %% External Service
    subgraph "External Service (note.sx or self-hosted)"
        Ingress["Ingress API Layer"]:::external
        Storage["Object Storage (S3)"]:::datastore
        DB["Metadata DB"]:::datastore
        CDN["CDN"]:::external
    end

    Recipient["Recipient Browser/Client"]:::external

    %% Data Flows
    Vault -->|"Read Note + Assets"| NoteReader
    NoteReader -->|"Apply Frontmatter Flags"| Main
    UI -->|"Share Note Command"| Main
    Main --> Settings
    Main --> Status
    NoteReader --> Template
    Template --> Decision
    Decision -->|"Yes"| Crypto
    Decision -->|"No"| Compressor
    Crypto --> Compressor
    Compressor --> APIClient
    APIClient -->|"POST /upload"| Ingress
    Ingress --> Storage
    Ingress --> DB
    Storage --> CDN
    Ingress -->|"returns id & key"| APIClient
    APIClient -->|"Share URL + Key"| Main
    Main -->|"Display URL"| Status
    Recipient -->|"Fetch Note + Assets"| CDN
    Recipient -->|"Decrypt & Render"| Crypto

    ObsidianAPI --> Manifest
    ObsidianAPI --> Styles
    ObsidianAPI --> UI

    %% Click Events
    click UI "https://github.com/alangrainger/share-note/blob/main/src/UI.ts"
    click Main "https://github.com/alangrainger/share-note/blob/main/src/main.ts"
    click Settings "https://github.com/alangrainger/share-note/blob/main/src/settings.ts"
    click Status "https://github.com/alangrainger/share-note/blob/main/src/StatusMessage.ts"
    click NoteReader "https://github.com/alangrainger/share-note/blob/main/src/note.ts"
    click Template "https://github.com/alangrainger/share-note/blob/main/src/NoteTemplate.ts"
    click Compressor "https://github.com/alangrainger/share-note/blob/main/src/Compressor.ts"
    click Crypto "https://github.com/alangrainger/share-note/blob/main/src/crypto.ts"
    click APIClient "https://github.com/alangrainger/share-note/blob/main/src/api.ts"
    click Types "https://github.com/alangrainger/share-note/blob/main/src/types.ts"
    click FileTypes "https://github.com/alangrainger/share-note/blob/main/src/libraries/FileTypes.ts"
    click Manifest "https://github.com/alangrainger/share-note/blob/main/manifest.json"
    click Styles "https://github.com/alangrainger/share-note/blob/main/styles.css"

    %% Styles
    classDef client fill:#BBDEFB,stroke:#2196F3
    classDef external fill:#C8E6C9,stroke:#4CAF50
    classDef datastore fill:#FFEB3B,stroke:#FBC02D
    classDef decision fill:#F8BBD0,stroke:#E91E63
```
