知识库管理系统

graph TB
    subgraph "Clients"
        REST[REST API Clients]
        MCP[MCP/AI Agents]
    end

    subgraph "API Layer"
        FastAPI[FastAPI Routes]
        MCPTools[MCP Tools]
    end

    subgraph "Application Layer"
        UC[Use Cases]
        DTO[DTOs]
    end

    subgraph "Domain Layer"
        E[Entities]
        VO[Value Objects]
        DS[Domain Services]
    end

    subgraph "Infrastructure"
        PG[(PostgreSQL)]
        PGV[(pgvector)]
        AGE[(Apache AGE)]
        OAI[OpenAI API]
    end

    REST --> FastAPI
    MCP --> MCPTools
    FastAPI --> UC
    MCPTools --> UC
    UC --> E
    UC --> DS
    DS --> VO
    UC --> PG
    UC --> PGV
    UC --> AGE
    UC --> OAI

cd obsidian_vault_server

# Install dependencies (using uv)
just install-dev

# Or manually
uv sync --dev

# Start PostgreSQL with pgvector + Apache AGE
just infra-up

# Or with docker-compose
docker-compose up -d

DATABASE_URL=postgresql+asyncpg://obsidian:obsidian@localhost:5433/obsidian
OPENAI_API_KEY=your-openai-api-key
JWT_SECRET=your-secret-key-min-32-chars
JWT_ISSUER=obsidian-vault-server
MAX_UPLOAD_SIZE_MB=100
ENVIRONMENT=development
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
RATE_LIMIT_ENABLED=true

just migrate

# Or manually
uv run alembic upgrade head

just dev

# Or manually
uv run uvicorn app.main:app --reload --port 8001

?filter[column]=value          # Equality
?filter[column][gt]=value      # Greater than
?filter[column][lt]=value      # Less than
?filter[column][like]=pattern  # LIKE match
?sort=column&order=asc|desc    # Sorting
?limit=50&offset=0             # Pagination
?q=search_term                 # Full-text search

TABLE name, email FROM Contacts WHERE status = 'active' SORT name ASC LIMIT 10

# Project Notes

See all contacts: [[table:Contacts]]
Specific contact: [[row:Contacts/550e8400-e29b-41d4-a716-446655440000]]

## Embedded Query
```dataview
TABLE name, email FROM Contacts WHERE status = "active"

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql+asyncpg://...` | PostgreSQL connection string (async) |
| `OPENAI_API_KEY` | - | OpenAI API key for embeddings (required for semantic search) |
| `JWT_SECRET` | `change-me-in-production` | Secret key for JWT tokens (change in production) |
| `JWT_ALGORITHM` | `HS256` | JWT signing algorithm |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `60` | Access token expiry in minutes |
| `REFRESH_TOKEN_EXPIRE_DAYS` | `7` | Refresh token expiry in days |
| `EMBEDDING_MODEL` | `text-embedding-ada-002` | OpenAI embedding model |
| `EMBEDDING_DIMENSIONS` | `1536` | Embedding vector dimensions |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `DEBUG` | `False` | Enable debug mode |
| `STORAGE_PATH` | `./storage` | Path for file storage |
| `RATE_LIMIT_ENABLED` | `True` | Enable rate limiting |
| `CHUNK_SIZE` | `500` | Tokens per embedding chunk |
| `CHUNK_OVERLAP` | `50` | Token overlap between chunks |

## MCP Tools

The server exposes MCP tools for AI agent integration via the Model Context Protocol.

```mermaid
graph LR
    subgraph "AI Agent"
        LLM[LLM]
    end

    subgraph "MCP Server"
        Tools[MCP Tools]
    end

    subgraph "Capabilities"
        Docs[Documents]
        Search[Search]
        Graph[Graph]
        Tables[Tables]
    end

    LLM <-->|MCP Protocol| Tools
    Tools --> Docs
    Tools --> Search
    Tools --> Graph
    Tools --> Tables

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "uv",
      "args": ["run", "python", "-m", "app.mcp_server"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://...",
        "JWT_SECRET": "your-secret"
      }
    }
  }
}

# Run tests
just test

# Run tests with coverage
just test-cov

# Run linting
just lint

# Run type checking
just typecheck

# Format code
just format

app/
├── domain/           # Pure Python - no external dependencies
│   ├── entities/     # Business objects (Vault, Document, Tag, etc.)
│   ├── value_objects/# Immutable values (WikiLink, Frontmatter, etc.)
│   ├── services/     # Domain logic (LinkResolver, TagParser, etc.)
│   └── exceptions.py # Domain exceptions
│
├── application/      # Use cases and ports
│   ├── interfaces/   # Port definitions (repositories, providers)
│   ├── use_cases/    # Application logic
│   └── dto/          # Data transfer objects
│
├── infrastructure/   # External adapters
│   ├── database/     # PostgreSQL repositories
│   ├── pgvector/     # Vector search adapter
│   ├── age/          # Apache AGE graph adapter
│   └── embedding/    # OpenAI embedding adapter
│
└── api/              # HTTP interface
    ├── routes/       # FastAPI endpoints
    └── schemas/      # Request/response models

erDiagram
    users ||--o{ vaults : owns
    vaults ||--o{ documents : contains
    vaults ||--o{ folders : contains
    vaults ||--o{ tags : contains
    vaults ||--o{ data_tables : contains
    documents ||--o{ document_links : has
    documents ||--o{ document_tags : has
    documents ||--o{ embedding_chunks : has
    documents ||--o{ document_table_links : references
    data_tables ||--o{ table_rows : contains
    data_tables ||--o{ table_relationships : has
    data_tables ||--o{ document_table_links : referenced_by

    users {
        uuid id PK
        string email UK
        string password_hash
        string display_name
        boolean is_active
    }

    vaults {
        uuid id PK
        uuid user_id FK
        string name
        string slug UK
        int document_count
    }

    documents {
        uuid id PK
        uuid vault_id FK
        uuid folder_id FK
        string title
        string path
        text content
        jsonb frontmatter
    }

    data_tables {
        uuid id PK
        uuid vault_id FK
        string name
        string slug
        jsonb schema
        int row_count
    }

    table_rows {
        uuid id PK
        uuid table_id FK
        uuid vault_id FK
        jsonb data
    }

# Run all tests
just test

# Run with coverage
just test-cov

# Run specific test suite
uv run pytest tests/unit -v
uv run pytest tests/api -v
uv run pytest tests/bdd -v