# phibr0/obsidian-commander architecture

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

- Interactive diagram: https://gitdiagram.com/phibr0/obsidian-commander
- Repository: https://github.com/phibr0/obsidian-commander

## Overview

##### Project Type and Purpose
- Project type: A full‑stack (front‑end + runtime) Obsidian plugin written in TypeScript/React that extends the Obsidian UI.
- Purpose: Allow users to add, remove, reorder, and hide custom commands in various Obsidian UI areas (left ribbon, status bar, title bar, menu, page header).

##### File Structure
- Top‑level:
- manifest.json, package.json, scripts/, src/, locale/, styles/, build configs, GitHub/workflows.
- src/:
- src/main.ts – plugin entry point (initializes plugin, registers commands).
- src/manager/commands – logic to register, update, and remove command placements.
- src/assets, src/constants.ts, src/types.ts, src/l10n.ts – shared assets, types, localization loader.
- locale/: language JSON files for i18n.
- styles/: SASS/Tailwind config for UI theming.
- GitHub/workflows/release.yml – CI/CD pipeline for packaging and publishing the plugin.

##### README for Insights
- Confirms that the core functionality is to extend UI sections with custom commands.

a. Main Components
1. Obsidian Host (external service)
2. Plugin Loader (Obsidian runtime reads manifest.json)
3. Plugin Core (src/main.ts)
4. Command Manager (src/manager/commands/*)
5. UI Layer (React components in src/ui)
6. Localization Module (src/l10n.ts + locale JSON)
7. Storage (Obsidian’s Setting API for persisting command configurations)
8. Build Pipeline (scripts/ + esbuild + tailwind.config.js)
b. Relationships & Interactions
- On startup, Obsidian loads the Plugin Loader which invokes Plugin Core.
- Plugin Core hands off to the Command Manager to scan existing UI areas via Obsidian API.
- Command Manager registers hooks/commands in UI areas.
- When user opens settings, Plugin Core renders the UI Layer in a modal.
- UI Layer components call back into Command Manager to add/edit/delete/reorder commands.
- Command Manager updates persistent settings via Obsidian Storage API.
- Localization Module provides translated strings to UI Layer at render time.
- Build Pipeline compiles all src/TSX into a single JS bundle, injects manifest, and packages for release.
c. Architectural Patterns & Principles
- Modular separation of concerns: “manager” for logic, “ui” for presentation, “locale” for i18n.
- Plugin API boundary: the only external dependency is the Obsidian Plugin API.
- Reactive UI: user actions in React components immediately trigger manager updates.
d. Key Technologies & Frameworks
- TypeScript for type safety
- React/TSX for UI components
- SASS/Tailwind for styling
- esbuild for bundling
- Obsidian Plugin API for integration
- GitHub Actions for CI/CD

##### Final Advice
- Every directory as its own component or sub‑component to reflect the true modular structure.
- Be explicit about data persistence (settings JSON via Obsidian API).
- Don’t omit the build/deployment step—this is crucial for plugin packaging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Host
    ObsidianHost["Obsidian Host"]:::external

    %% Plugin Loader
    PluginLoader["Plugin Loader\n(manifest.json)"]:::runtime
    click PluginLoader "https://github.com/phibr0/obsidian-commander/blob/main/manifest.json"

    %% Plugin Core
    PluginCore["Plugin Core\n(src/main.ts)"]:::runtime
    click PluginCore "https://github.com/phibr0/obsidian-commander/blob/main/src/main.ts"

    %% Command Manager Core
    subgraph "Command Manager" 
        direction TB
        CmdIndex["Core Logic & Registry\n(src/manager/commands/index.ts)"]:::runtime
        click CmdIndex "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/index.ts"
        ExplorerMgr["Explorer Commands\n(explorerManager.ts)"]:::runtime
        click ExplorerMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/explorerManager.ts"
        LeftRibbonMgr["Left Ribbon Commands\n(leftRibbonManager.ts)"]:::runtime
        click LeftRibbonMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/leftRibbonManager.ts"
        StatusBarMgr["Status Bar Commands\n(statusBarManager.ts)"]:::runtime
        click StatusBarMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/statusBarManager.ts"
        TitleBarMgr["Title Bar Commands\n(titleBarManager.ts)"]:::runtime
        click TitleBarMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/titleBarManager.ts"
        MenuMgr["Menu Commands\n(menuManager.ts)"]:::runtime
        click MenuMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/menuManager.ts"
        PageHeaderMgr["Page Header Commands\n(pageHeaderManager.ts)"]:::runtime
        click PageHeaderMgr "https://github.com/phibr0/obsidian-commander/blob/main/src/manager/commands/pageHeaderManager.ts"
    end

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        UILayer["UI Layer\n(src/ui)"]:::ui
        click UILayer "https://github.com/phibr0/obsidian-commander/tree/main/src/ui"
        About["About & Credits\n(About.tsx, Credits.tsx)"]:::ui
        click About "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/About.tsx"
        Credits["Credits Component"]:::ui
        click Credits "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/Credits.tsx"
        MacroBuilder["Macro Builder\n(MacroBuilder.tsx)"]:::ui
        click MacroBuilder "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/MacroBuilder.tsx"
        MacroViewer["Macro Viewer\n(MacroViewer.tsx)"]:::ui
        click MacroViewer "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/MacroViewer.tsx"
        ColorPicker["Color Picker\n(ColorPicker.tsx)"]:::ui
        click ColorPicker "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/ColorPicker/ColorPicker.tsx"
        IconPicker["Icon Picker\n(chooseIconModal.ts)"]:::ui
        click IconPicker "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/chooseIconModal.ts"
        AdvancedSettings["Advanced Toolbar Settings\n(AdvancedToolbarSettings.tsx)"]:::ui
        click AdvancedSettings "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/AdvancedToolbarSettings.tsx"
        SettingTab["Settings Tab\n(settingTab.ts)"]:::ui
        click SettingTab "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/settingTab.ts"
        SettingTabModal["Settings Modal\n(settingTabModal.ts)"]:::ui
        click SettingTabModal "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/settingTabModal.ts"
        ConfirmDeleteModal["Confirm Delete Modal\n(confirmDeleteModal.ts)"]:::ui
        click ConfirmDeleteModal "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/confirmDeleteModal.ts"
        ConfirmDeleteComp["Confirm Delete Component\n(confirmDeleteComponent.tsx)"]:::ui
        click ConfirmDeleteComp "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/components/confirmDeleteComponent.tsx"
        MobileModify["Mobile Modify Modal\n(mobileModifyModal.ts)"]:::ui
        click MobileModify "https://github.com/phibr0/obsidian-commander/blob/main/src/ui/mobileModifyModal.ts"
    end

    %% Shared Assets & Utilities
    subgraph "Shared Assets & Utilities"
        direction TB
        Constants["Constants\n(src/constants.ts)"]:::util
        click Constants "https://github.com/phibr0/obsidian-commander/blob/main/src/constants.ts"
        Types["Types\n(src/types.ts)"]:::util
        click Types "https://github.com/phibr0/obsidian-commander/blob/main/src/types.ts"
        L10nLoader["Localization Loader\n(src/l10n.ts)"]:::locale
        click L10nLoader "https://github.com/phibr0/obsidian-commander/blob/main/src/l10n.ts"
        UtilFuncs["Utility Functions\n(src/util.tsx)"]:::util
        click UtilFuncs "https://github.com/phibr0/obsidian-commander/blob/main/src/util.tsx"
        Assets["Static Assets\n(src/assets)"]:::util
        click Assets "https://github.com/phibr0/obsidian-commander/tree/main/src/assets"
    end

    %% Localization Module
    Localization["Localization Module\n(locale/*.json)"]:::locale
    click Localization "https://github.com/phibr0/obsidian-commander/tree/main/locale"

    %% Storage
    Storage["Obsidian Storage API"]:::storage

    %% Build Pipeline & Scripts
    subgraph "Build Pipeline & CI/CD"
        direction TB
        Esbuild["Bundler Config\n(esbuild.config.mjs)"]:::build
        click Esbuild "https://github.com/phibr0/obsidian-commander/blob/main/scripts/esbuild.config.mjs"
        VersionBump["Versioning Script\n(version-bump.mjs)"]:::build
        click VersionBump "https://github.com/phibr0/obsidian-commander/blob/main/scripts/version-bump.mjs"
        VersionsJSON["Versions JSON\n(versions.json)"]:::build
        click VersionsJSON "https://github.com/phibr0/obsidian-commander/blob/main/versions.json"
        IconUpdater["Icon List Updater\n(update-icon-list.mjs)"]:::build
        click IconUpdater "https://github.com/phibr0/obsidian-commander/blob/main/scripts/update-icon-list.mjs"
        TailwindCfg["Tailwind Config\n(tailwind.config.js)"]:::build
        click TailwindCfg "https://github.com/phibr0/obsidian-commander/blob/main/tailwind.config.js"
        CIWorkflow["CI/CD Workflow\n(.github/workflows/release.yml)"]:::build
        click CIWorkflow "https://github.com/phibr0/obsidian-commander/blob/main/.github/workflows/release.yml"
    end

    %% Connections
    ObsidianHost -->|"loads manifest.json"| PluginLoader
    PluginLoader -->|"invoke onload()"| PluginCore
    PluginCore -->|"initialize managers"| CmdIndex
    CmdIndex --> ExplorerMgr
    CmdIndex --> LeftRibbonMgr
    CmdIndex --> StatusBarMgr
    CmdIndex --> TitleBarMgr
    CmdIndex --> MenuMgr
    CmdIndex --> PageHeaderMgr
    PluginCore -->|"render settings modal"| UILayer
    UILayer -->|"user actions"| CmdIndex
    CmdIndex -->|"saveSettings()"| Storage
    L10nLoader -->|"provide strings"| UILayer
    Localization -->|"translations"| L10nLoader
    UILayer -.->|"uses constants/types"| Constants
    UILayer -.-> UtilFuncs
    UILayer -.-> Assets
    BuildPipeline(BuildPipeline):::build
    Esbuild --> BuildPipeline
    VersionBump --> BuildPipeline
    VersionsJSON --> BuildPipeline
    IconUpdater --> BuildPipeline
    TailwindCfg --> BuildPipeline
    CIWorkflow --> BuildPipeline

    %% Styles and Theming
    classDef external fill:#ccc,stroke:#333,stroke-width:1px,color:#000
    classDef runtime fill:#bbdefb,stroke:#1e88e5,stroke-width:1px,color:#000
    classDef ui fill:#c8e6c9,stroke:#43a047,stroke-width:1px,color:#000
    classDef util fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000
    classDef locale fill:#f8bbd0,stroke:#d81b60,stroke-width:1px,color:#000
    classDef storage fill:#e1bee7,stroke:#8e24aa,stroke-width:1px,color:#000
    classDef build fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px,color:#000
```
