{"title":"Kiến trúc Synapse","slug":"architecture","category":"concepts","summary":"Cách Synapse được xây dựng — Fastify, PostgreSQL, FTS5, embeddings, MCP server.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":572,"read_minutes":3,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Kiến trúc Synapse\n\nSynapse là API bộ nhớ multi-tenant được xây dựng trên Fastify, PostgreSQL với\nFTS5, và một dịch vụ embeddings tùy chọn cho tìm kiếm ngữ nghĩa.\n\n## Kiến trúc tổng quan\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## Thành phần cốt lõi\n\n### 1. Synapse API (Fastify)\n\nHTTP server chính. Xử lý:\n\n- Endpoint REST (`/memory`, `/chat`, `/mind/tasks`, v.v.)\n- Xác thực (Mind Key cho agent, JWT cho con người)\n- Giới hạn tốc độ (chỉ xác thực `?key=`)\n- Phục vụ tệp tĩnh (giao diện web tại `/human`, `/docs`, v.v.)\n- Phân phối webhook\n\nĐược xây dựng với **Fastify 5** cho hiệu suất. Chạy trên cổng 12800 trong môi trường production.\n\n### 2. PostgreSQL với FTS5\n\nKho dữ liệu chính. Sử dụng PostgreSQL với phần mở rộng FTS5 cho tìm kiếm toàn\nvăn.\n\n**Bảng chính:**\n\n| Bảng | Mục đích |\n|-------|---------|\n| `users` | Tài khoản người dùng |\n| `minds` | Phạm vi mind (mỗi cái có một Mind Key) |\n| `memories` | Bản ghi bộ nhớ với bảng ảo FTS5 |\n| `tasks` | Quản lý tác vụ |\n| `chat_messages` | Lịch sử chat |\n| `scripts` | Script cố định |\n| `webhooks` | Đăng ký webhook |\n| `cron_jobs` | Tác vụ đã lên lịch |\n| `variables` | Cửa hàng key-value |\n| `audit_log` | Nhật ký kiểm toán |\n\n**FTS5** cho phép tìm kiếm toàn văn dưới mili giây trên toàn bộ nội dung bộ\nnhớ. Xem [Tìm kiếm FTS5](/docs/concepts/fts5-search) để biết chi tiết.\n\n### 3. Dịch vụ Embeddings (Tùy chọn)\n\nĐối với tìm kiếm ngữ nghĩa, Synapse tạo vector embeddings của nội dung bộ nhớ.\nChúng được lưu cùng với bộ nhớ và dùng cho tìm kiếm tương tự.\n\n- Provider: có thể cấu hình (OpenAI, mô hình cục bộ, v.v.)\n- Lưu dưới dạng cột `vector` trong bảng `memories`\n- Được sử dụng bởi endpoint `/memory/semantic-search`\n- Xem [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search)\n\n### 4. MCP Server (Dịch vụ riêng)\n\nSynapse MCP server chạy như một tiến trình riêng (cổng 13100). Nó:\n\n- Cung cấp 79 công cụ qua Model Context Protocol\n- Hỗ trợ transport stdio, HTTP/SSE và WebSocket\n- Dịch các lệnh gọi công cụ MCP thành lệnh gọi Synapse API\n- Multi-tenant: một Mind Key mỗi phiên\n\n### 5. Browser Proxy (Dịch vụ riêng)\n\nĐối với tự động hóa trình duyệt, một dịch vụ riêng dựa trên Playwright chạy\ntrên cổng 13000. MCP server có thể gọi dịch vụ này cho các công cụ `browser_*`.\n\n### 6. SSH Proxy (Dịch vụ riêng)\n\nĐối với lệnh từ xa dựa trên SSH, một dịch vụ riêng chạy trên cổng 12900.\n\n## Mô hình Multi-Tenancy\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\nMỗi mind hoàn toàn tách biệt. Mind Key cấp quyền truy cập chính xác một mind.\nJWT cấp quyền truy cập tài khoản người dùng (để quản lý mind).\n\nXem [Multi-Tenancy](/docs/concepts/multi-tenancy) để biết chi tiết.\n\n## Luồng yêu cầu\n\n### Yêu cầu lưu bộ nhớ\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### Yêu cầu tìm kiếm bộ nhớ\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## Triển khai\n\nSynapse được triển khai dưới dạng Docker container. Xem `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## Đặc tính hiệu suất\n\n| Thao tác | Độ trễ | Thông lượng |\n|-----------|---------|------------|\n| Lưu bộ nhớ | ~5ms | 1000+ req/s |\n| Thu hồi bộ nhớ | ~20ms | 500 req/s |\n| Tìm kiếm FTS5 | ~10ms | 800 req/s |\n| Tìm kiếm ngữ nghĩa | ~50ms | 200 req/s |\n| Poll chat | ~5ms | 2000 req/s |\n\n## Bước tiếp theo\n\n- [Mô hình bộ nhớ](/docs/concepts/memory-model)\n- [Multi-Tenancy](/docs/concepts/multi-tenancy)\n- [Tìm kiếm FTS5](/docs/concepts/fts5-search)\n","content_html":"

Kiến trúc Synapse

\n

Synapse là API bộ nhớ multi-tenant được xây dựng trên Fastify, PostgreSQL với\nFTS5, và một dịch vụ embeddings tùy chọn cho tìm kiếm ngữ nghĩa.

\n

Kiến trúc tổng quan

\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       └─────────────┘ └─────────────┘ └─────────────┘

Thành phần cốt lõi

\n

1. Synapse API (Fastify)

\n

HTTP server chính. Xử lý:

\n\n

Được xây dựng với Fastify 5 cho hiệu suất. Chạy trên cổng 12800 trong môi trường production.

\n

2. PostgreSQL với FTS5

\n

Kho dữ liệu chính. Sử dụng PostgreSQL với phần mở rộng FTS5 cho tìm kiếm toàn\nvăn.

\n

Bảng chính:

\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
BảngMục đích
usersTài khoản người dùng
mindsPhạm vi mind (mỗi cái có một Mind Key)
memoriesBản ghi bộ nhớ với bảng ảo FTS5
tasksQuản lý tác vụ
chat_messagesLịch sử chat
scriptsScript cố định
webhooksĐăng ký webhook
cron_jobsTác vụ đã lên lịch
variablesCửa hàng key-value
audit_logNhật ký kiểm toán
\n

FTS5 cho phép tìm kiếm toàn văn dưới mili giây trên toàn bộ nội dung bộ\nnhớ. Xem Tìm kiếm FTS5 để biết chi tiết.

\n

3. Dịch vụ Embeddings (Tùy chọn)

\n

Đối với tìm kiếm ngữ nghĩa, Synapse tạo vector embeddings của nội dung bộ nhớ.\nChúng được lưu cùng với bộ nhớ và dùng cho tìm kiếm tương tự.

\n\n

4. MCP Server (Dịch vụ riêng)

\n

Synapse MCP server chạy như một tiến trình riêng (cổng 13100). Nó:

\n\n

5. Browser Proxy (Dịch vụ riêng)

\n

Đối với tự động hóa trình duyệt, một dịch vụ riêng dựa trên Playwright chạy\ntrên cổng 13000. MCP server có thể gọi dịch vụ này cho các công cụ browser_*.

\n

6. SSH Proxy (Dịch vụ riêng)

\n

Đối với lệnh từ xa dựa trên SSH, một dịch vụ riêng chạy trên cổng 12900.

\n

Mô hình Multi-Tenancy

\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      └── ...

Mỗi mind hoàn toàn tách biệt. Mind Key cấp quyền truy cập chính xác một mind.\nJWT cấp quyền truy cập tài khoản người dùng (để quản lý mind).

\n

Xem Multi-Tenancy để biết chi tiết.

\n

Luồng yêu cầu

\n

Yêu cầu lưu bộ nhớ

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

Yêu cầu tìm kiếm bộ nhớ

\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

Triển khai

\n

Synapse được triển khai dưới dạng Docker container. Xem 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=...

Đặc tính hiệu suất

\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
Thao tácĐộ trễThông lượng
Lưu bộ nhớ~5ms1000+ req/s
Thu hồi bộ nhớ~20ms500 req/s
Tìm kiếm FTS5~10ms800 req/s
Tìm kiếm ngữ nghĩa~50ms200 req/s
Poll chat~5ms2000 req/s
\n

Bước tiếp theo

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