# Synapse Mimarisi

Synapse, Fastify, FTS5 ile PostgreSQL ve anlamsal arama için isteğe bağlı bir gömme hizmeti üzerine inşa edilmiş çok kiracılı bir bellek API'sidir.

## Üst Düzey Mimari

```
┌──────────────────────────────────────────────────────────┐
│                       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 │
       └─────────────┘ └─────────────┘ └─────────────┘
```

## Çekirdek Bileşenler

### 1. Synapse API (Fastify)

Ana HTTP sunucusu. Şunları ele alır:

- REST uç noktaları (`/memory`, `/chat`, `/mind/tasks` vb.)
- Kimlik doğrulama (ajanlar için Mind Key, insanlar için JWT)
- Hız sınırlaması (yalnızca `?key=` kimlik doğrulaması)
- Statik dosya sunumu (`/human`, `/docs` vb. web arayüzü)
- Webhook dağıtımı

Performans için **Fastify 5** ile inşa edilmiştir. Üretimde 12800 portunda çalışır.

### 2. FTS5 ile PostgreSQL

Birincil veri deposu. Tam metin arama için FTS5 uzantısına sahip PostgreSQL kullanır.

**Önemli tablolar:**

| Tablo | Amaç |
|-------|---------|
| `users` | Kullanıcı hesapları |
| `minds` | Mind kapsamları (her birinin bir Mind Key'i vardır) |
| `memories` | FTS5 sanal tablosuyla bellek kayıtları |
| `tasks` | Görev yönetimi |
| `chat_messages` | Sohbet geçmişi |
| `scripts` | Kalıcı betikler |
| `webhooks` | Webhook kayıtları |
| `cron_jobs` | Zamanlanmış görevler |
| `variables` | Anahtar-değer deposu |
| `audit_log` | Denetim izi |

**FTS5**, tüm bellek içeriğinde milisaniyenin altında tam metin arama sağlar. Detaylar için bkz. [FTS5 Arama](/docs/concepts/fts5-search).

### 3. Gömme Hizmeti (İsteğe Bağlı)

Anlamsal arama için Synapse, bellek içeriğinin vektör gömmelerini üretir. Bunlar belleklerle birlikte saklanır ve benzerlik araması için kullanılır.

- Sağlayıcı: yapılandırılabilir (OpenAI, yerel model vb.)
- `memories` tablosunda `vector` sütunu olarak saklanır
- `/memory/semantic-search` uç noktası tarafından kullanılır
- Bkz. [Anlamsal Arama](/docs/concepts/semantic-search)

### 4. MCP Sunucusu (Ayrı Hizmet)

Synapse MCP sunucusu ayrı bir süreç (port 13100) olarak çalışır. Şunları yapar:

- Model Context Protocol üzerinden 79 araç sunar
- stdio, HTTP/SSE ve WebSocket taşıyıcılarını destekler
- MCP araç çağrılarını Synapse API çağrılarına çevirir
- Çok kiracılı: oturum başına bir Mind Key

### 5. Browser Proxy (Ayrı Hizmet)

Tarayıcı otomasyonu için, 13000 portunda Playwright tabanlı ayrı bir hizmet çalışır. MCP sunucusu bunu `browser_*` araçları için çağırabilir.

### 6. SSH Proxy (Ayrı Hizmet)

SSH tabanlı uzak komutlar için, 12900 portunda ayrı bir hizmet çalışır.

## Çok Kiracılılık Modeli

```
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)
      └── ...
```

Her mind tamamen izoledir. Mind Key'ler tam olarak bir mind'e erişim sağlar. JWT'ler kullanıcı hesabına erişim sağlar (mind'leri yönetmek için).

Detaylar için bkz. [Çok Kiracılılık](/docs/concepts/multi-tenancy).

## İstek Akışı

### Bellek Saklama İsteği

```
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" }
```

### Bellek Arama İsteği

```
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
```

## Dağıtım

Synapse bir Docker konteyneri olarak dağıtılır. Bkz. `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=...
```

## Performans Karakteristikleri

| İşlem | Gecikme | Verim |
|-----------|---------|------------|
| Bellek saklama | ~5ms | 1000+ istek/sn |
| Bellek geri çağırma | ~20ms | 500 istek/sn |
| FTS5 arama | ~10ms | 800 istek/sn |
| Anlamsal arama | ~50ms | 200 istek/sn |
| Sohbet poll | ~5ms | 2000 istek/sn |

## Sonraki Adımlar

- [Bellek Modeli](/docs/concepts/memory-model)
- [Çok Kiracılılık](/docs/concepts/multi-tenancy)
- [FTS5 Arama](/docs/concepts/fts5-search)