# Synapse アーキテクチャ

Synapse は Fastify、FTS5 搭載 PostgreSQL、セマンティック検索用のオプションの埋め込みサービスで構築されたマルチテナントメモリ API です。

## 全体アーキテクチャ

```
┌──────────────────────────────────────────────────────────┐
│                       Clients                            │
├──────────────┬──────────────┬──────────────┬─────────────┤
│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │
│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │    Synapse API (Fastify)      │
              │    port 12800                 │
              │    - REST endpoints           │
              │    - Auth (Mind Key / JWT)    │
              │    - Rate limiting            │
              │    - Static file serving      │
              └───────────────┬───────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │
       │ + FTS5      │ │ Service     │ │ (separate)  │
       │             │ │ (optional)  │ │ port 13100  │
       │ - memories  │ │             │ │             │
       │ - tasks     │ │ - generate  │ │ - 79 tools  │
       │ - chat      │ │   embeddings│ │ - stdio/SSE │
       │ - scripts   │ │             │ │ - WebSocket │
       └─────────────┘ └─────────────┘ └─────────────┘
```

## コアコンポーネント

### 1. Synapse API（Fastify）

メインの HTTP サーバーです。以下を処理します。

- REST エンドポイント（`/memory`、`/chat`、`/mind/tasks` など）
- 認証（エージェントは Mind Key、人間は JWT）
- レート制限（`?key=` 認証のみ）
- 静的ファイル配信（`/human`、`/docs` などの Web UI）
- Webhook ディスパッチ

パフォーマンス重視で **Fastify 5** により構築されています。本番環境ではポート 12800 で動作します。

### 2. FTS5 搭載 PostgreSQL

プライマリデータストアです。フルテキスト検索用に FTS5 拡張を備えた PostgreSQL を使用します。

**主なテーブル：**

| テーブル | 目的 |
|-------|---------|
| `users` | ユーザーアカウント |
| `minds` | Mind スコープ（各々が Mind Key を持つ） |
| `memories` | FTS5 仮想テーブル付きのメモリレコード |
| `tasks` | タスク管理 |
| `chat_messages` | チャット履歴 |
| `scripts` | 永続スクリプト |
| `webhooks` | Webhook 登録 |
| `cron_jobs` | スケジュールタスク |
| `variables` | キーバリューストア |
| `audit_log` | 監査トレイル |

**FTS5** により、全メモリコンテンツに対するサブミリ秒のフルテキスト検索が可能です。詳しくは [FTS5 Search](/docs/concepts/fts5-search) を参照。

### 3. 埋め込みサービス（オプション）

セマンティック検索のため、Synapse はメモリコンテンツのベクトル埋め込みを生成します。これらはメモリと一緒に保存され、類似度検索に使用されます。

- プロバイダー：構成可能（OpenAI、ローカルモデルなど）
- `memories` テーブルの `vector` カラムとして保存
- `/memory/semantic-search` エンドポイントで使用
- [Semantic Search](/docs/concepts/semantic-search) を参照

### 4. MCP サーバー（別サービス）

Synapse MCP サーバーは別プロセス（ポート 13100）として動作します。以下を行います。

- Model Context Protocol 経由で 79 のツールを公開
- stdio、HTTP/SSE、WebSocket トランスポートをサポート
- MCP ツール呼び出しを Synapse API 呼び出しに変換
- マルチテナント：セッションごとに 1 つの Mind Key

### 5. Browser Proxy（別サービス）

ブラウザ自動化用に、Playwright ベースの別サービスがポート 13000 で動作します。MCP サーバーは `browser_*` ツールのためにこれを呼び出せます。

### 6. SSH Proxy（別サービス）

SSH ベースのリモートコマンド用に、別サービスがポート 12900 で動作します。

## マルチテナントモデル

```
User Account (email + password)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── Memories
  │   ├── Tasks
  │   ├── Chat
  │   └── Scripts
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (isolated from Mind 1)
  │
  └── Mind 3 (Mind Key 3)
      └── ...
```

各 mind は完全に分離されています。Mind Key は厳密に 1 つの mind へのアクセスを許可します。JWT はユーザーアカウントへのアクセスを許可します（mind 管理用）。

詳しくは [Multi-Tenancy](/docs/concepts/multi-tenancy) を参照。

## リクエストフロー

### メモリ保存リクエスト

```
1. Client sends POST /memory with Authorization: Bearer mk_xxx
2. Fastify receives request
3. Auth middleware validates Mind Key, attaches mind_id to request
4. Memory route handler:
   a. Validate JSON body (zod schema)
   b. Insert into memories table
   c. Update FTS5 index
   d. (Async) Generate embedding if embeddings enabled
   e. Trigger webhooks for memory.store event
5. Return { id, status: "stored" }
```

### メモリ検索リクエスト

```
1. Client sends GET /memory/search?q=docker
2. Auth middleware validates Mind Key
3. Memory route handler:
   a. Parse query (FTS5 syntax)
   b. Execute FTS5 MATCH against memories table
   c. Filter by mind_id (tenant isolation)
   d. Rank by relevance
   e. Return results
```

## デプロイ

Synapse は Docker コンテナとしてデプロイされます。`docker-compose.yml` を参照：

```yaml
services:
  synapse:
    image: registry.gitlab.com/schaefer-services/synapse:latest
    ports:
      - "12800:12800"
    environment:
      - DATABASE_URL=postgres://...
      - JWT_SECRET=...
      - SYNAPSE_HOST=0.0.0.0
      - SYNAPSE_PORT=12800
    depends_on:
      - postgres
  
  postgres:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=synapse
      - POSTGRES_PASSWORD=...
```

## パフォーマンス特性

| 操作 | レイテンシ | スループット |
|-----------|---------|------------|
| メモリ保存 | ~5ms | 1000+ req/s |
| メモリ再取得 | ~20ms | 500 req/s |
| FTS5 検索 | ~10ms | 800 req/s |
| セマンティック検索 | ~50ms | 200 req/s |
| チャットポーリング | ~5ms | 2000 req/s |

## 次のステップ

- [Memory Model](/docs/concepts/memory-model)
- [Multi-Tenancy](/docs/concepts/multi-tenancy)
- [FTS5 Search](/docs/concepts/fts5-search)