How ratiger/obsidian-banyan works
Project Type and Purpose
• Type: A client‐side Obsidian plugin written in TypeScript + React that enhances note organization and review.
• Purpose: Provides a card-style browsing UI, compound filtering, random review, and heat-map statistics for Obsidian notes, all running within the Obsidian host application.
File Structure
Top-Level Directories/Files of Interest
• src/
– main.ts: plugin entry point, registers commands & views with Obsidian API
– BanyanPlugin.ts: core plugin class (implements onload, onunload, event handlers)
– BanyanPluginSettings.ts & BanyanSettingTab.tsx: settings model + settings UI
– components/: reusable React components (ConfirmModal, TagInput, etc.)
– pages/: page-level React components (CardDashboard, sidebar panels, header, etc.)
– store/: state management hooks (useDashBoardStore, useFilterSchemeStore, etc.), likely using Zustand or similar
– models/: data schemas (FileInfo, FilterScheme, ViewScheme, TagFilter, DateRange)
– utils/: file utilities (reading/writing note files), fileWatcher, i18n support
• manifest.json: plugin metadata for Obsidian
• esbuild.config.mjs: build config
• jest.config.js & test/: unit tests for core logic
• docs/: markdown docs and demo assets
Extract Architecture Insights from README
• Single-page panel UI injected into Obsidian’s left sidebar
• React + TypeScript for UI
• Persistent state (filter schemes, view schemes, random review settings) saved as JSON/YAML files in plugin’s directory under the vault
• Obsidian API used for file read/write, command registration, and UI mounting
Main Components & Interactions
a. Obsidian Host Application
– Provides plugin API: commands, workspace events, vault file system, UI mounting points
b. Plugin Core (BanyanPlugin)
– Lifecycle hooks (onload, onunload)
– Registers commands (open panel, open new note, random review)
– Subscribes to file system events (via fileWatcher)
c. Settings Subsystem
– BanyanPluginSettings model ←→ BanyanSettingTab React UI
– Persists settings in Obsidian’s settings storage
d. State Management Store
– useDashBoardStore, useFilterSchemeStore, useRandomReviewStore, useViewSchemeStore, useSettingsStore
– Central store holds current filters, view schemes, random review configurations
e. UI Layer (React Components & Pages)
– Top-level: CardDashboard.tsx (renders card grid)
– Sidebar panels: FilterSchemeView, RandomReviewView, HeatmapView
– Header: AddNoteView, SearchView
– Reusable: ConfirmModal, TagInput, FolderSuggest
f. Data Models & Utilities
– models/: define types & validation for FileInfo (note metadata), FilterScheme, TagFilter, etc.
– utils/fileUtils.ts: read/write note files, parse frontmatter
– utils/fileWatcher.ts: listen to Vault changes, trigger store updates
– utils/i18n: provide localized strings
g. Local File System (Vault)
– Plugin reads/writes note files under .obsidian/plugins/banyan/cards (default directory)
– Persists custom filter/view schemes as JSON in plugin data folder
Architectural Patterns & Design Principles
• Modular layering: Core plugin logic, settings, UI components, state store, and utilities all in separate modules.
• Unidirectional data flow: user action → command or event → store update → React re-render.
• Observer pattern: fileWatcher observes Vault changes → notifies store.
• MVC-like:
– Model: models/ + store/
– View: React components under components/ and pages/
– Controller: commands and event handlers in BanyanPlugin.ts + main.ts
Final Checklist
• Clear component labels (e.g., “BanyanPlugin (onload, commands)”)
• Callouts for persistence layers (Obsidian settings vs. plugin data files)
• Related modules (models + utils, UI components + pages, store)