How quipex/obsidian-habit-tracking works
Project type and purpose
• This is an Obsidian plugin (“Obsidian Habit Button”) written in TypeScript. Its purpose is to let users track habits via one-tap buttons and groups in their Obsidian vault, with features like streaks, heatmaps, grace/warning periods, and Canvas support. It hooks into Obsidian’s plugin API, reads/writes markdown notes, and renders custom blocks.
File structure
• Top level:
• plugin/…: the entire plugin source, build config, tests
• assets/: demo GIFs and screenshots
• .github/: CI workflows
• test_vault/: example vault for functional tests
• plugin/src:
• main.ts – plugin entrypoint registers commands and block renderers
• habit-core.ts – core logic to log a habit, compute streaks/heatmaps
• habit-event-bus.ts – in-memory pub/sub for plugin modules
• habit-registry.ts – scans vault notes, caches habit definitions & state
• i18n.ts and locales/… – internationalization
• settings.ts – plugin settings schema
• types.d.ts – shared TS types
• plugin/scripts: utilities to bump versions and sync test vault
• plugin/esbuild.config.mjs: build setup
• plugin/tests + vitest.config.ts: unit & integration tests with a harness that mocks Obsidian
README for additional insights
• Describes how blocks (habit-button, habit-group) are injected via fenced code blocks
• Explains that groups can scan specified note locations or listen to registry updates
• Mentions automatic sync of Canvas placements
• Highlights features (event-driven updates, real-time rendering)
Components and their interactions (to be shown
a. Main components:
1. Obsidian Host (the environment & vault)
2. Plugin Entrypoint (main.ts)
3. HabitRegistry service
4. EventBus
5. HabitCore service
6. UI Processors:
• HabitButtonRenderer
• HabitGroupRenderer
7. Settings & i18n modules
8. File System / Vault (markdown files & daily notes)
9. Build & Test pipeline (esbuild, Vitest)
b. Relationships / data flow:
• On activation, main.ts registers commands & block processors
• HabitRegistry scans vault → populates in-memory state
• EventBus broadcasts registry updates
• HabitButtonRenderer / HabitGroupRenderer subscribe to EventBus
• User clicks a habit button → HabitCore logs an entry to vault file → emits event via EventBus → UI re-renders (updates streaks/heatmaps)
• Blocks either poll registry or listen to updates to refresh aggregate status
• Settings → loaded by main.ts, passed to services for default behavior
• i18n → used by UI processors for localized labels/tooltips
• Build: esbuild bundles plugin into main.js + manifest.json → deployed in vault/.obsidian/plugins
• Tests: harness mocks Obsidian API, exercises services & renderers via Vitest
c. Architectural patterns and principles:
• Modular services: registry / core / event-bus separated by single responsibility
• Publish/subscribe for decoupling UI from core logic
• Plugin API adapter layer in main.ts
• Unit/integration tests isolated with stubs for file I/O & Obsidian
d. Key technologies/frameworks:
• TypeScript
• esbuild for bundling
• Vitest for testing
• Obsidian Plugin API
• JSON locales for i18n
Summary of elements
• Components: Obsidian Host, Vault, Plugin Entrypoint, HabitRegistry, EventBus, HabitCore, HabitButtonRenderer, HabitGroupRenderer, Settings, i18n, Build & Test pipeline
• Data flows for registration, scanning, event publication, UI rendering, file writes, user interactions
• Call out the modular separation and pub/sub pattern