# aidenlx/alx-folder-note architecture

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

- Interactive diagram: https://gitdiagram.com/aidenlx/alx-folder-note
- Repository: https://github.com/aidenlx/alx-folder-note

## Overview

##### Project type and purpose
- This is an Obsidian plugin written in TypeScript that augments the built-in file explorer with “folder note” functionality (creating and syncing a note with each folder). It is packaged via esbuild, installed into Obsidian via a manifest.json, and depends on the external folder-note-core plugin for core folder-note logic.

##### File structure
- Top‐level build and config:
- package.json, pnpm-lock.yaml, tsconfig.json, esbuild.config.mjs, scripts/ob-bumper.mjs
- manifest.json (+ manifest-beta.json) defining the plugin’s metadata and entry point
- Source code under src/:
- fn-main.ts – plugin entry (loads settings, registers commands, initializes patches)
- fe-patch.ts – orchestrates front-end patches (applies all fe-handler modules)
- click-handler.ts, drag-patch.ts – event interceptors for click and drag on folders
- settings.ts & settings.less – UI for plugin configuration
- typings/ – TypeScript definitions for Obsidian API and SVG
- Other metadata: CHANGELOG.md, LICENSE, README.md

##### Review the README for architectural clues
- It describes how the plugin hooks into the Obsidian file explorer to:
- Open or create a folder note when a folder is clicked
- Hide or reveal the note in the explorer
- Sync folder & note names (rename)
- Toggle a folder-focus mode
- Optionally render a Folder Overview codeblock (`folderv`)
- It calls out an external dependency: folder-note-core

