Obsidian Reference ArchitectureSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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 <[email protected]>
tags:
- saas
- obsidian
- obsidian-reference
compatibility: Designed for Claude Code
---
# 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

```typescript
// 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 { VaultService } from './services/vault-service';

export default class MyPlugin extends Plugin {
  settings: MyPluginSettings;
  vaultService: VaultService;

  async onload() {
    await this.loadSettings();
    this.vaultService = new VaultService(this.app);

    registerCommands(this);
    registerViews(this);
    this.addSettingTab(new MySettingTab(this.app, this));
  }

  onunload() {
    // Services clean up their own resources
    this.vaultService.destroy();
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}
```

### Step 3: Command Registry Pattern

```typescript
// src/commands/index.ts
import type MyPlugin from '../main';
import { insertTemplate } from './insert-template';
import { toggleSidebar } from './toggle-sidebar';

export function registerCommands(plugin: MyPlugin) {
  plugin.addCommand({
    id: 'insert-template',
    name: 'Insert Template',
    editorCallback: (editor, view) => insertTemplate(plugin, editor, view),
  });

  plugin.addCommand({
    id: 'toggle-sidebar',
    name: 'Toggle Sidebar',
    callback: () => toggleSidebar(plugin),
  });
}
```

```typescript
// src/commands/insert-template.ts
import { Editor, MarkdownView } from 'obsidian';
import type MyPlugin from '../main';

export function insertTemplate(plugin: MyPlugin, editor: Editor, view: MarkdownView) {
  const template = plugin.settings.defaultTemplate;
  editor.replaceSelection(template);
}
```

### Step 4: View Manager

```typescript
// src/views/index.ts
import type MyPlugin from '../main';
import { SidebarView, VIEW_TYPE_SIDEBAR } from './sidebar-view';

export function registerViews(plugin: MyPlugin) {
  plugin.registerView(VIEW_TYPE_SIDEBAR, (leaf) => new SidebarView(leaf, plugin));

  // Add ribbon icon to activate view
  plugin.addRibbonIcon('layout-sidebar-right', 'Open Sidebar', () => {
    activateView(plugin);
  });
}

async function activateView(plugin: MyPlugin) {
  const { workspace } = plugin.app;

  let leaf = workspace.getLeavesOfType(VIEW_TYPE_SIDEBAR)[0];
  if (!leaf) {
    const rightLeaf = workspace.getRightLeaf(false);
    if (rightLeaf) {
      await rightLeaf.setViewState({ type: VIEW_TYPE_SIDEBAR, active: true });
      leaf = rightLeaf;
    }
  }
  if (leaf) {
    workspace.revealLeaf(leaf);
  }
}
```

```typescript
// src/views/sidebar-view.ts
import { ItemView, WorkspaceLeaf } from 'obsidian';
import type MyPlugin from '../main';

export const VIEW_TYPE_SIDEBAR = 'my-plugin-sidebar';

export class SidebarView extends ItemView {
  plugin: MyPlugin;

  constructor(leaf: WorkspaceLeaf, plugin: MyPlugin) {
    super(leaf);
    this.plugin = plugin;
  }

  getViewType(): string {
    return VIEW_TYPE_SIDEBAR;
  }

  getDisplayText(): string {
    return 'My Plugin';
  }

  getIcon(): string {
    return 'layout-sidebar-right';
  }

  async onOpen() {
    const container = this.containerEl.children[1];
    container.empty();
    container.addClass('my-plugin-sidebar');

    container.createEl('h3', { text: 'My Plugin' });
    const list = container.createEl('ul');

    // Populate from service layer
    const files = await this.plugin.vaultService.getRecentFiles(10);
    for (const file of files) {
      list.createEl('li', { text: file.basename });
    }
  }

  async onClose() {
    // Clean up DOM references
    this.containerEl.empty();
  }
}
```

### Step 5: Service Layer for Vault Operations

```typescript
// src/services/vault-service.ts
import { App, TFile, TFol

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.