{"title":"Architecture de Synapse","slug":"architecture","category":"concepts","summary":"Comment Synapse est construit — Fastify, PostgreSQL, FTS5, embeddings, serveur MCP.","audience":["human","llm"],"tags":["architecture","design","components"],"difficulty":"intermediate","updated":"2026-06-27","word_count":498,"read_minutes":2,"lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Architecture de Synapse\n\nSynapse est une API de mémoire multi-tenant construite sur Fastify, PostgreSQL avec\nFTS5, et un service d'embeddings optionnel pour la recherche sémantique.\n\n## Architecture globale\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## Composants principaux\n\n### 1. API Synapse (Fastify)\n\nLe serveur HTTP principal. Gère :\n\n- Endpoints REST (`/memory`, `/chat`, `/mind/tasks`, etc.)\n- Authentification (Mind Key pour les agents, JWT pour les humains)\n- Limitation de débit (auth `?key=` uniquement)\n- Service de fichiers statiques (interface web sur `/human`, `/docs`, etc.)\n- Dispatch des webhooks\n\nConstruit avec **Fastify 5** pour la performance. Fonctionne sur le port 12800 en\nproduction.\n\n### 2. PostgreSQL avec FTS5\n\nLe magasin de données principal. Utilise PostgreSQL avec l'extension FTS5 pour la\nrecherche en texte intégral.\n\n**Tables principales :**\n\n| Table | Rôle |\n|-------|---------|\n| `users` | Comptes utilisateurs |\n| `minds` | Scopes de mind (chacun a une Mind Key) |\n| `memories` | Enregistrements de mémoire avec table virtuelle FTS5 |\n| `tasks` | Gestion des tâches |\n| `chat_messages` | Historique de chat |\n| `scripts` | Scripts persistants |\n| `webhooks` | Enregistrements de webhooks |\n| `cron_jobs` | Tâches planifiées |\n| `variables` | Magasin clé-valeur |\n| `audit_log` | Piste d'audit |\n\n**FTS5** permet la recherche en texte intégral sub-milliseconde sur tout le contenu\nde mémoire. Voir [Recherche FTS5](/docs/concepts/fts5-search) pour plus de détails.\n\n### 3. Service d'embeddings (optionnel)\n\nPour la recherche sémantique, Synapse génère des embeddings vectoriels du contenu des\nmémoires. Ils sont stockés à côté des mémoires et utilisés pour la recherche de\nsimilarité.\n\n- Fournisseur : configurable (OpenAI, modèle local, etc.)\n- Stocké comme colonne `vector` dans la table `memories`\n- Utilisé par l'endpoint `/memory/semantic-search`\n- Voir [Recherche sémantique](/docs/concepts/semantic-search)\n\n### 4. Serveur MCP (service séparé)\n\nLe serveur MCP Synapse s'exécute comme un processus distinct (port 13100). Il :\n\n- Expose 79 outils via Model Context Protocol\n- Prend en charge les transports stdio, HTTP/SSE et WebSocket\n- Traduit les appels d'outils MCP en appels d'API Synapse\n- Multi-tenant : une Mind Key par session\n\n### 5. Proxy navigateur (service séparé)\n\nPour l'automatisation de navigateur, un service distinct basé sur Playwright\ns'exécute sur le port 13000. Le serveur MCP peut l'appeler pour les outils\n`browser_*`.\n\n### 6. Proxy SSH (service séparé)\n\nPour les commandes distantes basées sur SSH, un service distinct s'exécute sur le\nport 12900.\n\n## Modèle multi-tenant\n\n```\nCompte utilisateur (email + mot de passe)\n │\n ├── Mind 1 (Mind Key 1)\n │ ├── Memories\n │ ├── Tasks\n │ ├── Chat\n │ └── Scripts\n │\n ├── Mind 2 (Mind Key 2)\n │ └── ... (isolé du Mind 1)\n │\n └── Mind 3 (Mind Key 3)\n └── ...\n```\n\nChaque mind est entièrement isolé. Les Mind Keys accordent l'accès à un seul mind.\nLes JWT accordent l'accès au compte utilisateur (pour gérer les minds).\n\nVoir [Multi-tenancy](/docs/concepts/multi-tenancy) pour plus de détails.\n\n## Flux de requêtes\n\n### Requête de stockage mémoire\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### Requête de recherche mémoire\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## Déploiement\n\nSynapse est déployé comme conteneur Docker. Voir `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## Caractéristiques de performance\n\n| Opération | Latence | Débit |\n|-----------|---------|------------|\n| Stockage mémoire | ~5 ms | 1000+ req/s |\n| Rappel mémoire | ~20 ms | 500 req/s |\n| Recherche FTS5 | ~10 ms | 800 req/s |\n| Recherche sémantique | ~50 ms | 200 req/s |\n| Polling chat | ~5 ms | 2000 req/s |\n\n## Prochaines étapes\n\n- [Modèle de mémoire](/docs/concepts/memory-model)\n- [Multi-tenancy](/docs/concepts/multi-tenancy)\n- [Recherche FTS5](/docs/concepts/fts5-search)\n","content_html":"

Architecture de Synapse

\n

Synapse est une API de mémoire multi-tenant construite sur Fastify, PostgreSQL avec\nFTS5, et un service d'embeddings optionnel pour la recherche sémantique.

\n

Architecture globale

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

Composants principaux

\n

1. API Synapse (Fastify)

\n

Le serveur HTTP principal. Gère :

\n\n

Construit avec Fastify 5 pour la performance. Fonctionne sur le port 12800 en\nproduction.

\n

2. PostgreSQL avec FTS5

\n

Le magasin de données principal. Utilise PostgreSQL avec l'extension FTS5 pour la\nrecherche en texte intégral.

\n

Tables principales :

\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
TableRôle
usersComptes utilisateurs
mindsScopes de mind (chacun a une Mind Key)
memoriesEnregistrements de mémoire avec table virtuelle FTS5
tasksGestion des tâches
chat_messagesHistorique de chat
scriptsScripts persistants
webhooksEnregistrements de webhooks
cron_jobsTâches planifiées
variablesMagasin clé-valeur
audit_logPiste d'audit
\n

FTS5 permet la recherche en texte intégral sub-milliseconde sur tout le contenu\nde mémoire. Voir Recherche FTS5 pour plus de détails.

\n

3. Service d'embeddings (optionnel)

\n

Pour la recherche sémantique, Synapse génère des embeddings vectoriels du contenu des\nmémoires. Ils sont stockés à côté des mémoires et utilisés pour la recherche de\nsimilarité.

\n\n

4. Serveur MCP (service séparé)

\n

Le serveur MCP Synapse s'exécute comme un processus distinct (port 13100). Il :

\n\n

5. Proxy navigateur (service séparé)

\n

Pour l'automatisation de navigateur, un service distinct basé sur Playwright\ns'exécute sur le port 13000. Le serveur MCP peut l'appeler pour les outils\nbrowser_*.

\n

6. Proxy SSH (service séparé)

\n

Pour les commandes distantes basées sur SSH, un service distinct s'exécute sur le\nport 12900.

\n

Modèle multi-tenant

\n
Compte utilisateur (email + mot de passe)\n  │\n  ├── Mind 1 (Mind Key 1)\n  │   ├── Memories\n  │   ├── Tasks\n  │   ├── Chat\n  │   └── Scripts\n  │\n  ├── Mind 2 (Mind Key 2)\n  │   └── ... (isolé du Mind 1)\n  │\n  └── Mind 3 (Mind Key 3)\n      └── ...

Chaque mind est entièrement isolé. Les Mind Keys accordent l'accès à un seul mind.\nLes JWT accordent l'accès au compte utilisateur (pour gérer les minds).

\n

Voir Multi-tenancy pour plus de détails.

\n

Flux de requêtes

\n

Requête de stockage mémoire

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

Requête de recherche mémoire

\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

Déploiement

\n

Synapse est déployé comme conteneur Docker. Voir 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=...

Caractéristiques de performance

\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
OpérationLatenceDébit
Stockage mémoire~5 ms1000+ req/s
Rappel mémoire~20 ms500 req/s
Recherche FTS5~10 ms800 req/s
Recherche sémantique~50 ms200 req/s
Polling chat~5 ms2000 req/s
\n

Prochaines étapes

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