{"title":"Arsitektur Synapse","slug":"architecture","category":"concepts","summary":"Bagaimana Synapse dibangun — Fastify, PostgreSQL, FTS5, embeddings, MCP server.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":429,"read_minutes":2,"lang":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Arsitektur Synapse\n\nSynapse adalah API memori multi-tenant yang dibangun di atas Fastify, PostgreSQL\ndengan FTS5, dan layanan embeddings opsional untuk pencarian semantik.\n\n## Arsitektur Tingkat Tinggi\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## Komponen Inti\n\n### 1. Synapse API (Fastify)\n\nServer HTTP utama. Menangani:\n\n- Endpoint REST (`/memory`, `/chat`, `/mind/tasks`, dll.)\n- Autentikasi (Mind Key untuk agen, JWT untuk manusia)\n- Rate limiting (hanya autentikasi `?key=`)\n- Penyajian file statis (web UI di `/human`, `/docs`, dll.)\n- Pengiriman webhook\n\nDibangun dengan **Fastify 5** untuk performa. Berjalan di port 12800 di produksi.\n\n### 2. PostgreSQL dengan FTS5\n\nPenyimpanan data utama. Menggunakan PostgreSQL dengan ekstensi FTS5 untuk\npencarian teks penuh.\n\n**Tabel utama:**\n\n| Tabel | Tujuan |\n|-------|---------|\n| `users` | Akun pengguna |\n| `minds` | Cakupan mind (masing-masing memiliki Mind Key) |\n| `memories` | Catatan memori dengan tabel virtual FTS5 |\n| `tasks` | Manajemen tugas |\n| `chat_messages` | Riwayat chat |\n| `scripts` | Skrip persisten |\n| `webhooks` | Pendaftaran webhook |\n| `cron_jobs` | Tugas terjadwal |\n| `variables` | Key-value store |\n| `audit_log` | Jejak audit |\n\n**FTS5** memungkinkan pencarian teks penuh sub-milidetik di seluruh konten memori.\nLihat [Pencarian FTS5](/docs/concepts/fts5-search) untuk detail.\n\n### 3. Layanan Embeddings (Opsional)\n\nUntuk pencarian semantik, Synapse membuat vektor embeddings dari konten memori.\nIni disimpan bersama memori dan digunakan untuk pencarian kesamaan.\n\n- Provider: dapat dikonfigurasi (OpenAI, model lokal, dll.)\n- Disimpan sebagai kolom `vector` di tabel `memories`\n- Digunakan oleh endpoint `/memory/semantic-search`\n- Lihat [Pencarian Semantik](/docs/concepts/semantic-search)\n\n### 4. MCP Server (Layanan Terpisah)\n\nSynapse MCP server berjalan sebagai proses terpisah (port 13100). Server ini:\n\n- Mengekspos 79 alat melalui Model Context Protocol\n- Mendukung transport stdio, HTTP/SSE, dan WebSocket\n- Menerjemahkan pemanggilan alat MCP menjadi pemanggilan API Synapse\n- Multi-tenant: satu Mind Key per sesi\n\n### 5. Browser Proxy (Layanan Terpisah)\n\nUntuk otomasi browser, layanan terpisah berbasis Playwright berjalan di port 13000.\nMCP server dapat memanggil ini untuk alat `browser_*`.\n\n### 6. SSH Proxy (Layanan Terpisah)\n\nUntuk perintah remote berbasis SSH, layanan terpisah berjalan di port 12900.\n\n## Model 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\nSetiap mind sepenuhnya terisolasi. Mind Key memberikan akses ke tepat satu mind.\nJWT memberikan akses ke akun pengguna (untuk mengelola mind).\n\nLihat [Multi-Tenancy](/docs/concepts/multi-tenancy) untuk detail.\n\n## Alur Permintaan\n\n### Permintaan Penyimpanan Memori\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### Permintaan Pencarian Memori\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 di-deploy sebagai container Docker. Lihat `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## Karakteristik Performa\n\n| Operasi | Latensi | Throughput |\n|-----------|---------|------------|\n| Penyimpanan memori | ~5ms | 1000+ req/s |\n| Recall memori | ~20ms | 500 req/s |\n| Pencarian FTS5 | ~10ms | 800 req/s |\n| Pencarian semantik | ~50ms | 200 req/s |\n| Polling chat | ~5ms | 2000 req/s |\n\n## Langkah Berikutnya\n\n- [Model Memori](/docs/concepts/memory-model)\n- [Multi-Tenancy](/docs/concepts/multi-tenancy)\n- [Pencarian FTS5](/docs/concepts/fts5-search)\n","content_html":"

Arsitektur Synapse

\n

Synapse adalah API memori multi-tenant yang dibangun di atas Fastify, PostgreSQL\ndengan FTS5, dan layanan embeddings opsional untuk pencarian semantik.

\n

Arsitektur Tingkat Tinggi

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

Komponen Inti

\n

1. Synapse API (Fastify)

\n

Server HTTP utama. Menangani:

\n\n

Dibangun dengan Fastify 5 untuk performa. Berjalan di port 12800 di produksi.

\n

2. PostgreSQL dengan FTS5

\n

Penyimpanan data utama. Menggunakan PostgreSQL dengan ekstensi FTS5 untuk\npencarian teks penuh.

\n

Tabel utama:

\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
TabelTujuan
usersAkun pengguna
mindsCakupan mind (masing-masing memiliki Mind Key)
memoriesCatatan memori dengan tabel virtual FTS5
tasksManajemen tugas
chat_messagesRiwayat chat
scriptsSkrip persisten
webhooksPendaftaran webhook
cron_jobsTugas terjadwal
variablesKey-value store
audit_logJejak audit
\n

FTS5 memungkinkan pencarian teks penuh sub-milidetik di seluruh konten memori.\nLihat Pencarian FTS5 untuk detail.

\n

3. Layanan Embeddings (Opsional)

\n

Untuk pencarian semantik, Synapse membuat vektor embeddings dari konten memori.\nIni disimpan bersama memori dan digunakan untuk pencarian kesamaan.

\n\n

4. MCP Server (Layanan Terpisah)

\n

Synapse MCP server berjalan sebagai proses terpisah (port 13100). Server ini:

\n\n

5. Browser Proxy (Layanan Terpisah)

\n

Untuk otomasi browser, layanan terpisah berbasis Playwright berjalan di port 13000.\nMCP server dapat memanggil ini untuk alat browser_*.

\n

6. SSH Proxy (Layanan Terpisah)

\n

Untuk perintah remote berbasis SSH, layanan terpisah berjalan di port 12900.

\n

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

Setiap mind sepenuhnya terisolasi. Mind Key memberikan akses ke tepat satu mind.\nJWT memberikan akses ke akun pengguna (untuk mengelola mind).

\n

Lihat Multi-Tenancy untuk detail.

\n

Alur Permintaan

\n

Permintaan Penyimpanan Memori

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

Permintaan Pencarian Memori

\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 di-deploy sebagai container Docker. Lihat 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=...

Karakteristik Performa

\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
OperasiLatensiThroughput
Penyimpanan memori~5ms1000+ req/s
Recall memori~20ms500 req/s
Pencarian FTS5~10ms800 req/s
Pencarian semantik~50ms200 req/s
Polling chat~5ms2000 req/s
\n

Langkah Berikutnya

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