# akosbalasko/zoottelkeeper-obsidian-plugin architecture

> Architecture diagram of the GitHub repository akosbalasko/zoottelkeeper-obsidian-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akosbalasko/zoottelkeeper-obsidian-plugin
- Repository: https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin

## Overview

1. **Repository purpose and runtime boundary**
   - This is an **Obsidian plugin** written in **TypeScript**. Its runtime boundary is the Obsidian app and its vault filesystem.
   - The plugin’s job is to keep “index” notes in sync with folder structure, so each folder can have an autogenerated note that links to its children.

2. **Top-level orchestration lives in `main.ts`**
   - `main.ts` is the entry point and likely contains the plugin class lifecycle: load settings, register commands/settings UI, subscribe to vault file events, and trigger index regeneration.
   - It is the central coordinator that connects vault events and manual actions to the lower-level helpers in `utils/`.

3. **Configuration is a first-class subsystem**
   - `defaultSettings.ts` provides the baseline plugin configuration.
   - `interfaces/ZottelkeeperPluginSettings.ts` and related interface files define the settings shape and typed options.
   - The settings model includes behaviors that materially affect architecture: index prefix, list style, sorting order, folder include/exclude rules, frontmatter/meta tags, template path, and whether to embed sub-index content.

4. **Folder scoping and filtering is separated from content generation**
   - `utils/isInSpecificFolder.ts` and `utils/cleanDisallowedFolders.ts` implement the boundary rules for which folders are managed.
   - The readme indicates include/exclude paths are evaluated against absolute vault paths, with optional recursive matching using `*`.
   - This filtering step determines which folders get index files and prevents updates in disallowed regions of the vault.

5. **Index file identification and lifecycle**
   - The plugin appears to recognize index notes by a configurable prefix and/or by matching the folder name.
   - `consts.ts` likely stores sentinel strings and constants used to detect autogenerated regions and preserve custom content.
   - The lifecycle is: detect folder scope → locate/create corresponding index note → update only the autogenerated section.

6. **Autogenerated content is updated surgically**
   - `utils/updateIndexContent.ts` is the core content generator/updater.
   - The readme describes a protected region delimited by “beginning/end of autogenerated index file list” markers; the plugin updates only that region and leaves surrounding manual content intact.
   - This is the main architectural boundary between autogenerated data and user-authored note content.

7. **Frontmatter handling is isolated**
   - `utils/hasFrontmatter.ts`, `getFrontmatter.ts`, `removeFrontmatter.ts`, and `updateFrontmatter.ts` form a dedicated frontmatter subsystem.
   - These helpers let the plugin detect YAML frontmatter, read existing metadata, preserve or strip it as needed, and rewrite tags/meta fields consistently.
   - This is important because the plugin can optionally add YAML metadata to generated index notes.

8. **File content model and sorting are explicitly modeled**
   - The `models/` folder, especially `models/sortOrder.ts`, suggests sorting is treated as a domain concern rather than ad hoc string handling.
   - `interfaces/GeneralContentOptions.ts` and `interfaces/IndexItemStyle.ts` likely define how list entries are rendered: plain links, bullet lists, or checkbox links.
   - These options influence the shape of the generated index content but not the vault traversal logic.

9. **External plugin/template integration is a deliberate extension point**
   - The readme shows integration with the **Templater** Obsidian plugin for pre-seeding index notes with placeholders.
   - Zoottelkeeper respects template-managed notes by updating only the designated autogenerated block, which allows custom surrounding text while still regenerating folder listings.
   - This is an integration boundary, not a hard dependency in the codebase itself.

10. **Build and packaging**
   - `rollup.config.js`, `tsconfig.json`, `manifest.json`, `styles.css`, and `versions.json` show a standard Obsidian plugin packaging pipeline.
   - Rollup bundles the TypeScript plugin for distribution; `manifest.json` describes plugin metadata for Obsidian; `styles.css` contains UI styling for the plugin settings or generated note presentation.

11. **End-to-end data flow**
   - On startup or file/folder changes, the plugin scans the vault.
   - It filters folders by include/exclude rules.
   - For each eligible folder, it resolves the target index note, reads existing note content/frontmatter, generates a sorted list of children, and writes back only the managed section.
   - The result is a set of stable folder-index notes that automatically track vault structure without overwriting custom content outside the autogenerated block.

12. **Architectural shape**
   - The repo is organized as a small, single-purpose plugin with a clear split between:
     - orchestration (`main.ts`)
     - configuration and typed settings (`interfaces/`, `defaultSettings.ts`)
     - domain helpers for vault path handling and frontmatter (`utils/`)
     - rendering/sorting models (`models/`)
   - There are no obvious backend services or multi-process boundaries; everything operates inside the Obsidian host against local vault files.

