# obsidianmd/obsidian-releases architecture

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

- Interactive diagram: https://gitdiagram.com/obsidianmd/obsidian-releases
- Repository: https://github.com/obsidianmd/obsidian-releases

## Overview

#### Purpose and Consumers
This is Obsidian’s public distribution metadata repository, not the Obsidian application source. The Obsidian desktop client consumes curated JSON registries here to discover community plugins, themes, snippets, and public desktop releases. GitHub Actions maintain selected registry-derived artifacts.

#### Primary Entry Points
The client-facing registries are repository-root JSON files:
- `community-plugins.json`
- `community-css-themes.json`
- `community-snippets.json`
- `desktop-releases.json`

`README.md` defines the plugin installation contract: the client reads the plugin registry, then retrieves plugin metadata and release artifacts from each plugin’s GitHub repository.

#### Community Plugin Directory
`community-plugins.json` is the canonical plugin catalog. It supplies plugin identity and searchable metadata, including name, author, and description. A plugin entry directs Obsidian to an external GitHub repository; detailed metadata and installable artifacts do not live in this repository.

Lifecycle and policy overlays are represented separately:
- `community-plugins-removed.json`
- `community-plugin-deprecation.json`
- `community-plugin-stats.json`

These files allow the catalog to distinguish active plugins from removed/deprecated entries and publish aggregate or per-plugin statistics without changing the core discovery format.

#### Plugin Installation Boundary
Plugin installation crosses from this static registry into GitHub-hosted plugin repositories:
1. Obsidian selects an entry from `community-plugins.json`.
2. For plugin detail and version resolution, it fetches that repository’s `manifest.json` and `README.md`.
3. It compares the manifest’s Obsidian compatibility requirement; when needed, it consults the plugin repository’s `versions.json`.
4. It downloads release assets tagged with the manifest version: `manifest.json`, `main.js`, and optional `styles.css`.

Thus this repository owns discovery/curation, while plugin authors’ GitHub repositories and GitHub Releases own executable plugin delivery.

#### Theme and Snippet Directories
Theme discovery is represented by `community-css-themes.json`, with removals separated into `community-css-themes-removed.json`. Community snippets are indexed by `community-snippets.json`. Like plugins, these are public directory data rather than bundled application assets.

#### Desktop Release Publication
`desktop-releases.json` is the public release metadata surface for Obsidian desktop releases. It is distinct from community extensibility registries and enables clients or release consumers to resolve official application versions independently of plugin/theme catalogs.

#### Automation and Runtime
The repository is static-data-first, with Node/npm metadata in `package.json` and `package-lock.json`. GitHub Actions provide operational automation:
- `.github/workflows/mirror-community-json.yml` mirrors community JSON data.
- `.github/workflows/plugin-stat.yml` generates or updates plugin statistics.

GitHub is the material infrastructure boundary: it hosts this registry, runs the workflows, and serves external plugin repositories and release assets referenced by the catalog.

Main entry points: [`community-plugins.json`](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugins.json) (Plugin catalog), [`.github/workflows/mirror-community-json.yml`](https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/mirror-community-json.yml) (Community JSON mirror), [`community-plugin-stats.json`](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugin-stats.json) (Plugin statistics), [`.github/workflows/plugin-stat.yml`](https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/plugin-stat.yml) (Plugin statistics job)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_registries["Public registries"]
  node_plugin_catalog["Plugin catalog<br/>JSON registry"]
  node_plugin_removed["Removed plugins<br/>policy registry"]
  node_plugin_deprecation["Plugin deprecations<br/>policy registry"]
  node_plugin_stats["Plugin statistics<br/>derived registry"]
  node_theme_catalog["Theme catalog<br/>JSON registry"]
  node_theme_removed["Removed themes<br/>policy registry"]
  node_snippet_catalog["Snippet catalog<br/>JSON registry"]
  node_desktop_releases["Desktop releases<br/>JSON registry"]
end

