commit b655c58ba16f2c326bf64bddf9e4b4e370798d46
Author: Andrey Epifancev <andrey.epifancev@ssi-solutions.ru>
Date:   Tue Oct 7 16:17:02 2025 +0400

    Initial commit: Add design document
    
    🤖 Generated with [Claude Code](https://claude.ai/code)
    
    Co-Authored-By: Claude <noreply@anthropic.com>

diff --git a/design.md b/design.md
new file mode 100644
index 0000000..0648de1
--- /dev/null
+++ b/design.md
@@ -0,0 +1,1872 @@
+# Obsidian MCP Server - Design Document
+
+**Version:** 1.0.0  
+**Date:** 2025-10-07  
+**Status:** Draft
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [System Overview](#2-system-overview)
+3. [Architecture](#3-architecture)
+4. [Domain Model](#4-domain-model)
+5. [Use Cases](#5-use-cases)
+6. [API Specification](#6-api-specification)
+7. [Data Model](#7-data-model)
+8. [Infrastructure Design](#8-infrastructure-design)
+9. [Security & Performance](#9-security--performance)
+10. [Testing Strategy](#10-testing-strategy)
+11. [Deployment](#11-deployment)
+12. [Implementation Roadmap](#12-implementation-roadmap)
+
+---
+
+## 1. Executive Summary
+
+### 1.1 Project Goals
+
+Разработать легковесный, производительный MCP-сервер на Go для работы с Obsidian vault через Model Context Protocol.
+
+**Ключевые цели:**
+- Предоставить AI-ассистентам полный доступ к Obsidian заметкам
+- Поддержать Git workflow для версионирования
+- Обеспечить быстрый поиск и навигацию по заметкам
+- Работать с wikilinks, тегами и frontmatter
+- Быть легко расширяемым и поддерживаемым
+
+### 1.2 Key Requirements
+
+**Функциональные:**
+- CRUD операции над заметками
+- Полнотекстовый и семантический поиск
+- Работа с графом связей (backlinks/outlinks)
+- Управление тегами и метаданными
+- Git интеграция (commit, push, pull)
+- Поддержка шаблонов и daily notes
+
+**Нефункциональные:**
+- Производительность: < 100ms на операцию чтения
+- Надёжность: обработка ошибок, валидация данных
+- Масштабируемость: поддержка vault до 10,000+ заметок
+- Maintainability: чистая архитектура, 80%+ test coverage
+
+### 1.3 Technology Stack
+
+| Component | Technology | Justification |
+|-----------|-----------|---------------|
+| Language | Go 1.21+ | Производительность, лёгковесность |
+| MCP SDK | github.com/modelcontextprotocol/go-sdk | Официальная реализация |
+| Git | github.com/go-git/go-git/v5 | Pure Go, без C зависимостей |
+| Markdown | github.com/yuin/goldmark | CommonMark compliant |
+| Frontmatter | go.abhg.dev/goldmark/frontmatter | Интеграция с goldmark |
+
+---
+
+## 2. System Overview
+
+### 2.1 System Context Diagram
+
+```mermaid
+graph TB
+    subgraph "MCP Clients"
+        Claude[Claude Desktop]
+        Cursor[Cursor IDE]
+        Other[Other MCP Clients]
+    end
+    
+    subgraph "Obsidian MCP Server"
+        MCP[MCP Protocol Layer]
+        Tools[MCP Tools 45+]
+        Resources[MCP Resources]
+        Prompts[MCP Prompts]
+    end
+    
+    subgraph "Data Storage"
+        Vault[Obsidian Vault<br/>Markdown Files]
+        Git[Git Repository]
+    end
+    
+    Claude -->|stdio/SSE| MCP
+    Cursor -->|stdio/SSE| MCP
+    Other -->|stdio/SSE| MCP
+    
+    MCP --> Tools
+    MCP --> Resources
+    MCP --> Prompts
+    
+    Tools -->|Read/Write| Vault
+    Tools -->|Commit/Push/Pull| Git
+    
+    Vault -.->|Version Control| Git
+```
+
+### 2.2 High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Presentation Layer"
+        MCPT[MCP Tools]
+        MCPR[MCP Resources]
+        MCPP[MCP Prompts]
+    end
+    
+    subgraph "Application Layer"
+        UC1[Note Use Cases]
+        UC2[Search Use Cases]
+        UC3[Link Use Cases]
+        UC4[Tag Use Cases]
+        UC5[Git Use Cases]
+    end
+    
+    subgraph "Domain Layer"
+        Note[Note Entity]
+        Vault[Vault Entity]
+        Link[WikiLink VO]
+        Tag[Tag VO]
+        FM[Frontmatter VO]
+    end
+    
+    subgraph "Infrastructure Layer"
+        FS[Filesystem Repository]
+        GitRepo[Git Repository]
+        MD[Markdown Parser]
+        Index[Search Index]
+    end
+    
+    MCPT --> UC1
+    MCPT --> UC2
+    MCPR --> UC1
+    MCPP --> UC1
+    
+    UC1 --> Note
+    UC2 --> Note
+    UC3 --> Link
+    UC4 --> Tag
+    UC5 --> GitRepo
+    
+    UC1 --> FS
+    UC1 --> GitRepo
+    UC2 --> Index
+    
+    FS --> MD
+    FS --> Note
+    GitRepo --> Vault
+```
+
+### 2.3 Key Components
+
+| Component | Responsibility | Technology |
+|-----------|---------------|------------|
+| MCP Server | Protocol handling, tool registration | go-sdk/mcp |
+| Use Cases | Business logic, orchestration | Pure Go |
+| Domain Model | Business entities, rules | Pure Go |
+| Repositories | Data persistence abstraction | Interfaces |
+| Markdown Parser | Parse MD, frontmatter, wikilinks | goldmark |
+| Git Manager | Version control operations | go-git |
+| Search Index | Fast full-text search | In-memory |
+
+---
+
+## 3. Architecture
+
+### 3.1 Clean Architecture
+
+**Принципы:**
+- Dependency Rule: зависимости направлены внутрь (к Domain)
+- Domain независим от frameworks и libraries
+- Use Cases содержат бизнес-логику
+- Infrastructure легко заменяема
+
+### 3.2 Layer Diagram
+
+```mermaid
+graph LR
+    subgraph "Layer 4: Infrastructure"
+        FS[File System]
+        Git[Git Impl]
+        Parser[MD Parser]
+    end
+    
+    subgraph "Layer 3: Adapters"
+        MCP[MCP Adapter]
+        DTO[DTOs]
+        Repo[Repository Impl]
+    end
+    
+    subgraph "Layer 2: Application"
+        UC[Use Cases]
+        Iface[Repository Interfaces]
+    end
+    
+    subgraph "Layer 1: Domain"
+        Entity[Entities]
+        VO[Value Objects]
+        Rules[Business Rules]
+    end
+    
+    MCP --> UC
+    UC --> Iface
+    Repo --> Iface
+    Repo --> FS
+    Repo --> Git
+    Repo --> Parser
+    UC --> Entity
+    Entity --> VO
+    Entity --> Rules
+```
+
+### 3.3 Dependency Flow
+
+```mermaid
+flowchart TD
+    A[MCP Client Request] --> B[MCP Tool Handler]
+    B --> C[Use Case]
+    C --> D{Repository Interface}
+    D --> E[Repository Implementation]
+    E --> F[Infrastructure<br/>Filesystem/Git/Parser]
+    F --> G[Domain Entity]
+    G --> E
+    E --> C
+    C --> B
+    B --> H[MCP Client Response]
+    
+    style D fill:#f9f,stroke:#333
+    style G fill:#9ff,stroke:#333
+```
+
+### 3.4 Directory Structure
+
+```
+obsidian-mcp-server/
+├── cmd/
+│   └── obsidian-mcp/
+│       └── main.go                    # Entry point
+├── internal/
+│   ├── domain/                        # Domain layer
+│   │   ├── note.go
+│   │   ├── vault.go
+│   │   ├── frontmatter.go
+│   │   ├── wikilink.go
+│   │   ├── tag.go
+│   │   └── errors.go
+│   ├── repository/                    # Repository interfaces
+│   │   ├── note_repository.go
+│   │   ├── git_repository.go
+│   │   └── vault_repository.go
+│   ├── usecase/                       # Application use cases
+│   │   ├── note/
+│   │   ├── search/
+│   │   ├── link/
+│   │   ├── tag/
+│   │   ├── frontmatter/
+│   │   ├── git/
+│   │   └── vault/
+│   ├── infrastructure/                # Infrastructure
+│   │   ├── filesystem/
+│   │   ├── git/
+│   │   ├── markdown/
+│   │   └── index/
+│   ├── adapter/                       # Interface adapters
+│   │   ├── mcp/
+│   │   │   ├── server.go
+│   │   │   ├── tools/
+│   │   │   ├── resources/
+│   │   │   └── prompts/
+│   │   └── dto/
+│   └── config/
+├── pkg/                               # Public packages
+├── test/                              # Tests
+├── go.mod
+└── README.md
+```
+
+---
+
+## 4. Domain Model
+
+### 4.1 Domain Entity Diagram
+
+```mermaid
+classDiagram
+    class Note {
+        -string path
+        -string content
+        -Frontmatter frontmatter
+        -[]WikiLink outlinks
+        -[]Tag tags
+        -time createdAt
+        -time modifiedAt
+        +NewNote(path, content) Note
+        +AddTag(tag) error
+        +RemoveTag(tag) error
+        +UpdateContent(content) error
+        +ExtractLinks() []WikiLink
+    }
+    
+    class Vault {
+        -string rootPath
+        -[]Note notes
+        -Graph graph
+        -map tags
+        +NewVault(path) Vault
+        +AddNote(note) error
+        +GetStats() VaultStats
+    }
+    
+    class Frontmatter {
+        -map data
+        +Get(key) interface{}
+        +Set(key, value) error
+        +Merge(other) Frontmatter
+    }
+    
+    class WikiLink {
+        -string target
+        -string alias
+        -string section
+        +Target() string
+        +IsValid() bool
+    }
+    
+    class Tag {
+        -string name
+        +Name() string
+        +Parent() Tag
+        +IsNested() bool
+    }
+    
+    class Graph {
+        -map adjacencyList
+        +AddEdge(from, to)
+        +GetBacklinks(path) []string
+        +GetOutlinks(path) []string
+    }
+    
+    Vault "1" *-- "0..*" Note
+    Note "1" *-- "0..1" Frontmatter
+    Note "1" *-- "0..*" WikiLink
+    Note "1" *-- "0..*" Tag
+    Vault "1" *-- "1" Graph
+```
+
+### 4.2 Core Entities
+
+#### 4.2.1 Note Entity
+
+**Responsibilities:**
+- Хранить путь, контент и метаданные
+- Управлять тегами
+- Валидировать содержимое
+- Отслеживать временные метки
+
+**Business Rules:**
+- Path должен быть уникальным
+- Path должен заканчиваться на .md
+- Content может быть пустым
+- Теги не могут дублироваться
+- ModifiedAt обновляется при изменениях
+
+#### 4.2.2 Value Objects
+
+**Frontmatter:**
+- Immutable map данных
+- YAML совместимый
+- Поддержка стандартных полей (title, tags, date, etc)
+- Merge операции
+
+**WikiLink:**
+- Target (обязательный)
+- Alias (опциональный)
+- Section (опциональный)
+- Валидация существования target
+
+**Tag:**
+- Name с префиксом #
+- Поддержка nested tags (#project/ai)
+- Иерархия тегов
+
+### 4.3 Domain Errors
+
+| Error | Description | Handling |
+|-------|-------------|----------|
+| ErrNoteNotFound | Note doesn't exist | Return 404 |
+| ErrNoteAlreadyExists | Note path taken | Return 409 |
+| ErrInvalidPath | Invalid file path | Return 400 |
+| ErrEmptyContent | Content is empty | Return 400 |
+| ErrInvalidTag | Invalid tag format | Return 400 |
+| ErrCircularLink | Circular dependency | Return 400 |
+
+---
+
+## 5. Use Cases
+
+### 5.1 Use Case Catalog
+
+```mermaid
+mindmap
+  root((Use Cases))
+    Note Operations
+      Read Note
+      Create Note
+      Update Note
+      Delete Note
+      Rename Note
+    Search Operations
+      Search Content
+      Search by Tags
+      Search by Frontmatter
+    Link Operations
+      Get Backlinks
+      Get Outlinks
+      Get Graph
+      Find Broken Links
+      Update Links
+    Tag Operations
+      Get All Tags
+      Add Tags
+      Remove Tags
+      Rename Tag
+    Frontmatter Operations
+      Get Frontmatter
+      Update Frontmatter
+      Bulk Update
+    Git Operations
+      Status
+      Commit
+      Pull
+      Push
+      History
+    Vault Operations
+      Get Stats
+      Get Structure
+      List Notes
+      Find Orphaned
+```
+
+### 5.2 Key Use Case Specifications
+
+#### UC-001: Read Note
+
+**Actor:** MCP Client  
+**Preconditions:** Note exists  
+**Postconditions:** Note content returned
+
+**Main Flow:**
+1. Client requests note by path
+2. System performs git pull
+3. System reads note file
+4. System parses markdown
+5. System extracts frontmatter
+6. System extracts wikilinks and tags
+7. System returns note with metadata
+
+**Alternate Flows:**
+- Git pull fails → log warning, continue
+- File not found → return error
+- Invalid markdown → return partial content
+
+**Business Rules:**
+- Path relative to vault root
+- File must have .md extension
+- Read never modifies files
+
+#### UC-002: Create Note
+
+**Actor:** MCP Client  
+**Preconditions:** Note doesn't exist  
+**Postconditions:** Note created and committed
+
+**Main Flow:**
+1. Client requests creation
+2. System validates path
+3. System creates directories if needed
+4. System writes note file
+5. System commits to git
+6. System returns created note
+
+**Business Rules:**
+- Path must not exist
+- Content can be empty
+- Git commit is mandatory
+
+#### UC-010: Search Content
+
+**Actor:** MCP Client  
+**Preconditions:** Vault indexed  
+**Postconditions:** Results returned
+
+**Main Flow:**
+1. Client submits search query
+2. System validates query
+3. System searches index
+4. System ranks results
+5. System returns top N results
+
+**Search Types:**
+- Full-text (regex/substring)
+- Tag-based
+- Frontmatter
+- Semantic (future)
+
+#### UC-015: Get Backlinks
+
+**Actor:** MCP Client  
+**Preconditions:** Note exists  
+**Postconditions:** Backlinks returned
+
+**Main Flow:**
+1. Client requests backlinks
+2. System validates path
+3. System queries graph index
+4. System loads referring notes
+5. System returns backlinks with context
+
+### 5.3 Use Case Dependencies
+
+```mermaid
+graph TD
+    A[Create Note] --> B[Git Commit]
+    C[Update Note] --> B
+    D[Delete Note] --> B
+    E[Rename Note] --> F[Update Links]
+    F --> B
+    G[Search Content] --> H[Search Index]
+    I[Get Backlinks] --> J[Graph Index]
+```
+
+---
+
+## 6. API Specification
+
+### 6.1 MCP Tools Overview
+
+**Total Tools:** 45+
+
+**Categories:**
+- File Operations (5 tools)
+- Search Operations (3 tools)
+- Link Operations (5 tools)
+- Tag Operations (4 tools)
+- Frontmatter Operations (3 tools)
+- Git Operations (5 tools)
+- Vault Operations (5 tools)
+- Template Operations (3 tools)
+- Daily Notes (3 tools)
+- Batch Operations (3 tools)
+- Analytics (2 tools)
+
+### 6.2 File Operations
+
+#### `read_note`
+
+**Description:** Read Obsidian note with frontmatter and metadata
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "format": "markdown|json (default: json)"
+}
+```
+
+**Output Schema:**
+```json
+{
+  "path": "string",
+  "content": "string",
+  "frontmatter": "object",
+  "tags": ["string"],
+  "outlinks": [{"target": "string", "alias": "string"}],
+  "stats": {
+    "words": "number",
+    "characters": "number",
+    "created": "timestamp",
+    "modified": "timestamp"
+  }
+}
+```
+
+#### `create_note`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "content": "string",
+  "frontmatter": "object",
+  "create_dirs": "boolean (default: true)"
+}
+```
+
+**Output:** Created note object
+
+#### `update_note`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "content": "string",
+  "mode": "overwrite|append|prepend (default: overwrite)",
+  "frontmatter": "object",
+  "merge_frontmatter": "boolean (default: true)"
+}
+```
+
+#### `delete_note`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "confirm": "boolean (default: false)"
+}
+```
+
+#### `rename_note`
+
+**Input Schema:**
+```json
+{
+  "old_path": "string (required)",
+  "new_path": "string (required)",
+  "update_links": "boolean (default: true)"
+}
+```
+
+### 6.3 Search Operations
+
+#### `search_content`
+
+**Input Schema:**
+```json
+{
+  "query": "string (required)",
+  "max_results": "number (default: 50)",
+  "case_sensitive": "boolean (default: false)",
+  "use_regex": "boolean (default: false)",
+  "context_lines": "number (default: 2)"
+}
+```
+
+**Output Schema:**
+```json
+{
+  "results": [
+    {
+      "path": "string",
+      "matches": [
+        {
+          "line": "number",
+          "content": "string",
+          "context_before": "string",
+          "context_after": "string"
+        }
+      ],
+      "score": "number"
+    }
+  ],
+  "total": "number"
+}
+```
+
+#### `search_by_tags`
+
+**Input Schema:**
+```json
+{
+  "tags": ["string"],
+  "mode": "all|any (default: any)",
+  "include_nested": "boolean (default: true)"
+}
+```
+
+#### `search_by_frontmatter`
+
+**Input Schema:**
+```json
+{
+  "filters": "object",
+  "operator": "and|or (default: and)"
+}
+```
+
+### 6.4 Link Operations
+
+#### `get_backlinks`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "include_context": "boolean (default: true)"
+}
+```
+
+**Output Schema:**
+```json
+{
+  "note": "string",
+  "backlinks": [
+    {
+      "from": "string",
+      "context": "string",
+      "line": "number"
+    }
+  ],
+  "count": "number"
+}
+```
+
+#### `get_outlinks`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "resolve": "boolean (default: true)"
+}
+```
+
+#### `get_graph`
+
+**Input Schema:**
+```json
+{
+  "path": "string (required)",
+  "depth": "number (default: 1)",
+  "max_nodes": "number (default: 100)"
+}
+```
+
+**Output Schema:**
+```json
+{
+  "nodes": [{"path": "string", "title": "string"}],
+  "edges": [{"from": "string", "to": "string"}]
+}
+```
+
+#### `find_broken_links`
+
+**Input Schema:**
+```json
+{
+  "path": "string (optional, check specific note or entire vault)"
+}
+```
+
+#### `update_links`
+
+**Input Schema:**
+```json
+{
+  "old_path": "string (required)",
+  "new_path": "string (required)",
+  "dry_run": "boolean (default: false)"
+}
+```
+
+### 6.5 Tag Operations
+
+#### `get_all_tags`
+
+**Input Schema:**
+```json
+{
+  "sort_by": "name|count (default: count)",
+  "min_count": "number (default: 1)"
+}
+```
+
+#### `add_tags`, `remove_tags`, `rename_tag`
+
+Similar input patterns with tag manipulation logic.
+
+### 6.6 Git Operations
+
+#### `git_status`, `git_commit`, `git_pull`, `git_push`, `git_history`
+
+Standard Git operations exposed through MCP.
+
+### 6.7 Vault Operations
+
+#### `list_notes`, `get_vault_stats`, `get_vault_structure`, `find_orphaned_notes`, `get_most_linked`
+
+Vault-level analytics and navigation tools.
+
+### 6.8 Error Handling
+
+**Error Response Format:**
+```json
+{
+  "error": {
+    "code": "string",
+    "message": "string",
+    "details": "object"
+  }
+}
+```
+
+**Error Codes:**
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| NOTE_NOT_FOUND | 404 | Note doesn't exist |
+| NOTE_ALREADY_EXISTS | 409 | Note already exists |
+| INVALID_PATH | 400 | Invalid file path |
+| GIT_ERROR | 500 | Git operation failed |
+| PARSE_ERROR | 500 | Markdown parse error |
+
+---
+
+## 7. Data Model
+
+### 7.1 Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    VAULT ||--o{ NOTE : contains
+    NOTE ||--o| FRONTMATTER : has
+    NOTE ||--o{ TAG : has
+    NOTE ||--o{ WIKILINK : contains
+    NOTE ||--o{ NOTE : links-to
+    VAULT ||--|| GRAPH : maintains
+    
+    VAULT {
+        string root_path
+        int total_notes
+        datetime last_indexed
+    }
+    
+    NOTE {
+        string path PK
+        string content
+        datetime created_at
+        datetime modified_at
+        int word_count
+    }
+    
+    FRONTMATTER {
+        string note_path FK
+        json data
+    }
+    
+    TAG {
+        string name PK
+        int usage_count
+    }
+    
+    WIKILINK {
+        int id PK
+        string source_note FK
+        string target
+        string alias
+    }
+    
+    GRAPH {
+        string vault_path FK
+        map adjacency_list
+    }
+```
+
+### 7.2 Data Storage
+
+**Primary Storage:** Filesystem (Markdown files)
+
+**In-Memory Indices:**
+- Search Index: word → [notePaths]
+- Graph Index: note → [linkedNotes]
+- Tag Index: tag → [notePaths]
+
+**Cache Strategy:**
+- LRU cache for recently accessed notes
+- TTL: 5 minutes
+- Invalidation on file changes
+
+---
+
+## 8. Infrastructure Design
+
+### 8.1 Component Diagram
+
+```mermaid
+graph TB
+    subgraph "MCP Layer"
+        Server[MCP Server]
+        Tools[Tool Handlers]
+    end
+    
+    subgraph "Application"
+        UC[Use Cases]
+    end
+    
+    subgraph "Repository"
+        NoteRepo[Note Repository]
+        GitRepo[Git Repository]
+    end
+    
+    subgraph "Infrastructure"
+        FS[Filesystem]
+        GitImpl[Go-Git]
+        Parser[Goldmark Parser]
+        FMParser[Frontmatter Parser]
+        WLParser[WikiLink Parser]
+    end
+    
+    subgraph "Indices"
+        SearchIdx[Search Index]
+        GraphIdx[Graph Index]
+        TagIdx[Tag Index]
+    end
+    
+    Server --> Tools
+    Tools --> UC
+    UC --> NoteRepo
+    UC --> GitRepo
+    
+    NoteRepo --> FS
+    NoteRepo --> Parser
+    NoteRepo --> SearchIdx
+    
+    GitRepo --> GitImpl
+    
+    Parser --> FMParser
+    Parser --> WLParser
+    Parser --> GraphIdx
+    Parser --> TagIdx
+```
+
+### 8.2 Markdown Parser Architecture
+
+```mermaid
+flowchart LR
+    A[Raw Markdown] --> B[Goldmark Parser]
+    B --> C[AST]
+    C --> D[Frontmatter Extractor]
+    C --> E[WikiLink Extractor]
+    C --> F[Tag Extractor]
+    
+    D --> G[Frontmatter Object]
+    E --> H[WikiLink List]
+    F --> I[Tag List]
+    
+    G --> J[Note Entity]
+    H --> J
+    I --> J
+    C --> K[Content String]
+    K --> J
+```
+
+### 8.3 Git Integration Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant UseCase
+    participant GitRepo
+    participant GoGit
+    participant Filesystem
+    
+    Client->>UseCase: Update Note
+    UseCase->>GitRepo: Pull()
+    GitRepo->>GoGit: Pull latest
+    GoGit-->>GitRepo: OK
+    
+    UseCase->>Filesystem: Write file
+    Filesystem-->>UseCase: OK
+    
+    UseCase->>GitRepo: Commit(message, files)
+    GitRepo->>GoGit: Add files
+    GitRepo->>GoGit: Commit
+    GoGit-->>GitRepo: commit hash
+    
+    opt Auto-push enabled
+        GitRepo->>GoGit: Push
+    end
+    
+    GitRepo-->>UseCase: Success
+    UseCase-->>Client: Note updated
+```
+
+### 8.4 Index Building
+
+```mermaid
+flowchart TD
+    A[Vault Scan] --> B[Iterate Notes]
+    B --> C[Parse Note]
+    C --> D[Extract Text]
+    C --> E[Extract Links]
+    C --> F[Extract Tags]
+    
+    D --> G[Build Search Index]
+    E --> H[Build Graph Index]
+    F --> I[Build Tag Index]
+    
+    G --> J[In-Memory Indices]
+    H --> J
+    I --> J
+```
+
+---
+
+## 9. Security & Performance
+
+### 9.1 Security Considerations
+
+**Input Validation:**
+- Path traversal prevention (no `..`)
+- Extension validation (.md only)
+- Content sanitization
+- Size limits
+
+**Permission Model:**
+- Read-only mode support
+- Git operations opt-in
+- Rate limiting per client
+
+**Authentication:**
+- API key support (optional)
+- OAuth integration (future)
+
+### 9.2 Performance Targets
+
+| Operation | Target | Notes |
+|-----------|--------|-------|
+| Read Note | < 100ms | Including git pull |
+| Create Note | < 200ms | Including git commit |
+| Search | < 500ms | Vault with 5000 notes |
+| Get Backlinks | < 50ms | From graph index |
+| List Notes | < 100ms | Recursive listing |
+
+### 9.3 Performance Optimization
+
+**Caching:**
+- LRU cache for notes (size: 1000)
+- Index caching with TTL
+- Incremental index updates
+
+**Concurrency:**
+- Worker pools for batch operations
+- Parallel file reading
+- Non-blocking git operations
+
+**Memory Management:**
+- Streaming for large files
+- Lazy loading of note content
+- Periodic garbage collection
+
+---
+
+## 10. Testing Strategy
+
+### 10.1 Testing Pyramid
+
+```mermaid
+graph TD
+    A[E2E Tests 10%] --> B[Integration Tests 20%]
+    B --> C[Unit Tests 70%]
+    
+    style C fill:#90EE90
+    style B fill:#FFD700
+    style A fill:#FF6347
+```
+
+### 10.2 Test Coverage Goals
+
+| Layer | Coverage | Priority |
+|-------|----------|----------|
+| Domain | 90%+ | High |
+| Use Cases | 85%+ | High |
+| Repositories | 80%+ | Medium |
+| Adapters | 70%+ | Medium |
+| Infrastructure | 60%+ | Low |
+
+### 10.3 Test Types
+
+**Unit Tests:**
+- Domain entity logic
+- Use case orchestration (with mocks)
+- Value object validation
+
+**Integration Tests:**
+- Repository implementations
+- Index building
+- Git operations
+
+**E2E Tests:**
+- MCP tool invocations
+- Complete workflows
+- Error scenarios
+
+**Performance Tests:**
+- Search benchmarks
+- Large vault handling
+- Concurrent operations
+
+---
+
+## 11. Deployment
+
+### 11.1 Installation Methods
+
+**Binary Release:**
+- Pre-compiled binaries for Linux, macOS, Windows
+- Simple download and run
+
+**Go Install:**
+- `go install github.com/user/obsidian-mcp-server@latest`
+
+**Docker:**
+- Official Docker image
+- docker-compose support
+
+### 11.2 Configuration
+
+**Environment Variables:**
+- `VAULT_PATH` - Path to Obsidian vault
+- `GIT_AUTO_PUSH` - Enable auto-push
+- `LOG_LEVEL` - Logging level
+
+**Config File (YAML):**
+```yaml
+server:
+  name: obsidian-mcp
+  transport: stdio
+
+vault:
+  path: /path/to/vault
+  exclude_paths:
+    - .obsidian/
+    - .git/
+
+git:
+  enabled: true
+  auto_pull: true
+  auto_push: false
+
+logging:
+  level: info
+```
+
+### 11.3 Monitoring
+
+**Health Checks:**
+- Vault accessibility
+- Git repository status
+- Index health
+
+**Metrics:**
+- Request count
+- Request duration
+- Error rate
+- Cache hit rate
+
+**Logging:**
+- Structured JSON logging
+- Log levels: debug, info, warn, error
+- Request/response logging
+
+---
+
+## 12. Implementation Roadmap
+
+### 12.1 Development Phases
+
+```mermaid
+gantt
+    title Implementation Timeline
+    dateFormat YYYY-MM-DD
+    section Phase 1
+    Domain Model           :2025-01-20, 7d
+    Repository Interfaces  :2025-01-27, 5d
+    section Phase 2
+    Infrastructure         :2025-02-01, 14d
+    Use Cases             :2025-02-08, 14d
+    section Phase 3
+    MCP Adapter           :2025-02-15, 10d
+    Testing               :2025-02-25, 7d
+    section Phase 4
+    Documentation         :2025-03-04, 5d
+    Release v1.0          :2025-03-09, 1d
+```
+
+### 12.2 Phase 1: Foundation (Week 1-2)
+
+**Goals:**
+- Domain model
+- Repository interfaces
+- Project structure
+
+**Deliverables:**
+- [ ] Domain entities (Note, Vault, Tag, WikiLink, Frontmatter)
+- [ ] Repository interfaces
+- [ ] Domain tests (90%+ coverage)
+- [ ] Project setup
+
+### 12.3 Phase 2: Core Functionality (Week 3-6)
+
+**Goals:**
+- Infrastructure implementations
+- Core use cases
+- Index building
+
+**Deliverables:**
+- [ ] Filesystem repository
+- [ ] Git repository
+- [ ] Markdown parser
+- [ ] Search/Graph indices
+- [ ] Note CRUD use cases
+- [ ] Search use cases
+- [ ] Link use cases
+
+### 12.4 Phase 3: MCP Integration (Week 7-9)
+
+**Goals:**
+- MCP adapter layer
+- Tool implementations
+- End-to-end testing
+
+**Deliverables:**
+- [ ] MCP server setup
+- [ ] 45+ MCP tools
+- [ ] MCP resources
+- [ ] MCP prompts
+- [ ] E2E tests
+- [ ] Performance testing
+
+**Tasks:**
+1. Setup MCP server with go-sdk
+2. Implement file operation tools (5)
+3. Implement search tools (3)
+4. Implement link tools (5)
+5. Implement tag/frontmatter tools (7)
+6. Implement git tools (5)
+7. Implement vault tools (5)
+8. Implement template tools (3)
+9. Write E2E tests
+10. Performance benchmarks
+
+### 12.5 Phase 4: Polish & Release (Week 10-11)
+
+**Goals:**
+- Documentation
+- Examples
+- Release preparation
+
+**Deliverables:**
+- [ ] README with examples
+- [ ] API documentation
+- [ ] Configuration guide
+- [ ] Binary releases (Linux, macOS, Windows)
+- [ ] Docker image
+- [ ] GitHub releases
+
+**Tasks:**
+1. Write comprehensive README
+2. Create example configurations
+3. Build for multiple platforms
+4. Create Docker image
+5. Setup GitHub releases
+6. Publish v1.0.0
+
+### 12.6 Post-Release Roadmap
+
+**v1.1.0 (Future):**
+- Semantic search with embeddings
+- Real-time file watching
+- Web UI for monitoring
+- Batch operations optimization
+- Plugin system
+
+**v1.2.0 (Future):**
+- Custom parsers
+- Advanced git operations (branches, merges)
+- Vault backup/restore
+- Performance improvements
+
+**v2.0.0 (Future):**
+- Multi-vault support
+- Collaboration features
+- Cloud sync integration
+- Advanced analytics
+
+---
+
+## Appendix A: Repository Interfaces
+
+### A.1 Core Interfaces
+
+**NoteRepository:**
+- Get(ctx, path) → Note
+- Create(ctx, note) → error
+- Update(ctx, note) → error
+- Delete(ctx, path) → error
+- List(ctx, pattern, recursive) → []Note
+- Exists(ctx, path) → bool
+
+**GitRepository:**
+- Status(ctx) → GitStatus
+- Pull(ctx) → error
+- Push(ctx) → error
+- Commit(ctx, message, files) → error
+- Log(ctx, path, limit) → []Commit
+
+**VaultRepository:**
+- GetStats(ctx) → VaultStats
+- GetStructure(ctx, maxDepth) → VaultStructure
+- FindOrphaned(ctx, excludePaths) → []string
+
+**SearchIndex:**
+- Index(note) → error
+- Remove(path) → error
+- Search(query, maxResults) → []string
+- Rebuild(notes) → error
+
+**GraphIndex:**
+- AddNote(note) → error
+- RemoveNote(path) → error
+- GetBacklinks(path) → []string
+- GetOutlinks(path) → []string
+- GetConnected(path, depth) → []string
+
+**TagIndex:**
+- AddNote(note) → error
+- RemoveNote(path) → error
+- GetAllTags() → []TagInfo
+- GetNotesWithTag(tag) → []string
+- GetNotesWithTags(tags, mode) → []string
+
+### A.2 Data Types
+
+**GitStatus:**
+- Branch: string
+- Modified: []string
+- Untracked: []string
+- Staged: []string
+- Ahead: int
+- Behind: int
+
+**Commit:**
+- Hash: string
+- Author: string
+- Date: time.Time
+- Message: string
+- Files: []string
+
+**VaultStats:**
+- TotalNotes: int
+- TotalWords: int
+- TotalLinks: int
+- TotalTags: int
+- AvgNoteLength: int
+- MostLinked: []MostLinkedNote
+- OrphanedNotes: int
+
+**VaultStructure:**
+- Name: string
+- Path: string
+- Type: string (file/directory)
+- Children: []VaultStructure
+
+**TagInfo:**
+- Name: string
+- Count: int
+- Nested: bool
+
+---
+
+## Appendix B: Configuration Schema
+
+### B.1 Complete Configuration
+
+```yaml
+server:
+  name: obsidian-mcp
+  version: 1.0.0
+  transport: stdio  # or "sse"
+
+vault:
+  path: /path/to/vault
+  exclude_paths:
+    - .obsidian/
+    - .git/
+    - .trash/
+    - Archive/
+  watch_changes: true
+
+git:
+  enabled: true
+  auto_pull: true
+  auto_push: false
+  auto_commit: true
+  commit_prefix: "[MCP]"
+  remote: origin
+  branch: main
+
+index:
+  build_on_startup: true
+  rebuild_interval: 5m
+  max_notes_in_memory: 10000
+
+search:
+  max_results: 50
+  context_lines: 2
+  case_sensitive: false
+
+cache:
+  enabled: true
+  max_size: 1000
+  ttl: 5m
+
+logging:
+  level: info  # debug, info, warn, error
+  format: text  # text or json
+  file: /var/log/obsidian-mcp.log
+
+performance:
+  max_concurrent_operations: 10
+  read_timeout: 30s
+  write_timeout: 30s
+
+security:
+  rate_limit:
+    enabled: true
+    requests_per_second: 10
+    burst: 20
+  max_file_size: 10MB
+```
+
+### B.2 Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| VAULT_PATH | Path to Obsidian vault | required |
+| CONFIG_PATH | Path to config file | config.yaml |
+| LOG_LEVEL | Logging level | info |
+| GIT_ENABLED | Enable git operations | true |
+| GIT_AUTO_PUSH | Auto-push changes | false |
+| CACHE_ENABLED | Enable caching | true |
+
+---
+
+## Appendix C: Error Codes Reference
+
+### C.1 Domain Errors
+
+| Code | Message | HTTP Status |
+|------|---------|-------------|
+| ERR_NOTE_NOT_FOUND | Note not found | 404 |
+| ERR_NOTE_EXISTS | Note already exists | 409 |
+| ERR_INVALID_PATH | Invalid note path | 400 |
+| ERR_EMPTY_CONTENT | Content cannot be empty | 400 |
+| ERR_INVALID_TAG | Invalid tag format | 400 |
+| ERR_TAG_EXISTS | Tag already exists | 409 |
+| ERR_CIRCULAR_LINK | Circular link detected | 400 |
+
+### C.2 Infrastructure Errors
+
+| Code | Message | HTTP Status |
+|------|---------|-------------|
+| ERR_GIT_PULL | Git pull failed | 500 |
+| ERR_GIT_PUSH | Git push failed | 500 |
+| ERR_GIT_COMMIT | Git commit failed | 500 |
+| ERR_PARSE | Markdown parse error | 500 |
+| ERR_IO | File I/O error | 500 |
+| ERR_PERMISSION | Permission denied | 403 |
+
+### C.3 Application Errors
+
+| Code | Message | HTTP Status |
+|------|---------|-------------|
+| ERR_INVALID_INPUT | Invalid input parameters | 400 |
+| ERR_RATE_LIMIT | Rate limit exceeded | 429 |
+| ERR_TIMEOUT | Operation timeout | 408 |
+| ERR_INTERNAL | Internal server error | 500 |
+
+---
+
+## Appendix D: Performance Benchmarks
+
+### D.1 Target Performance Metrics
+
+**Vault Sizes:**
+- Small: 100 notes, ~200KB
+- Medium: 1,000 notes, ~2MB
+- Large: 5,000 notes, ~10MB
+- XL: 10,000 notes, ~20MB
+
+**Operation Latencies (Medium Vault):**
+
+| Operation | P50 | P95 | P99 |
+|-----------|-----|-----|-----|
+| Read Note | 20ms | 50ms | 100ms |
+| Create Note | 50ms | 150ms | 200ms |
+| Update Note | 40ms | 120ms | 180ms |
+| Delete Note | 30ms | 100ms | 150ms |
+| Search (full-text) | 100ms | 300ms | 500ms |
+| Get Backlinks | 10ms | 30ms | 50ms |
+| Get Outlinks | 5ms | 15ms | 30ms |
+| List Notes (100) | 20ms | 60ms | 100ms |
+| Git Commit | 200ms | 500ms | 1s |
+| Git Pull | 300ms | 1s | 2s |
+
+**Memory Usage:**
+
+| Vault Size | Base Memory | Index Memory | Total |
+|------------|-------------|--------------|-------|
+| Small | 20MB | 5MB | 25MB |
+| Medium | 30MB | 30MB | 60MB |
+| Large | 50MB | 150MB | 200MB |
+| XL | 80MB | 300MB | 380MB |
+
+### D.2 Scalability Limits
+
+**Recommended Limits:**
+- Max notes: 10,000
+- Max note size: 10MB
+- Max concurrent operations: 100
+- Max search results: 1,000
+
+**Hard Limits:**
+- Max notes: 50,000 (performance degrades)
+- Max note size: 50MB (memory issues)
+- Max vault size: 1GB
+
+---
+
+## Appendix E: MCP Tools Complete List
+
+### E.1 File Operations (5)
+1. read_note
+2. create_note
+3. update_note
+4. delete_note
+5. rename_note
+
+### E.2 Directory Operations (3)
+6. list_notes
+7. create_directory
+8. get_vault_structure
+
+### E.3 Search Operations (3)
+9. search_content
+10. search_by_tags
+11. search_by_frontmatter
+
+### E.4 Link Operations (5)
+12. get_backlinks
+13. get_outlinks
+14. get_graph
+15. find_broken_links
+16. update_links
+
+### E.5 Tag Operations (4)
+17. get_all_tags
+18. add_tags
+19. remove_tags
+20. rename_tag
+
+### E.6 Frontmatter Operations (3)
+21. get_frontmatter
+22. update_frontmatter
+23. bulk_update_frontmatter
+
+### E.7 Git Operations (5)
+24. git_status
+25. git_commit
+26. git_pull
+27. git_push
+28. git_history
+
+### E.8 Vault Operations (5)
+29. get_vault_stats
+30. find_orphaned_notes
+31. get_most_linked
+
+### E.9 Template Operations (3)
+32. create_from_template
+33. list_templates
+
+### E.10 Daily Notes (3)
+34. get_daily_note
+35. create_daily_note
+36. append_to_daily_note
+
+### E.11 Batch Operations (3)
+37. batch_operation
+
+### E.12 Analytics (2)
+38. get_note_stats
+
+**Total: 38 Core Tools** (expandable to 45+ with variants)
+
+---
+
+## Appendix F: Development Guidelines
+
+### F.1 Code Style
+
+**General Principles:**
+- Follow Go idioms and conventions
+- Use meaningful variable names
+- Keep functions small and focused
+- Write self-documenting code
+- Add comments for complex logic
+
+**Naming Conventions:**
+- Interfaces: `XxxRepository`, `XxxIndex`
+- Implementations: `XxxRepositoryImpl`
+- Use Cases: `XxxUseCase`
+- DTOs: `XxxDTO`
+- Errors: `ErrXxx`
+
+**Package Organization:**
+- One concept per package
+- Avoid circular dependencies
+- Keep packages small and cohesive
+
+### F.2 Testing Guidelines
+
+**Test Structure:**
+- Arrange-Act-Assert pattern
+- Use table-driven tests
+- Mock external dependencies
+- Test error paths
+
+**Test Naming:**
+- `TestXxx_Yyy` for methods
+- `TestXxx_Yyy_Error` for error cases
+- Descriptive test case names
+
+**Coverage:**
+- All public functions must have tests
+- Test edge cases and error paths
+- Integration tests for critical paths
+
+### F.3 Git Commit Messages
+
+**Format:**
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- feat: New feature
+- fix: Bug fix
+- docs: Documentation
+- refactor: Code refactoring
+- test: Tests
+- chore: Maintenance
+
+**Examples:**
+```
+feat(domain): add Note entity with validation
+
+Implements Note entity with path, content, and metadata.
+Includes validation for path format and content.
+
+Closes #123
+```
+
+### F.4 Pull Request Process
+
+**Requirements:**
+- [ ] All tests pass
+- [ ] Code coverage > 80%
+- [ ] Linter passes
+- [ ] Documentation updated
+- [ ] CHANGELOG updated
+
+**Review Checklist:**
+- [ ] Code follows guidelines
+- [ ] Tests are comprehensive
+- [ ] No unnecessary complexity
+- [ ] Error handling is correct
+- [ ] Performance considered
+
+---
+
+## Appendix G: Troubleshooting Guide
+
+### G.1 Common Issues
+
+**Issue: Git pull fails**
+- Check network connectivity
+- Verify git credentials
+- Check remote repository access
+- Solution: Configure SSH keys or HTTPS credentials
+
+**Issue: Note not found**
+- Verify vault path is correct
+- Check file exists in filesystem
+- Verify path is relative to vault root
+- Solution: Use absolute path or check vault configuration
+
+**Issue: Parse error**
+- Check frontmatter YAML syntax
+- Verify markdown is valid
+- Check for special characters
+- Solution: Validate markdown with external tool
+
+**Issue: Out of memory**
+- Check vault size
+- Verify index size
+- Monitor memory usage
+- Solution: Increase memory limit or reduce cache size
+
+**Issue: Slow search**
+- Check index status
+- Verify vault size
+- Monitor query complexity
+- Solution: Rebuild index or optimize query
+
+### G.2 Debug Mode
+
+**Enable debug logging:**
+```bash
+OBSIDIAN_MCP_LOG_LEVEL=debug obsidian-mcp
+```
+
+**Enable profiling:**
+```bash
+OBSIDIAN_MCP_PROFILE=true obsidian-mcp
+# Access: http://localhost:6060/debug/pprof/
+```
+
+**Verbose git operations:**
+```yaml
+git:
+  verbose: true
+```
+
+### G.3 Health Checks
+
+**Check vault accessibility:**
+```bash
+obsidian-mcp --health
+```
+
+**Check git status:**
+```bash
+obsidian-mcp --git-status
+```
+
+**Check index status:**
+```bash
+obsidian-mcp --index-status
+```
+
+---
+
+## Appendix H: Glossary
+
+**Terms:**
+
+- **MCP (Model Context Protocol):** Open protocol for connecting AI to data sources
+- **Obsidian:** Markdown-based note-taking application
+- **Vault:** Obsidian's term for a collection of notes
+- **WikiLink:** Internal link format `[[Note Name]]`
+- **Frontmatter:** YAML metadata at top of markdown file
+- **Backlink:** Link pointing to a note from another note
+- **Outlink:** Link from a note to another note
+- **Graph:** Network of interconnected notes
+- **Use Case:** Single unit of business logic
+- **Repository:** Interface for data persistence
+- **Entity:** Domain object with identity
+- **Value Object:** Domain object without identity
+- **DTO:** Data Transfer Object for API layer
+
+**Acronyms:**
+
+- **CRUD:** Create, Read, Update, Delete
+- **API:** Application Programming Interface
+- **SDK:** Software Development Kit
+- **CLI:** Command Line Interface
+- **CI/CD:** Continuous Integration/Continuous Deployment
+- **TDD:** Test-Driven Development
+- **DDD:** Domain-Driven Design
+- **VO:** Value Object
+- **UC:** Use Case
+- **E2E:** End-to-End
+
+---
+
+## Document Metadata
+
+**Document Version:** 1.0.0  
+**Last Updated:** 2025-10-07  
+**Status:** Complete - Ready for Implementation  
+**Review Status:** Draft - Awaiting Technical Review
+
+**Authors:**
+- Architecture Team
+- Technical Lead
+
+**Reviewers:**
+- [ ] Technical Lead
+- [ ] Senior Developer
+- [ ] Security Team
+- [ ] DevOps Team
+
+**Approvals:**
+- [ ] Project Manager
+- [ ] Technical Lead
+- [ ] Product Owner
+
+**Change Log:**
+- 2025-10-07: Initial document creation
+
+**Related Documents:**
+- API Specification (to be created)
+- Architecture Decision Records (to be created)
+- User Guide (to be created)
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Foundation ✅
+- [ ] Domain entities (Note, Vault, Tag, WikiLink, Frontmatter)
+- [ ] Repository interfaces
+- [ ] Domain unit tests (90%+ coverage)
+- [ ] Project structure setup
+- [ ] CI/CD pipeline
+
+### Phase 2: Core Functionality ✅
+- [ ] Filesystem repository
+- [ ] Git repository
+- [ ] Markdown parser (goldmark)
+- [ ] Search index
+- [ ] Graph index
+- [ ] Tag index
+- [ ] All use cases (30+)
+- [ ] Integration tests
+
+### Phase 3: MCP Integration ✅
+- [ ] MCP server setup
+- [ ] 45+ MCP tools
+- [ ] MCP resources
+- [ ] MCP prompts
+- [ ] E2E tests
+- [ ] Performance benchmarks
+
+### Phase 4: Release ✅
+- [ ] Documentation
+- [ ] Binary builds
+- [ ] Docker image
+- [ ] Example configs
+- [ ] GitHub release
+
+---
+
+**End of Design Document**
+
+This document provides complete specifications for the Obsidian MCP Server implementation. All development should follow the architecture, patterns, and guidelines defined herein.
+
+For questions or clarifications, contact the architecture team.