Main entry points: [`utils/updateIndexContent.ts`](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/updateIndexContent.ts) (Index updater), [`main.ts`](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/main.ts) (Main plugin), [`interfaces/ZottelkeeperPluginSettings.ts`](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/ZottelkeeperPluginSettings.ts) (Plugin settings), [`interfaces/GeneralContentOptions.ts`](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/GeneralContentOptions.ts) (Content options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main plugin<br/>entrypoint<br/>[main.ts]"]
end

subgraph group_config["Configuration"]
  node_default_settings["Defaults<br/>[defaultSettings.ts]"]
  node_plugin_settings["Plugin settings<br/>settings schema"]
  node_general_content_options["Content options<br/>render options"]
  node_index_item_style["Item style<br/>render enum<br/>[IndexItemStyle.ts]"]
  node_interfaces_index["Interfaces barrel<br/>module export<br/>[index.ts]"]
end

subgraph group_content["Content Sync"]
  node_folder_filter["Folder filter<br/>scope rules"]
  node_folder_cleanup["Disallowed cleanup<br/>scope filter"]
  node_index_content["Index updater<br/>content generator"]
  node_utils_index["Utils barrel<br/>module export<br/>[index.ts]"]
end

subgraph group_metadata["Metadata"]
  node_frontmatter_check["Has frontmatter<br/>yaml helper<br/>[hasFrontmatter.ts]"]
  node_frontmatter_read["Read frontmatter<br/>yaml helper<br/>[getFrontmatter.ts]"]
  node_frontmatter_strip["Strip frontmatter<br/>yaml helper"]
  node_frontmatter_write["Write frontmatter<br/>yaml helper"]
end

subgraph group_domain["Domain Models"]
  node_sort_order["Sort order<br/>domain model<br/>[sortOrder.ts]"]
  node_content_models["Content models<br/>domain types<br/>[index.ts]"]
end

subgraph group_packaging["Packaging"]
  node_build["Build config<br/>bundler config<br/>[rollup.config.js]"]
  node_manifest["Plugin manifest<br/>distribution metadata<br/>[manifest.json]"]
  node_styles["Styles<br/>ui css<br/>[styles.css]"]
end

node_default_settings -->|"populate"| node_plugin_settings
node_plugin_settings -->|"configure"| node_main
node_general_content_options -->|"shape output"| node_main
node_index_item_style -->|"type option"| node_general_content_options
node_main -->|"scope folders"| node_folder_filter
node_main -->|"prune scope"| node_folder_cleanup
node_folder_filter -->|"feeds"| node_folder_cleanup
node_main -->|"update notes"| node_index_content
node_index_content -->|"sort children"| node_sort_order
node_index_content -->|"inspect"| node_frontmatter_check
node_index_content -->|"read metadata"| node_frontmatter_read
node_index_content -->|"preserve body"| node_frontmatter_strip
node_index_content -->|"rewrite metadata"| node_frontmatter_write
node_frontmatter_read -->|"round-trip"| node_frontmatter_write
node_content_models -->|"data shapes"| node_index_content
node_utils_index -->|"export"| node_folder_filter
node_utils_index -->|"export"| node_index_content
node_interfaces_index -->|"export"| node_plugin_settings
node_interfaces_index -->|"export"| node_general_content_options
node_build -->|"package"| node_manifest
node_build -->|"include"| node_styles

click node_main "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/main.ts"
click node_default_settings "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/defaultSettings.ts"
click node_plugin_settings "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/ZottelkeeperPluginSettings.ts"
click node_general_content_options "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/GeneralContentOptions.ts"
click node_index_item_style "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/IndexItemStyle.ts"
click node_folder_filter "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/isInSpecificFolder.ts"
click node_folder_cleanup "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/cleanDisallowedFolders.ts"
click node_index_content "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/updateIndexContent.ts"
click node_frontmatter_check "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/hasFrontmatter.ts"
click node_frontmatter_read "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/getFrontmatter.ts"
click node_frontmatter_strip "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/removeFrontmatter.ts"
click node_frontmatter_write "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/updateFrontmatter.ts"
click node_sort_order "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/models/sortOrder.ts"
click node_content_models "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/models/index.ts"
click node_utils_index "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/index.ts"
click node_interfaces_index "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/index.ts"
click node_build "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/rollup.config.js"
click node_manifest "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/manifest.json"
click node_styles "https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/styles.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_default_settings,node_plugin_settings,node_general_content_options,node_index_item_style,node_interfaces_index toneAmber
class node_folder_filter,node_folder_cleanup,node_index_content,node_utils_index toneMint
class node_frontmatter_check,node_frontmatter_read,node_frontmatter_strip,node_frontmatter_write toneRose
class node_sort_order,node_content_models toneIndigo
class node_build,node_manifest,node_styles toneTeal
```

## Components

### Runtime

Obsidian plugin execution inside the vault

- [Main plugin](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/main.ts): entrypoint · Plugin lifecycle, commands, event hooks, and sync orchestration · `main.ts`

### Configuration

Typed settings and defaults

- [Defaults](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/defaultSettings.ts): settings defaults · Baseline plugin configuration · `defaultSettings.ts`
- [Plugin settings](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/ZottelkeeperPluginSettings.ts): settings schema · Typed settings shape and options · `interfaces/ZottelkeeperPluginSettings.ts`
- [Content options](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/GeneralContentOptions.ts): render options · Controls for generated list style and content shape · `interfaces/GeneralContentOptions.ts`
- [Item style](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/IndexItemStyle.ts): render enum · Styles for index entries and list presentation · `interfaces/IndexItemStyle.ts`
- [Interfaces barrel](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/interfaces/index.ts): module export · Convenience exports for type definitions · `interfaces/index.ts`

### Content Sync

Folder scanning, filtering, and index note updates

- [Folder filter](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/isInSpecificFolder.ts): scope rules · Include/exclude and recursive path matching · `utils/isInSpecificFolder.ts`
- [Disallowed cleanup](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/cleanDisallowedFolders.ts): scope filter · Prunes folders outside the managed scope · `utils/cleanDisallowedFolders.ts`
- [Index updater](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/updateIndexContent.ts): content generator · Surgically updates the autogenerated index block · `utils/updateIndexContent.ts`
- [Utils barrel](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/index.ts): module export · Convenience exports for utility helpers · `utils/index.ts`

### Metadata

Frontmatter handling

- [Has frontmatter](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/hasFrontmatter.ts): yaml helper · Detects whether a note has YAML frontmatter · `utils/hasFrontmatter.ts`
- [Read frontmatter](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/getFrontmatter.ts): yaml helper · Extracts existing frontmatter data · `utils/getFrontmatter.ts`
- [Strip frontmatter](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/removeFrontmatter.ts): yaml helper · Removes frontmatter for controlled rewriting · `utils/removeFrontmatter.ts`
- [Write frontmatter](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/utils/updateFrontmatter.ts): yaml helper · Rewrites tags and metadata for index notes · `utils/updateFrontmatter.ts`

### Domain Models

Shared sort and content types

- [Sort order](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/models/sortOrder.ts): domain model · Sorting rules for generated folder listings · `models/sortOrder.ts`
- [Content models](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/models/index.ts): domain types · Shared types for generated content and item rendering · `models/index.ts`

### Packaging

Build and plugin distribution files

- [Build config](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/rollup.config.js): bundler config · Rollup bundling for the Obsidian plugin · `rollup.config.js`
- [Plugin manifest](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/manifest.json): distribution metadata · Obsidian plugin metadata and activation info · `manifest.json`
- [Styles](https://github.com/akosbalasko/zoottelkeeper-obsidian-plugin/blob/master/styles.css): ui css · Plugin and note presentation styling · `styles.css`

## Connections

- Defaults → Plugin settings: populate · Defaults initialize the typed settings shape
- Plugin settings → Main plugin: configure · Main plugin consumes the settings model
- Content options → Main plugin: shape output · Rendering options influence index generation
- Item style → Content options: type option · Item style is one of the content rendering choices
- Main plugin → Folder filter: scope folders · Plugin checks whether a vault folder is managed
- Main plugin → Disallowed cleanup: prune scope · Managed folder sets are cleaned before updates
- Folder filter → Disallowed cleanup: feeds · Folder inclusion rules drive pruning decisions
- Main plugin → Index updater: update notes · Main orchestration triggers index regeneration
- Index updater → Sort order: sort children · Generated entries are ordered by the domain sort model
- Index updater → Has frontmatter: inspect · Updater checks whether metadata is present
- Index updater → Read frontmatter: read metadata · Existing YAML is read before rewriting
- Index updater → Strip frontmatter: preserve body · Frontmatter can be removed while updating managed content
- Index updater → Write frontmatter: rewrite metadata · Metadata is rewritten when plugin settings require it
- Read frontmatter → Write frontmatter: round-trip · Existing metadata informs the new frontmatter
- Content models → Index updater: data shapes · Generated content uses shared domain types
- Utils barrel → Folder filter: export · Utility barrel exposes helper functions
- Utils barrel → Index updater: export · Utility barrel exposes the content updater
- Interfaces barrel → Plugin settings: export · Interface barrel exposes settings types
- Interfaces barrel → Content options: export · Interface barrel exposes content option types
- Build config → Plugin manifest: package · Bundled output is described by plugin metadata
- Build config → Styles: include · Distribution package includes plugin styling
