# Architecture de Synapse

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

## Architecture globale

```
┌──────────────────────────────────────────────────────────┐
│                       Clients                            │
├──────────────┬──────────────┬──────────────┬─────────────┤
│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │
│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │    Synapse API (Fastify)      │
              │    port 12800                 │
              │    - REST endpoints           │
              │    - Auth (Mind Key / JWT)    │
              │    - Rate limiting            │
              │    - Static file serving      │
              └───────────────┬───────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │
       │ + FTS5      │ │ Service     │ │ (separate)  │
       │             │ │ (optional)  │ │ port 13100  │
       │ - memories  │ │             │ │             │
       │ - tasks     │ │ - generate  │ │ - 79 tools  │
       │ - chat      │ │   embeddings│ │ - stdio/SSE │
       │ - scripts   │ │             │ │ - WebSocket │
       └─────────────┘ └─────────────┘ └─────────────┘
```

## Composants principaux

### 1. API Synapse (Fastify)

Le serveur HTTP principal. Gère :

- Endpoints REST (`/memory`, `/chat`, `/mind/tasks`, etc.)
- Authentification (Mind Key pour les agents, JWT pour les humains)
- Limitation de débit (auth `?key=` uniquement)
- Service de fichiers statiques (interface web sur `/human`, `/docs`, etc.)
- Dispatch des webhooks

Construit avec **Fastify 5** pour la performance. Fonctionne sur le port 12800 en
production.

### 2. PostgreSQL avec FTS5

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

**Tables principales :**

| Table | Rôle |
|-------|---------|
| `users` | Comptes utilisateurs |
| `minds` | Scopes de mind (chacun a une Mind Key) |
| `memories` | Enregistrements de mémoire avec table virtuelle FTS5 |
| `tasks` | Gestion des tâches |
| `chat_messages` | Historique de chat |
| `scripts` | Scripts persistants |
| `webhooks` | Enregistrements de webhooks |
| `cron_jobs` | Tâches planifiées |
| `variables` | Magasin clé-valeur |
| `audit_log` | Piste d'audit |

**FTS5** permet la recherche en texte intégral sub-milliseconde sur tout le contenu
de mémoire. Voir [Recherche FTS5](/docs/concepts/fts5-search) pour plus de détails.

### 3. Service d'embeddings (optionnel)

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

- Fournisseur : configurable (OpenAI, modèle local, etc.)
- Stocké comme colonne `vector` dans la table `memories`
- Utilisé par l'endpoint `/memory/semantic-search`
- Voir [Recherche sémantique](/docs/concepts/semantic-search)

### 4. Serveur MCP (service séparé)

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

- Expose 79 outils via Model Context Protocol
- Prend en charge les transports stdio, HTTP/SSE et WebSocket
- Traduit les appels d'outils MCP en appels d'API Synapse
- Multi-tenant : une Mind Key par session

### 5. Proxy navigateur (service séparé)

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

### 6. Proxy SSH (service séparé)

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

## Modèle multi-tenant

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

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

Voir [Multi-tenancy](/docs/concepts/multi-tenancy) pour plus de détails.

## Flux de requêtes

### Requête de stockage mémoire

```
1. Client sends POST /memory with Authorization: Bearer mk_xxx
2. Fastify receives request
3. Auth middleware validates Mind Key, attaches mind_id to request
4. Memory route handler:
   a. Validate JSON body (zod schema)
   b. Insert into memories table
   c. Update FTS5 index
   d. (Async) Generate embedding if embeddings enabled
   e. Trigger webhooks for memory.store event
5. Return { id, status: "stored" }
```

### Requête de recherche mémoire

```
1. Client sends GET /memory/search?q=docker
2. Auth middleware validates Mind Key
3. Memory route handler:
   a. Parse query (FTS5 syntax)
   b. Execute FTS5 MATCH against memories table
   c. Filter by mind_id (tenant isolation)
   d. Rank by relevance
   e. Return results
```

## Déploiement

Synapse est déployé comme conteneur Docker. Voir `docker-compose.yml` :

```yaml
services:
  synapse:
    image: registry.gitlab.com/schaefer-services/synapse:latest
    ports:
      - "12800:12800"
    environment:
      - DATABASE_URL=postgres://...
      - JWT_SECRET=...
      - SYNAPSE_HOST=0.0.0.0
      - SYNAPSE_PORT=12800
    depends_on:
      - postgres
  
  postgres:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=synapse
      - POSTGRES_PASSWORD=...
```

## Caractéristiques de performance

| Opération | Latence | Débit |
|-----------|---------|------------|
| Stockage mémoire | ~5 ms | 1000+ req/s |
| Rappel mémoire | ~20 ms | 500 req/s |
| Recherche FTS5 | ~10 ms | 800 req/s |
| Recherche sémantique | ~50 ms | 200 req/s |
| Polling chat | ~5 ms | 2000 req/s |

## Prochaines étapes

- [Modèle de mémoire](/docs/concepts/memory-model)
- [Multi-tenancy](/docs/concepts/multi-tenancy)
- [Recherche FTS5](/docs/concepts/fts5-search)