{"title":"Synapse Mimarisi","slug":"architecture","category":"concepts","summary":"Synapse nasıl inşa edilmiştir — Fastify, PostgreSQL, FTS5, gömmeler, MCP sunucusu.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":434,"read_minutes":2,"lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# Synapse Mimarisi\n\nSynapse, 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.\n\n## Üst Düzey Mimari\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ Clients │\n├──────────────┬──────────────┬──────────────┬─────────────┤\n│ LLM Agents │ Web Browsers│ MCP Clients │ Webhooks │\n│ (curl/SDK) │ (humans) │ (Claude/etc) │ (external) │\n└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘\n │ │ │ │\n └──────────────┴──────────────┴──────────────┘\n │\n ▼\n ┌───────────────────────────────┐\n │ Synapse API (Fastify) │\n │ port 12800 │\n │ - REST endpoints │\n │ - Auth (Mind Key / JWT) │\n │ - Rate limiting │\n │ - Static file serving │\n └───────────────┬───────────────┘\n │\n ┌───────────────┼───────────────┐\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Embeddings │ │ MCP Server │\n │ + FTS5 │ │ Service │ │ (separate) │\n │ │ │ (optional) │ │ port 13100 │\n │ - memories │ │ │ │ │\n │ - tasks │ │ - generate │ │ - 79 tools │\n │ - chat │ │ embeddings│ │ - stdio/SSE │\n │ - scripts │ │ │ │ - WebSocket │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n## Çekirdek Bileşenler\n\n### 1. Synapse API (Fastify)\n\nAna HTTP sunucusu. Şunları ele alır:\n\n- REST uç noktaları (`/memory`, `/chat`, `/mind/tasks` vb.)\n- Kimlik doğrulama (ajanlar için Mind Key, insanlar için JWT)\n- Hız sınırlaması (yalnızca `?key=` kimlik doğrulaması)\n- Statik dosya sunumu (`/human`, `/docs` vb. web arayüzü)\n- Webhook dağıtımı\n\nPerformans için **Fastify 5** ile inşa edilmiştir. Üretimde 12800 portunda çalışır.\n\n### 2. FTS5 ile PostgreSQL\n\nBirincil veri deposu. Tam metin arama için FTS5 uzantısına sahip PostgreSQL kullanır.\n\n**Önemli tablolar:**\n\n| Tablo | Amaç |\n|-------|---------|\n| `users` | Kullanıcı hesapları |\n| `minds` | Mind kapsamları (her birinin bir Mind Key'i vardır) |\n| `memories` | FTS5 sanal tablosuyla bellek kayıtları |\n| `tasks` | Görev yönetimi |\n| `chat_messages` | Sohbet geçmişi |\n| `scripts` | Kalıcı betikler |\n| `webhooks` | Webhook kayıtları |\n| `cron_jobs` | Zamanlanmış görevler |\n| `variables` | Anahtar-değer deposu |\n| `audit_log` | Denetim izi |\n\n**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).\n\n### 3. Gömme Hizmeti (İsteğe Bağlı)\n\nAnlamsal 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.\n\n- Sağlayıcı: yapılandırılabilir (OpenAI, yerel model vb.)\n- `memories` tablosunda `vector` sütunu olarak saklanır\n- `/memory/semantic-search` uç noktası tarafından kullanılır\n- Bkz. [Anlamsal Arama](/docs/concepts/semantic-search)\n\n### 4. MCP Sunucusu (Ayrı Hizmet)\n\nSynapse MCP sunucusu ayrı bir süreç (port 13100) olarak çalışır. Şunları yapar:\n\n- Model Context Protocol üzerinden 79 araç sunar\n- stdio, HTTP/SSE ve WebSocket taşıyıcılarını destekler\n- MCP araç çağrılarını Synapse API çağrılarına çevirir\n- Çok kiracılı: oturum başına bir Mind Key\n\n### 5. Browser Proxy (Ayrı Hizmet)\n\nTarayıcı otomasyonu için, 13000 portunda Playwright tabanlı ayrı bir hizmet çalışır. MCP sunucusu bunu `browser_*` araçları için çağırabilir.\n\n### 6. SSH Proxy (Ayrı Hizmet)\n\nSSH tabanlı uzak komutlar için, 12900 portunda ayrı bir hizmet çalışır.\n\n## Çok Kiracılılık Modeli\n\n```\nUser Account (email + password)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── Memories\n │ ├── Tasks\n │ ├── Chat\n │ └── Scripts\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (isolated from Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nHer 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).\n\nDetaylar için bkz. [Çok Kiracılılık](/docs/concepts/multi-tenancy).\n\n## İstek Akışı\n\n### Bellek Saklama İsteği\n\n```\n1. Client sends POST /memory with Authorization: Bearer mk_xxx\n2. Fastify receives request\n3. Auth middleware validates Mind Key, attaches mind_id to request\n4. Memory route handler:\n a. Validate JSON body (zod schema)\n b. Insert into memories table\n c. Update FTS5 index\n d. (Async) Generate embedding if embeddings enabled\n e. Trigger webhooks for memory.store event\n5. Return { id, status: \"stored\" }\n```\n\n### Bellek Arama İsteği\n\n```\n1. Client sends GET /memory/search?q=docker\n2. Auth middleware validates Mind Key\n3. Memory route handler:\n a. Parse query (FTS5 syntax)\n b. Execute FTS5 MATCH against memories table\n c. Filter by mind_id (tenant isolation)\n d. Rank by relevance\n e. Return results\n```\n\n## Dağıtım\n\nSynapse bir Docker konteyneri olarak dağıtılır. Bkz. `docker-compose.yml`:\n\n```yaml\nservices:\n synapse:\n image: registry.gitlab.com/schaefer-services/synapse:latest\n ports:\n - \"12800:12800\"\n environment:\n - DATABASE_URL=postgres://...\n - JWT_SECRET=...\n - SYNAPSE_HOST=0.0.0.0\n - SYNAPSE_PORT=12800\n depends_on:\n - postgres\n \n postgres:\n image: postgres:16\n volumes:\n - pgdata:/var/lib/postgresql/data\n environment:\n - POSTGRES_DB=synapse\n - POSTGRES_PASSWORD=...\n```\n\n## Performans Karakteristikleri\n\n| İşlem | Gecikme | Verim |\n|-----------|---------|------------|\n| Bellek saklama | ~5ms | 1000+ istek/sn |\n| Bellek geri çağırma | ~20ms | 500 istek/sn |\n| FTS5 arama | ~10ms | 800 istek/sn |\n| Anlamsal arama | ~50ms | 200 istek/sn |\n| Sohbet poll | ~5ms | 2000 istek/sn |\n\n## Sonraki Adımlar\n\n- [Bellek Modeli](/docs/concepts/memory-model)\n- [Çok Kiracılılık](/docs/concepts/multi-tenancy)\n- [FTS5 Arama](/docs/concepts/fts5-search)\n","content_html":"

Synapse Mimarisi

\n

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.

\n

Üst Düzey Mimari

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

Çekirdek Bileşenler

\n

1. Synapse API (Fastify)

\n

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

\n\n

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

\n

2. FTS5 ile PostgreSQL

\n

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

\n

Önemli tablolar:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TabloAmaç
usersKullanıcı hesapları
mindsMind kapsamları (her birinin bir Mind Key'i vardır)
memoriesFTS5 sanal tablosuyla bellek kayıtları
tasksGörev yönetimi
chat_messagesSohbet geçmişi
scriptsKalıcı betikler
webhooksWebhook kayıtları
cron_jobsZamanlanmış görevler
variablesAnahtar-değer deposu
audit_logDenetim izi
\n

FTS5, tüm bellek içeriğinde milisaniyenin altında tam metin arama sağlar. Detaylar için bkz. FTS5 Arama.

\n

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

\n

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.

\n\n

4. MCP Sunucusu (Ayrı Hizmet)

\n

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

\n\n

5. Browser Proxy (Ayrı Hizmet)

\n

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

\n

6. SSH Proxy (Ayrı Hizmet)

\n

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

\n

Çok Kiracılılık Modeli

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

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).

\n

Detaylar için bkz. Çok Kiracılılık.

\n

İstek Akışı

\n

Bellek Saklama İsteği

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

Bellek Arama İsteği

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

Dağıtım

\n

Synapse bir Docker konteyneri olarak dağıtılır. Bkz. docker-compose.yml:

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

Performans Karakteristikleri

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
İşlemGecikmeVerim
Bellek saklama~5ms1000+ istek/sn
Bellek geri çağırma~20ms500 istek/sn
FTS5 arama~10ms800 istek/sn
Anlamsal arama~50ms200 istek/sn
Sohbet poll~5ms2000 istek/sn
\n

Sonraki Adımlar

\n\n","urls":{"html":"/docs/concepts/architecture","text":"/docs/concepts/architecture?format=text","json":"/docs/concepts/architecture?format=json","llm":"/docs/concepts/architecture?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}