##### Main components
a. Build & Packaging Subsystem
- Developer machine with PNPM & esbuild.config.mjs → bundles TypeScript + Less → outputs dist/ + plugin manifest
- Scripts folder for version bumping (ob-bumper) and release (`release-it.cjs`)
b. Plugin Host (Obsidian)
- Obsidian app core loads plugin via manifest.json
- folder-note-core plugin (peer dependency)
c. alx-folder-note Plugin Runtime
- Plugin Entry (fn-main.ts)
– Reads user settings
– Registers commands & context-menu items with Obsidian API
– Invokes fe-patch to apply UI patches
- Event Handlers
– click-handler.ts intercepts folder clicks
– drag-patch.ts intercepts drag events
- Feature Modules
- Style Patches
– fe-handler/*.less for custom CSS injected into the explorer
d. Obsidian File Explorer UI
- Receives patched behaviors and styles
- Interacts with the folder-note-core to create, sync, hide, reveal notes
e. Optional Folder Overview Service
- Codeblock parser for `folderv`
- Renders dynamic summary cards of folder contents

##### Relationships and Interactions
- Developer → (build) → Plugin Package
- Obsidian Host loads → Plugin Entry → registers Event Handlers & UI Patches
- UI Patches → modify File Explorer DOM and styles
- Event Handlers → call folder-note-core APIs to create/rename/sync notes
- Settings UI ↔ User & Plugin Entry (two-way binding)
- Optional folderv codeblock parser ↔ folder overview renderer ↔ File Explorer pane

##### Architectural patterns & design principles
- Modular layering: separation between build, core plugin entry, event handlers, feature modules, and styling
- Patch/Decorator pattern: injecting behavior into Obsidian’s existing file explorer rather than forking it
- Observer pattern: subscribing to user events (click, drag, context-menu) via Obsidian API
- Dependency decoupling: relying on folder-note-core for business logic, while focusing on UI integration

##### Technology stack to call out
- TypeScript + tsconfig
- Less for styling (compiled via esbuild)
- esbuild (esbuild.config.mjs) for bundling
- PNPM for package management
- Obsidian Plugin API
- External plugin: folder-note-core

##### Essential elements to capture
- Build pipeline → plugin artifact
- Obsidian loading mechanism (manifest + API registration)
- Core entrypoint (fn-main.ts)
- Separation of concerns: event handlers vs. feature modules vs. styles
- External dependency (folder-note-core)
- User interaction flow: click/drag → plugin → file explorer update

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Packaging Subsystem
    subgraph "Build & Packaging Subsystem"
        direction TB
        DevMachine["Developer Machine"]:::build
        PKG["package.json"]:::build
        LOCK["pnpm-lock.yaml"]:::build
        TSC["tsconfig.json"]:::build
        ESB["esbuild.config.mjs"]:::build
        BUMP["scripts/ob-bumper.mjs"]:::build
        REL[".release-it.cjs"]:::build
        MAN1["manifest.json"]:::build
        MAN2["manifest-beta.json"]:::build
        DevMachine --> PKG --> LOCK --> TSC --> ESB --> BUMP --> REL --> MAN1 --> MAN2
        MAN2 --> PluginArtifact
    end

    PluginArtifact["Plugin Artifact (dist + manifest)"]:::build

    %% Obsidian Host
    subgraph "Obsidian Host" 
        direction TB
        ObsidianCore["Obsidian Core"]:::host
        CoreDependency["folder-note-core"]:::external
        ObsidianCore --> CoreDependency
        PluginArtifact --> ObsidianCore
    end

    %% Plugin Runtime
    subgraph "alx-folder-note Plugin Runtime"
        direction TB
        Entry["fn-main.ts"]:::plugin
        DocsSettings["Settings UI"]:::plugin
        PatchOrch["fe-patch.ts"]:::plugin
        ClickHandler["click-handler.ts"]:::plugin
        DragHandler["drag-patch.ts"]:::plugin
        FeatureModules["Feature Modules"]:::plugin
        StylePatches["Style Patches"]:::plugin
        Optional["Folder Overview (folderv)"]:::pluginOpt

        PluginArtifact --> Entry
        Entry --> DocsSettings
        Entry --> PatchOrch
        Entry --> ClickHandler
        Entry --> DragHandler
        Entry --> FeatureModules
        Entry --> StylePatches
        Entry --> Optional

        %% Settings UI
        subgraph "Settings UI"
            direction TB
            AppSettings["src/settings.ts"]:::plugin
            AppStyles["src/settings.less"]:::plugin
            DocsSettings --> AppSettings --> AppStyles
        end

        %% UI Patch Orchestrator
        subgraph "UI Patches (fe-handler)"
            direction TB
            BaseDef["base.ts"]:::plugin
            IndexFE["index.ts"]:::plugin
            ActiveFE["active-folder.ts"]:::plugin
            FocusFE["folder-focus.ts"]:::plugin
            MarkFE["folder-mark.ts"]:::plugin
            Less1["file-explorer.less"]:::plugin
            Less2["focus.less"]:::plugin
            Less3["folder-icon.less"]:::plugin
            PatchOrch --> BaseDef --> IndexFE --> ActiveFE --> FocusFE --> MarkFE
            MarkFE --> Less1 --> Less2 --> Less3
        end

        %% Feature Modules
        subgraph "Feature Modules"
            direction TB
            LongPress["long-press.ts"]:::plugin
            SetIcon["set-folder-icon.ts"]:::plugin
            FeatureModules --> LongPress --> SetIcon
        end

        %% Event Handlers
        subgraph "Event Handlers"
            direction TB
            ClickHandler --> CoreDependency
            DragHandler --> CoreDependency
        end

        %% Folder Overview optional
        subgraph "Optional Folder Overview" 
            direction TB
            Misc["src/misc.ts"]:::plugin
        end
    end

    %% File Explorer UI
    FileExplorer["Obsidian File Explorer UI"]:::host
    CoreDependency --> FileExplorer
    IndexFE --> FileExplorer

    %% Click events for mappings
    click PKG "https://github.com/aidenlx/alx-folder-note/blob/master/package.json"
    click LOCK "https://github.com/aidenlx/alx-folder-note/blob/master/pnpm-lock.yaml"
    click TSC "https://github.com/aidenlx/alx-folder-note/blob/master/tsconfig.json"
    click ESB "https://github.com/aidenlx/alx-folder-note/blob/master/esbuild.config.mjs"
    click BUMP "https://github.com/aidenlx/alx-folder-note/blob/master/scripts/ob-bumper.mjs"
    click REL "https://github.com/aidenlx/alx-folder-note/blob/master/.release-it.cjs"
    click MAN1 "https://github.com/aidenlx/alx-folder-note/blob/master/manifest.json"
    click MAN2 "https://github.com/aidenlx/alx-folder-note/blob/master/manifest-beta.json"
    click Entry "https://github.com/aidenlx/alx-folder-note/blob/master/src/fn-main.ts"
    click PatchOrch "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-patch.ts"
    click ClickHandler "https://github.com/aidenlx/alx-folder-note/blob/master/src/click-handler.ts"
    click DragHandler "https://github.com/aidenlx/alx-folder-note/blob/master/src/drag-patch.ts"
    click LongPress "https://github.com/aidenlx/alx-folder-note/blob/master/src/modules/long-press.ts"
    click SetIcon "https://github.com/aidenlx/alx-folder-note/blob/master/src/modules/set-folder-icon.ts"
    click BaseDef "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/base.ts"
    click IndexFE "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/index.ts"
    click ActiveFE "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/active-folder.ts"
    click FocusFE "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/folder-focus.ts"
    click MarkFE "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/folder-mark.ts"
    click Less1 "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/file-explorer.less"
    click Less2 "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/focus.less"
    click Less3 "https://github.com/aidenlx/alx-folder-note/blob/master/src/fe-handler/folder-icon.less"
    click AppSettings "https://github.com/aidenlx/alx-folder-note/blob/master/src/settings.ts"
    click AppStyles "https://github.com/aidenlx/alx-folder-note/blob/master/src/settings.less"
    click Misc "https://github.com/aidenlx/alx-folder-note/blob/master/src/misc.ts"
    click ObsSVG "https://github.com/aidenlx/alx-folder-note/blob/master/src/typings/svg.d.ts"
    click ObsAPI "https://github.com/aidenlx/alx-folder-note/blob/master/src/typings/obsidian-ex.d.ts"

    %% Styles
    classDef build fill:#e0e0e0,stroke:#999,stroke-width:1px
    classDef plugin fill:#cfe2ff,stroke:#339,stroke-width:1px
    classDef host fill:#d4edda,stroke:#3c763d,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef pluginOpt fill:#f8d7da,stroke:#721c24,stroke-width:1px,stroke-dasharray: 5 5
```
