# quipex/obsidian-habit-tracking architecture

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

- Interactive diagram: https://gitdiagram.com/quipex/obsidian-habit-tracking
- Repository: https://github.com/quipex/obsidian-habit-tracking

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ObsidianHost["Obsidian Host (API & Environment)"]:::external
    Vault["Vault (Markdown Notes & Canvas)"]:::external

    %% Plugin Entry & Modules
    subgraph "Plugin Core"
        direction TB
        PluginEntrypoint["Plugin Entrypoint\n(main.ts)"]:::core
        Settings["Settings Module"]:::core
        i18n["i18n Module"]:::core
        Locales["Locale Definitions"]:::core
        Types["Shared Types"]:::core
        HabitRegistry["HabitRegistry Service"]:::core
        EventBus["EventBus (Pub/Sub)"]:::core
        HabitCore["HabitCore Service"]:::core
    end

    subgraph "UI Renderers"
        direction TB
        HabitButtonRenderer["HabitButtonRenderer"]:::ui
        HabitGroupRenderer["HabitGroupRenderer"]:::ui
    end

    %% Build & Test Pipeline
    subgraph "Build & Test Pipeline"
        direction TB
        BuildConfig["esbuild Config"]:::pipeline
        Manifest["Plugin Manifest"]:::pipeline
        Stylesheet["Stylesheet"]:::pipeline
        Scripts["Version & Manifest Scripts"]:::pipeline
        Tests["Unit & Integration Tests"]:::pipeline
        VitestConfig["Vitest Config"]:::pipeline
        CIWorkflows["CI Workflows"]:::pipeline
    end

    %% Test Vault Setup
    TestVaultSetup["Example Test Vault Setup"]:::external

    %% Connections
    ObsidianHost -->|loads plugin| PluginEntrypoint
    Vault -->|scan notes| HabitRegistry
    PluginEntrypoint -->|loads settings| Settings
    PluginEntrypoint -->|loads locales| Locales
    PluginEntrypoint -->|loads i18n| i18n
    PluginEntrypoint -->|register renderers & commands| HabitButtonRenderer
    PluginEntrypoint -->|register renderers & commands| HabitGroupRenderer
    PluginEntrypoint -->|connect services| HabitRegistry
    PluginEntrypoint -->|connect services| EventBus

    HabitRegistry -->|publish updates| EventBus
    EventBus -->|notify| HabitButtonRenderer
    EventBus -->|notify| HabitGroupRenderer

    HabitButtonRenderer -->|click| HabitCore
    HabitCore -->|append entry| Vault
    HabitCore -->|emit update| EventBus

    HabitGroupRenderer -->|query| HabitRegistry

    PluginEntrypoint -->|bundle config| BuildConfig
    BuildConfig -->|outputs| Manifest
    BuildConfig -->|includes| Stylesheet

    Scripts -->|sync & update| TestVaultSetup
    Tests -->|mock| ObsidianHost
    Tests -->|exercise modules| HabitCore
    Tests -->|exercise modules| HabitRegistry
    Tests -->|exercise modules| HabitButtonRenderer
    VitestConfig -->|configures| Tests
    CIWorkflows -->|runs| BuildConfig
    CIWorkflows -->|runs| Tests

    %% Click Events
    click ObsidianHost "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/tests/stubs/obsidian.ts"
    click Vault "https://github.com/quipex/obsidian-habit-tracking/tree/master/test_vault/"
    click PluginEntrypoint "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/main.ts"
    click HabitRegistry "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/habit-registry.ts"
    click EventBus "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/habit-event-bus.ts"
    click HabitCore "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/habit-core.ts"
    click HabitButtonRenderer "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/main.ts"
    click HabitGroupRenderer "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/main.ts"
    click Settings "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/settings.ts"
    click i18n "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/i18n.ts"
    click Locales "https://github.com/quipex/obsidian-habit-tracking/tree/master/plugin/src/locales/"
    click Types "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/src/types.d.ts"
    click Stylesheet "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/styles.css"
    click BuildConfig "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/esbuild.config.mjs"
    click Manifest "https://github.com/quipex/obsidian-habit-tracking/blob/master/manifest.json"
    click Tests "https://github.com/quipex/obsidian-habit-tracking/tree/master/plugin/tests/"
    click VitestConfig "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/vitest.config.ts"
    click CIWorkflows "https://github.com/quipex/obsidian-habit-tracking/tree/master/.github/workflows/"
    click Scripts "https://github.com/quipex/obsidian-habit-tracking/tree/master/plugin/scripts/"
    click TestVaultSetup "https://github.com/quipex/obsidian-habit-tracking/blob/master/plugin/tests/harness.ts"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef ui fill:#DFFFE0,stroke:#228B22,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px
    classDef pipeline fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
```
