# coddingtonbear/obsidian-local-rest-api architecture

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

- Interactive diagram: https://gitdiagram.com/coddingtonbear/obsidian-local-rest-api
- Repository: https://github.com/coddingtonbear/obsidian-local-rest-api

## Overview

Obsidian Local REST API exposes vault operations through authenticated REST and MCP interfaces. Clients send requests to the plugin’s server; REST handling and MCP tools dispatch vault work, while Obsidian provides vault data and events. Documented capabilities include note CRUD and targeted patching, searching, active-file access, commands, tags, event streams, and file opening. The graph also shows security, extension, and API-description layers. Some subsystems are represented from README claims and the source index; unsampled implementation details and links are omitted.

Main entry points: [`src/requestHandler.ts`](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/requestHandler.ts) (REST routes), [`src/main.ts`](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/main.ts) (HTTP server), [`src/mcpHandler.ts`](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/mcpHandler.ts) (MCP tools), [`src/vaultOperations.ts`](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultOperations.ts) (Vault operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client interfaces"]
  node_server["HTTP server<br/>[main.ts]"]
  node_rest_routes["REST routes<br/>[requestHandler.ts]"]
  node_mcp_tools["MCP tools<br/>[mcpHandler.ts]"]
  node_mcp_schema["MCP schemas<br/>[mcpSchema.ts]"]
end

subgraph group_vault["Vault capabilities"]
  node_vault_ops["Vault operations<br/>[vaultOperations.ts]"]
  node_vault_path["Vault path guard<br/>[vaultPath.ts]"]
  node_patching["Targeted patching<br/>[requestHandler.ts]"]
  node_search["Vault search<br/>[vaultOperations.ts]"]
  node_events["Event streams<br/>[events.ts]"]
  node_subresources["Vault subresources"]
end

subgraph group_security["Security and state"]
  node_conditional["Conditional requests"]
  node_signed_urls["Signed URLs<br/>[signedUrls.ts]"]
  node_certificates["TLS certificates<br/>[certificates.ts]"]
  node_state["Server state<br/>[serverState.ts]"]
end

subgraph group_extensions["Extension platform"]
  node_extension_api["Extension API<br/>[publicApi.ts]"]
  node_openapi["OpenAPI spec<br/>[openApiSpec.ts]"]
end

node_rest_client(("REST clients"))
node_mcp_client(("MCP clients"))
node_obsidian["Obsidian host"]

node_rest_client -->|"sends requests"| node_server
node_mcp_client -->|"connects to"| node_server
node_server -->|"routes requests"| node_rest_routes
node_rest_routes -->|"delegates vault work"| node_vault_ops
node_mcp_tools -->|"invokes operations"| node_vault_ops
node_mcp_tools -->|"uses schemas"| node_mcp_schema
node_vault_ops -->|"reads and writes vault"| node_obsidian
node_rest_routes -->|"handles patch requests"| node_patching
node_rest_routes -->|"offers search"| node_search
node_rest_routes -->|"offers event streams"| node_events
node_rest_routes -->|"routes subresources"| node_subresources
node_vault_ops -->|"checks paths"| node_vault_path
node_rest_routes -->|"checks conditions"| node_conditional
node_mcp_tools -->|"checks preconditions"| node_conditional
node_mcp_tools -->|"creates signed links"| node_signed_urls
node_signed_urls -->|"validates paths"| node_vault_path
node_server -->|"generates certificates"| node_certificates
node_server -->|"uses state limits"| node_state
node_rest_routes -->|"exposes extensions"| node_extension_api
node_rest_routes -->|"serves API spec"| node_openapi
node_extension_api -->|"contributes descriptions"| node_openapi
node_obsidian -->|"emits vault events"| node_events

click node_server "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/main.ts"
click node_rest_routes "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/requestHandler.ts"
click node_mcp_tools "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/mcpHandler.ts"
click node_mcp_schema "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/mcpSchema.ts"
click node_vault_ops "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultOperations.ts"
click node_vault_path "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultPath.ts"
click node_patching "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/requestHandler.ts"
click node_search "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultOperations.ts"
click node_events "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/events.ts"
click node_subresources "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultSubresources.ts"
click node_conditional "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/conditionalRequests.ts"
click node_signed_urls "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/signedUrls.ts"
click node_certificates "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/certificates.ts"
click node_state "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/serverState.ts"
click node_extension_api "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/publicApi.ts"
click node_openapi "https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/openApiSpec.ts"

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_server,node_rest_routes,node_mcp_tools,node_mcp_schema,node_rest_client,node_mcp_client toneBlue
class node_vault_ops,node_vault_path,node_patching,node_search,node_events,node_subresources toneAmber
class node_conditional,node_signed_urls,node_certificates,node_state toneMint
class node_extension_api,node_openapi toneRose
class node_obsidian toneIndigo
```

## Components

### Client interfaces

- [HTTP server](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/main.ts): `src/main.ts`
- [REST routes](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/requestHandler.ts): `src/requestHandler.ts`
- [MCP tools](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/mcpHandler.ts): `src/mcpHandler.ts`
- [MCP schemas](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/mcpSchema.ts): `src/mcpSchema.ts`

### Vault capabilities

- [Vault operations](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultOperations.ts): `src/vaultOperations.ts`
- [Vault path guard](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultPath.ts): `src/vaultPath.ts`
- [Targeted patching](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/requestHandler.ts): `src/requestHandler.ts`
- [Vault search](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultOperations.ts): `src/vaultOperations.ts`
- [Event streams](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/events.ts): `src/events.ts`
- [Vault subresources](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/vaultSubresources.ts): `src/vaultSubresources.ts`

### Security and state

- [Conditional requests](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/conditionalRequests.ts): `src/conditionalRequests.ts`
- [Signed URLs](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/signedUrls.ts): `src/signedUrls.ts`
- [TLS certificates](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/certificates.ts): `src/certificates.ts`
- [Server state](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/serverState.ts): `src/serverState.ts`

### Extension platform

- [Extension API](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/publicApi.ts): `src/publicApi.ts`
- [OpenAPI spec](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/src/openApiSpec.ts): `src/openApiSpec.ts`

### Other components

- **REST clients**
- **MCP clients**
- **Obsidian host**

## Connections

- REST clients → HTTP server: sends requests (evidence: `README.md`)
- MCP clients → HTTP server: connects to (evidence: `README.md`)
- HTTP server → REST routes: routes requests (evidence: `src/main.ts`)
- REST routes → Vault operations: delegates vault work (evidence: `src/requestHandler.ts`)
- MCP tools → Vault operations: invokes operations (evidence: `src/mcpHandler.ts`)
- MCP tools → MCP schemas: uses schemas (evidence: `src/mcpHandler.ts`)
- Vault operations → Obsidian host: reads and writes vault (evidence: `src/vaultOperations.ts`)
- REST routes → Targeted patching: handles patch requests (evidence: `README.md`)
- REST routes → Vault search: offers search (evidence: `README.md`)
- REST routes → Event streams: offers event streams (evidence: `README.md`)
- REST routes → Vault subresources: routes subresources (evidence: `src/requestHandler.ts`)
- Vault operations → Vault path guard: checks paths (evidence: `src/vaultOperations.ts`)
- REST routes → Conditional requests: checks conditions (evidence: `src/requestHandler.ts`)
- MCP tools → Conditional requests: checks preconditions (evidence: `src/mcpHandler.ts`)
- MCP tools → Signed URLs: creates signed links (evidence: `src/mcpHandler.ts`)
- Signed URLs → Vault path guard: validates paths (evidence: `src/signedUrls.ts`)
- HTTP server → TLS certificates: generates certificates (evidence: `src/main.ts`)
- HTTP server → Server state: uses state limits (evidence: `src/main.ts`)
- REST routes → Extension API: exposes extensions (evidence: `src/requestHandler.ts`)
- REST routes → OpenAPI spec: serves API spec (evidence: `src/requestHandler.ts`)
- Extension API → OpenAPI spec: contributes descriptions (evidence: `src/openApiSpec.ts`)
- Obsidian host → Event streams: emits vault events (evidence: `README.md`)
