{"title":"Synapse Architecture","slug":"architecture","category":"concepts","summary":"วิธีที่ Synapse ถูกสร้างขึ้น — Fastify, PostgreSQL, FTS5, embeddings, MCP server","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":379,"read_minutes":2,"lang":"th","translated":true,"requested_lang":"th","content_markdown":"\n# Synapse Architecture\n\nSynapse เป็น multi-tenant memory API ที่สร้างบน Fastify, PostgreSQL พร้อม FTS5 และ embeddings service ที่เป็นตัวเลือกสำหรับ semantic search\n\n## Architecture ระดับสูง\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## Core Components\n\n### 1. Synapse API (Fastify)\n\nHTTP server หลัก จัดการ:\n\n- REST endpoint (`/memory`, `/chat`, `/mind/tasks`, etc.)\n- Authentication (Mind Key สำหรับ agent, JWT สำหรับ human)\n- Rate limiting (เฉพาะ auth ผ่าน `?key=`)\n- Static file serving (web UI ที่ `/human`, `/docs`, etc.)\n- Webhook dispatch\n\nสร้างด้วย **Fastify 5** เพื่อประสิทธิภาพ รันบน port 12800 ใน production\n\n### 2. PostgreSQL with FTS5\n\ndata store หลัก ใช้ PostgreSQL พร้อม FTS5 extension สำหรับ full-text search\n\n**ตารางหลัก:**\n\n| ตาราง | วัตถุประสงค์ |\n|-------|---------|\n| `users` | บัญชีผู้ใช้ |\n| `minds` | Mind scope (แต่ละอันมี Mind Key) |\n| `memories` | Memory record พร้อม FTS5 virtual table |\n| `tasks` | การจัดการ task |\n| `chat_messages` | ประวัติแช็ต |\n| `scripts` | Script แบบถาวร |\n| `webhooks` | การลงทะเบียน webhook |\n| `cron_jobs` | Task ที่ตั้งเวลาไว้ |\n| `variables` | Key-value store |\n| `audit_log` | Audit trail |\n\n**FTS5** เปิดใช้งาน full-text search ในระดับ sub-millisecond ทั่วเนื้อหา memory ทั้งหมด ดูรายละเอียดที่ [FTS5 Search](/docs/concepts/fts5-search)\n\n### 3. Embeddings Service (Optional)\n\nสำหรับ semantic search Synapse สร้าง vector embeddings ของเนื้อหา memory ซึ่งเก็บไว้กับ memory และใช้สำหรับ similarity search\n\n- Provider: กำหนดค่าได้ (OpenAI, local model, etc.)\n- เก็บเป็น `vector` column ในตาราง `memories`\n- ใช้โดย endpoint `/memory/semantic-search`\n- ดู [Semantic Search](/docs/concepts/semantic-search)\n\n### 4. MCP Server (Service แยกต่างหาก)\n\nSynapse MCP server รันเป็น process แยกต่างหาก (port 13100) ทำหน้าที่:\n\n- เปิดเผย 79 tool ผ่าน Model Context Protocol\n- รองรับ stdio, HTTP/SSE และ WebSocket transport\n- แปล MCP tool call เป็น Synapse API call\n- Multi-tenant: หนึ่ง Mind Key ต่อ session\n\n### 5. Browser Proxy (Service แยกต่างหาก)\n\nสำหรับ browser automation service แยกต่างหากที่ใช้ Playwright รันบน port 13000 MCP server สามารถเรียกสิ่งนี้สำหรับ tool `browser_*`\n\n### 6. SSH Proxy (Service แยกต่างหาก)\n\nสำหรับคำสั่งระยะไกลผ่าน SSH service แยกต่างหากรันบน port 12900\n\n## โมเดล 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\nแต่ละ mind ถูกแยกอย่างสมบูรณ์ Mind Key ให้สิทธิ์เข้าถึง mind หนึ่งเท่านั้น JWT ให้สิทธิ์เข้าถึงบัญชีผู้ใช้ (สำหรับจัดการ mind)\n\nดูรายละเอียดที่ [Multi-Tenancy](/docs/concepts/multi-tenancy)\n\n## การไหลของ Request\n\n### Request เก็บ Memory\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### Request ค้นหา Memory\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## Deployment\n\nSynapse deploy เป็น Docker container ดู `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| การดำเนินการ | Latency | Throughput |\n|-----------|---------|------------|\n| Memory store | ~5ms | 1000+ req/s |\n| Memory recall | ~20ms | 500 req/s |\n| FTS5 search | ~10ms | 800 req/s |\n| Semantic search | ~50ms | 200 req/s |\n| Chat poll | ~5ms | 2000 req/s |\n\n## ขั้นตอนถัดไป\n\n- [Memory Model](/docs/concepts/memory-model)\n- [Multi-Tenancy](/docs/concepts/multi-tenancy)\n- [FTS5 Search](/docs/concepts/fts5-search)\n","content_html":"

Synapse Architecture

\n

Synapse เป็น multi-tenant memory API ที่สร้างบน Fastify, PostgreSQL พร้อม FTS5 และ embeddings service ที่เป็นตัวเลือกสำหรับ semantic search

\n

Architecture ระดับสูง

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

Core Components

\n

1. Synapse API (Fastify)

\n

HTTP server หลัก จัดการ:

\n\n

สร้างด้วย Fastify 5 เพื่อประสิทธิภาพ รันบน port 12800 ใน production

\n

2. PostgreSQL with FTS5

\n

data store หลัก ใช้ PostgreSQL พร้อม FTS5 extension สำหรับ full-text search

\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บัญชีผู้ใช้
mindsMind scope (แต่ละอันมี Mind Key)
memoriesMemory record พร้อม FTS5 virtual table
tasksการจัดการ task
chat_messagesประวัติแช็ต
scriptsScript แบบถาวร
webhooksการลงทะเบียน webhook
cron_jobsTask ที่ตั้งเวลาไว้
variablesKey-value store
audit_logAudit trail
\n

FTS5 เปิดใช้งาน full-text search ในระดับ sub-millisecond ทั่วเนื้อหา memory ทั้งหมด ดูรายละเอียดที่ FTS5 Search

\n

3. Embeddings Service (Optional)

\n

สำหรับ semantic search Synapse สร้าง vector embeddings ของเนื้อหา memory ซึ่งเก็บไว้กับ memory และใช้สำหรับ similarity search

\n\n

4. MCP Server (Service แยกต่างหาก)

\n

Synapse MCP server รันเป็น process แยกต่างหาก (port 13100) ทำหน้าที่:

\n\n

5. Browser Proxy (Service แยกต่างหาก)

\n

สำหรับ browser automation service แยกต่างหากที่ใช้ Playwright รันบน port 13000 MCP server สามารถเรียกสิ่งนี้สำหรับ tool browser_*

\n

6. SSH Proxy (Service แยกต่างหาก)

\n

สำหรับคำสั่งระยะไกลผ่าน SSH service แยกต่างหากรันบน port 12900

\n

โมเดล 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      └── ...

แต่ละ mind ถูกแยกอย่างสมบูรณ์ Mind Key ให้สิทธิ์เข้าถึง mind หนึ่งเท่านั้น JWT ให้สิทธิ์เข้าถึงบัญชีผู้ใช้ (สำหรับจัดการ mind)

\n

ดูรายละเอียดที่ Multi-Tenancy

\n

การไหลของ Request

\n

Request เก็บ Memory

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

Request ค้นหา Memory

\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

Deployment

\n

Synapse deploy เป็น Docker container ดู 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
การดำเนินการLatencyThroughput
Memory store~5ms1000+ req/s
Memory recall~20ms500 req/s
FTS5 search~10ms800 req/s
Semantic search~50ms200 req/s
Chat poll~5ms2000 req/s
\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"]}