subgraph group_automation["Repository automation"]
  node_mirror_workflow{{"Community JSON mirror<br/>GitHub Actions workflow"}}
  node_stats_workflow{{"Plugin statistics job<br/>GitHub Actions workflow<br/>[plugin-stat.yml]"}}
end

subgraph group_external["GitHub delivery boundary"]
  node_plugin_repository["Plugin GitHub repository<br/>external repository"]
  node_plugin_metadata["Plugin metadata<br/>manifest and docs"]
  node_plugin_release_assets["Plugin release assets<br/>GitHub Release assets"]
  node_github{{"GitHub platform<br/>infrastructure"}}
end

node_obsidian_client["Obsidian desktop client<br/>consumer"]
node_install_contract["Installation contract<br/>documentation<br/>[README.md]"]
node_node_metadata["Node/npm metadata<br/>runtime metadata<br/>[package.json]"]

node_obsidian_client -->|"discovers plugins"| node_plugin_catalog
node_obsidian_client -->|"discovers themes"| node_theme_catalog
node_obsidian_client -->|"discovers snippets"| node_snippet_catalog
node_obsidian_client -->|"resolves desktop versions"| node_desktop_releases
node_install_contract -.->|"defines lookup"| node_plugin_catalog
node_plugin_catalog -->|"links author repository"| node_plugin_repository
node_plugin_repository -->|"serves detail and compatibility"| node_plugin_metadata
node_plugin_metadata -->|"selects manifest version"| node_plugin_release_assets
node_obsidian_client -->|"fetches metadata"| node_plugin_metadata
node_obsidian_client -->|"downloads installable assets"| node_plugin_release_assets
node_plugin_removed -.->|"lifecycle overlay"| node_plugin_catalog
node_plugin_deprecation -.->|"lifecycle overlay"| node_plugin_catalog
node_plugin_stats -.->|"statistics overlay"| node_plugin_catalog
node_theme_removed -.->|"lifecycle overlay"| node_theme_catalog
node_mirror_workflow -->|"mirrors data"| node_plugin_catalog
node_stats_workflow -->|"updates statistics"| node_plugin_stats
node_node_metadata -.->|"tooling runtime"| node_mirror_workflow
node_github -->|"runs"| node_mirror_workflow
node_github -->|"runs"| node_stats_workflow
node_github -->|"hosts"| node_plugin_repository
node_github -->|"serves"| node_plugin_release_assets

