{"title":"Архітектура Synapse","slug":"architecture","category":"concepts","summary":"Як побудовано Synapse — Fastify, PostgreSQL, FTS5, ембеддинги, MCP-сервер.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":425,"read_minutes":2,"lang":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Архітектура Synapse\n\nSynapse — це мультитенантний API пам'яті, побудований на Fastify, PostgreSQL із\nFTS5 та опціональній службі ембеддингів для семантичного пошуку.\n\n## Архітектура високого рівня\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## Основні компоненти\n\n### 1. Synapse API (Fastify)\n\nГоловний HTTP-сервер. Обробляє:\n\n- REST-кінцеві точки (`/memory`, `/chat`, `/mind/tasks` тощо)\n- Автентифікацію (Mind Key для агентів, JWT для людей)\n- Обмеження частоти (лише для автентифікації `?key=`)\n- Віддачу статичних файлів (веб-інтерфейс на `/human`, `/docs` тощо)\n- Диспетчеризацію webhook-ів\n\nПобудовано на **Fastify 5** для високої продуктивності. У продакшені працює на\nпорту 12800.\n\n### 2. PostgreSQL з FTS5\n\nОсновне сховище даних. Використовує PostgreSQL із розширенням FTS5 для\nповнотекстового пошуку.\n\n**Основні таблиці:**\n\n| Таблиця | Призначення |\n|-------|---------|\n| `users` | Облікові записи користувачів |\n| `minds` | Області mind-ів (кожен має Mind Key) |\n| `memories` | Записи спогадів із віртуальною таблицею FTS5 |\n| `tasks` | Керування завданнями |\n| `chat_messages` | Історія чату |\n| `scripts` | Постійні скрипти |\n| `webhooks` | Реєстрації webhook-ів |\n| `cron_jobs` | Заплановані завдання |\n| `variables` | Сховище ключ-значення |\n| `audit_log` | Журнал аудиту |\n\n**FTS5** забезпечує повнотекстовий пошук за всіма спогадами з затримкою менше\nмілісекунди. Докладніше дивіться у [пошуку FTS5](/docs/concepts/fts5-search).\n\n### 3. Служба ембеддингів (опціональна)\n\nДля семантичного пошуку Synapse генерує векторні ембеддинги вмісту спогадів.\nВони зберігаються разом зі спогадами та використовуються для пошуку за подібністю.\n\n- Постачальник: настроюваний (OpenAI, локальна модель тощо)\n- Зберігається у колонці `vector` у таблиці `memories`\n- Використовується кінцевою точкою `/memory/semantic-search`\n- Дивіться [Семантичний пошук](/docs/concepts/semantic-search)\n\n### 4. MCP-сервер (окрема служба)\n\nMCP-сервер Synapse працює як окремий процес (порт 13100). Він:\n\n- Надає 79 інструментів через Model Context Protocol\n- Підтримує транспорти stdio, HTTP/SSE та WebSocket\n- Перетворює виклики MCP-інструментів у виклики API Synapse\n- Мультитенантний: один Mind Key на сесію\n\n### 5. Браузерний проксі (окрема служба)\n\nДля автоматизації браузера окрема служба на основі Playwright працює на порту\n13000. MCP-сервер може викликати її для інструментів `browser_*`.\n\n### 6. SSH-проксі (окрема служба)\n\nДля віддалених команд через SSH окрема служба працює на порту 12900.\n\n## Модель мультитенантності\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 │ └── ... (ізольований від Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nКожен mind повністю ізольований. Mind Keys надають доступ лише до одного mind-у.\nJWT надають доступ до облікового запису користувача (для керування mind-ами).\n\nДокладніше дивіться у [Мультитенантності](/docs/concepts/multi-tenancy).\n\n## Потік запитів\n\n### Запит на збереження спогаду\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### Запит на пошук спогадів\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## Розгортання\n\nSynapse розгортається як Docker-контейнер. Дивіться `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## Характеристики продуктивності\n\n| Операція | Затримка | Пропускна здатність |\n|-----------|---------|------------|\n| Збереження спогаду | ~5мс | 1000+ запитів/с |\n| Відкликання спогадів | ~20мс | 500 запитів/с |\n| Пошук FTS5 | ~10мс | 800 запитів/с |\n| Семантичний пошук | ~50мс | 200 запитів/с |\n| Опитування чату | ~5мс | 2000 запитів/с |\n\n## Наступні кроки\n\n- [Модель пам'яті](/docs/concepts/memory-model)\n- [Мультитенантність](/docs/concepts/multi-tenancy)\n- [Пошук FTS5](/docs/concepts/fts5-search)\n","content_html":"

Архітектура Synapse

\n

Synapse — це мультитенантний API пам'яті, побудований на Fastify, PostgreSQL із\nFTS5 та опціональній службі ембеддингів для семантичного пошуку.

\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

1. Synapse API (Fastify)

\n

Головний HTTP-сервер. Обробляє:

\n\n

Побудовано на Fastify 5 для високої продуктивності. У продакшені працює на\nпорту 12800.

\n

2. PostgreSQL з FTS5

\n

Основне сховище даних. Використовує PostgreSQL із розширенням FTS5 для\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\n\n
ТаблицяПризначення
usersОблікові записи користувачів
mindsОбласті mind-ів (кожен має Mind Key)
memoriesЗаписи спогадів із віртуальною таблицею FTS5
tasksКерування завданнями
chat_messagesІсторія чату
scriptsПостійні скрипти
webhooksРеєстрації webhook-ів
cron_jobsЗаплановані завдання
variablesСховище ключ-значення
audit_logЖурнал аудиту
\n

FTS5 забезпечує повнотекстовий пошук за всіма спогадами з затримкою менше\nмілісекунди. Докладніше дивіться у пошуку FTS5.

\n

3. Служба ембеддингів (опціональна)

\n

Для семантичного пошуку Synapse генерує векторні ембеддинги вмісту спогадів.\nВони зберігаються разом зі спогадами та використовуються для пошуку за подібністю.

\n\n

4. MCP-сервер (окрема служба)

\n

MCP-сервер Synapse працює як окремий процес (порт 13100). Він:

\n\n

5. Браузерний проксі (окрема служба)

\n

Для автоматизації браузера окрема служба на основі Playwright працює на порту\n13000. MCP-сервер може викликати її для інструментів browser_*.

\n

6. SSH-проксі (окрема служба)

\n

Для віддалених команд через SSH окрема служба працює на порту 12900.

\n

Модель мультитенантності

\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  │   └── ... (ізольований від Mind 1)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

Кожен mind повністю ізольований. Mind Keys надають доступ лише до одного mind-у.\nJWT надають доступ до облікового запису користувача (для керування mind-ами).

\n

Докладніше дивіться у Мультитенантності.

\n

Потік запитів

\n

Запит на збереження спогаду

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

Запит на пошук спогадів

\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

Розгортання

\n

Synapse розгортається як Docker-контейнер. Дивіться 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=...

Характеристики продуктивності

\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
ОпераціяЗатримкаПропускна здатність
Збереження спогаду~5мс1000+ запитів/с
Відкликання спогадів~20мс500 запитів/с
Пошук FTS5~10мс800 запитів/с
Семантичний пошук~50мс200 запитів/с
Опитування чату~5мс2000 запитів/с
\n

Наступні кроки

\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"]}