obsidian-reference-architecture

name	obsidian-reference-architecture
description	Implement Obsidian reference architecture with best-practice project layout. Use when designing new plugins, reviewing project structure, or establishing architecture standards for Obsidian development. Trigger with phrases like "obsidian architecture", "obsidian project structure", "obsidian best practices", "organize obsidian plugin".
allowed-tools	Read, Grep
version	1.13.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","obsidian","obsidian-reference"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Obsidian Reference Architecture

Overview

Architecture patterns for complex Obsidian plugins: modular project structure with separate files for views, commands, settings, and services; state management; a service layer for vault operations; command registry; view manager; and CSS scoping.

Prerequisites

• TypeScript and Obsidian API familiarity
• Working build pipeline (esbuild recommended)
• Plugin scaffolding complete (manifest.json, package.json, tsconfig.json)

Instructions

Step 1: Project Structure

my-plugin/
├── src/
│   ├── main.ts              # Plugin entry — thin orchestrator
│   ├── types.ts              # Shared interfaces and type definitions
│   ├── constants.ts          # Plugin-wide constants
│   ├── commands/
│   │   ├── index.ts          # Command registry
│   │   ├── insert-template.ts
│   │   └── toggle-sidebar.ts
│   ├── views/
│   │   ├── index.ts          # View registry
│   │   ├── sidebar-view.ts
│   │   └── modal-view.ts
│   ├── settings/
│   │   ├── settings.ts       # Settings interface and defaults
│   │   └── settings-tab.ts   # Settings UI tab
│   └── services/
│       ├── vault-service.ts  # File read/write/search operations
│       ├── metadata-service.ts  # Frontmatter and cache operations
│       └── sync-service.ts   # External sync or background tasks
├── styles.css
├── manifest.json
├── versions.json
├── package.json
├── tsconfig.json
└── esbuild.config.mjs

Step 2: Thin Main Entry Point

// src/main.ts — orchestrates, does not implement
import { Plugin } from 'obsidian';
import { MyPluginSettings, DEFAULT_SETTINGS } from './settings/settings';
import { MySettingTab } from './settings/settings-tab';
import { registerCommands } from './commands';
import { registerViews } from './views';
import {  }  ;

      {
  : ;
  : ;

   () {
     .();
    . =  (.);

    ();
    ();
    .( (., ));
  }

  () {
    
    ..();
  }

   () {
    . = .({}, ,  .());
  }

   () {
     .(.);
  }
}