click node_plugin_catalog "https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugins.json"
click node_plugin_removed "https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugins-removed.json"
click node_plugin_deprecation "https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugin-deprecation.json"
click node_plugin_stats "https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugin-stats.json"
click node_theme_catalog "https://github.com/obsidianmd/obsidian-releases/blob/master/community-css-themes.json"
click node_theme_removed "https://github.com/obsidianmd/obsidian-releases/blob/master/community-css-themes-removed.json"
click node_snippet_catalog "https://github.com/obsidianmd/obsidian-releases/blob/master/community-snippets.json"
click node_desktop_releases "https://github.com/obsidianmd/obsidian-releases/blob/master/desktop-releases.json"
click node_install_contract "https://github.com/obsidianmd/obsidian-releases/blob/master/README.md"
click node_node_metadata "https://github.com/obsidianmd/obsidian-releases/blob/master/package.json"
click node_mirror_workflow "https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/mirror-community-json.yml"
click node_stats_workflow "https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/plugin-stat.yml"

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_plugin_catalog,node_plugin_removed,node_plugin_deprecation,node_plugin_stats,node_theme_catalog,node_theme_removed,node_snippet_catalog,node_desktop_releases toneBlue
class node_mirror_workflow,node_stats_workflow toneAmber
class node_plugin_repository,node_plugin_metadata,node_plugin_release_assets,node_github toneMint
class node_obsidian_client,node_install_contract,node_node_metadata toneNeutral
```

## Components

### Public registries

Client-consumed distribution metadata.

- [Plugin catalog](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugins.json): JSON registry · Canonical curated community plugin directory. · `community-plugins.json`
- [Removed plugins](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugins-removed.json): policy registry · Separates removed entries from the active catalog. · `community-plugins-removed.json`
- [Plugin deprecations](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugin-deprecation.json): policy registry · Records plugin lifecycle deprecations. · `community-plugin-deprecation.json`
- [Plugin statistics](https://github.com/obsidianmd/obsidian-releases/blob/master/community-plugin-stats.json): derived registry · Publishes aggregate or per-plugin statistics. · `community-plugin-stats.json`
- [Theme catalog](https://github.com/obsidianmd/obsidian-releases/blob/master/community-css-themes.json): JSON registry · Community CSS theme discovery directory. · `community-css-themes.json`
- [Removed themes](https://github.com/obsidianmd/obsidian-releases/blob/master/community-css-themes-removed.json): policy registry · Separates removed themes from the active directory. · `community-css-themes-removed.json`
- [Snippet catalog](https://github.com/obsidianmd/obsidian-releases/blob/master/community-snippets.json): JSON registry · Community snippet discovery directory. · `community-snippets.json`
- [Desktop releases](https://github.com/obsidianmd/obsidian-releases/blob/master/desktop-releases.json): JSON registry · Public metadata for official desktop versions. · `desktop-releases.json`

### Repository automation

GitHub Actions maintain derived registry data.

- [Community JSON mirror](https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/mirror-community-json.yml): GitHub Actions workflow · Mirrors community JSON data. · `.github/workflows/mirror-community-json.yml`
- [Plugin statistics job](https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/plugin-stat.yml): GitHub Actions workflow · Generates or updates plugin statistics. · `.github/workflows/plugin-stat.yml`

### GitHub delivery boundary

Plugin authors and releases own installable artifacts.

- **Plugin GitHub repository**: external repository · Author-owned source of detail, compatibility, and releases.
- **Plugin metadata**: manifest and docs · manifest.json, README.md, and optional versions.json.
- **Plugin release assets**: GitHub Release assets · Versioned manifest.json, main.js, and optional styles.css.
- **GitHub platform**: infrastructure · Hosts registries, workflows, repositories, and releases.

### Other components

- **Obsidian desktop client**: consumer · Discovers extensions and resolves desktop releases.
- [Installation contract](https://github.com/obsidianmd/obsidian-releases/blob/master/README.md): documentation · Defines registry-to-plugin installation resolution. · `README.md`
- [Node/npm metadata](https://github.com/obsidianmd/obsidian-releases/blob/master/package.json): runtime metadata · Supports static-data repository tooling. · `package.json`

## Connections

- Obsidian desktop client → Plugin catalog: discovers plugins
- Obsidian desktop client → Theme catalog: discovers themes
- Obsidian desktop client → Snippet catalog: discovers snippets
- Obsidian desktop client → Desktop releases: resolves desktop versions
- Installation contract → Plugin catalog: defines lookup
- Plugin catalog → Plugin GitHub repository: links author repository
- Plugin GitHub repository → Plugin metadata: serves detail and compatibility
- Plugin metadata → Plugin release assets: selects manifest version
- Obsidian desktop client → Plugin metadata: fetches metadata
- Obsidian desktop client → Plugin release assets: downloads installable assets
- Removed plugins → Plugin catalog: lifecycle overlay
- Plugin deprecations → Plugin catalog: lifecycle overlay
- Plugin statistics → Plugin catalog: statistics overlay
- Removed themes → Theme catalog: lifecycle overlay
- Community JSON mirror → Plugin catalog: mirrors data
- Plugin statistics job → Plugin statistics: updates statistics
- Node/npm metadata → Community JSON mirror: tooling runtime
- GitHub platform → Community JSON mirror: runs
- GitHub platform → Plugin statistics job: runs
- GitHub platform → Plugin GitHub repository: hosts
- GitHub platform → Plugin release assets: serves
