# Arquitectura de Synapse

Synapse es una API de memoria multi-tenant construida sobre Fastify, PostgreSQL
con FTS5, y un servicio opcional de embeddings para búsqueda semántica.

## Arquitectura de alto nivel

```
┌──────────────────────────────────────────────────────────┐
│                       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 │
       └─────────────┘ └─────────────┘ └─────────────┘
```

## Componentes principales

### 1. Synapse API (Fastify)

El servidor HTTP principal. Gestiona:

- Endpoints REST (`/memory`, `/chat`, `/mind/tasks`, etc.)
- Autenticación (Mind Key para agentes, JWT para humanos)
- Límites de frecuencia (solo auth con `?key=`)
- Servido de archivos estáticos (interfaz web en `/human`, `/docs`, etc.)
- Dispatch de webhooks

Construido con **Fastify 5** para rendimiento. Se ejecuta en el puerto 12800 en
producción.

### 2. PostgreSQL con FTS5

El almacén de datos principal. Usa PostgreSQL con la extensión FTS5 para
búsqueda de texto completo.

**Tablas principales:**

| Tabla | Propósito |
|-------|---------|
| `users` | Cuentas de usuario |
| `minds` | Ámbitos de mind (cada uno tiene un Mind Key) |
| `memories` | Registros de memoria con tabla virtual FTS5 |
| `tasks` | Gestión de tareas |
| `chat_messages` | Historial de chat |
| `scripts` | Scripts persistentes |
| `webhooks` | Registros de webhooks |
| `cron_jobs` | Tareas programadas |
| `variables` | Almacén clave-valor |
| `audit_log` | Pista de auditoría |

**FTS5** permite búsqueda de texto completo sub-milisegundo sobre todo el
contenido de memoria. Consulte [Búsqueda FTS5](/docs/concepts/fts5-search) para
más detalles.

### 3. Servicio de Embeddings (opcional)

Para búsqueda semántica, Synapse genera embeddings vectoriales del contenido de
memoria. Se almacenan junto a las memorias y se usan para búsqueda por similitud.

- Proveedor: configurable (OpenAI, modelo local, etc.)
- Se almacenan como columna `vector` en la tabla `memories`
- Los usa el endpoint `/memory/semantic-search`
- Consulte [Búsqueda semántica](/docs/concepts/semantic-search)

### 4. Servidor MCP (servicio separado)

El servidor MCP de Synapse se ejecuta como un proceso aparte (puerto 13100).
Esta persona:

- Expone 79 herramientas vía Model Context Protocol
- Admite transportes stdio, HTTP/SSE y WebSocket
- Traduce llamadas a herramientas MCP en llamadas a la API de Synapse
- Multi-tenant: un Mind Key por sesión

### 5. Browser Proxy (servicio separado)

Para automatización de navegador, un servicio separado basado en Playwright se
ejecuta en el puerto 13000. El servidor MCP puede invocarlo para las
herramientas `browser_*`.

### 6. SSH Proxy (servicio separado)

Para comandos remotos basados en SSH, un servicio separado se ejecuta en el
puerto 12900.

## Modelo multi-tenant

```
User Account (email + password)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── Memories
  │   ├── Tasks
  │   ├── Chat
  │   └── Scripts
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (isolated from Mind 1)
  │
  └── Mind 3 (Mind Key 3)
      └── ...
```

Cada mind está completamente aislado. Los Mind Keys otorgan acceso a
exactamente un mind. Los JWT otorgan acceso a la cuenta de usuario (para
gestionar minds).

Consulte [Multi-Tenancy](/docs/concepts/multi-tenancy) para más detalles.

## Flujo de solicitudes

### Solicitud de almacenamiento de memoria

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

### Solicitud de búsqueda de memoria

```
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
```

## Despliegue

Synapse se despliega como un contenedor Docker. Consulte `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=...
```

## Características de rendimiento

| Operación | Latencia | Throughput |
|-----------|---------|------------|
| Memory store | ~5ms | 1000+ req/s |
| Memory recall | ~20ms | 500 req/s |
| FTS5 search | ~10ms | 800 req/s |
| Semantic search | ~50ms | 200 req/s |
| Chat poll | ~5ms | 2000 req/s |

## Próximos pasos

- [Modelo de memoria](/docs/concepts/memory-model)
- [Multi-Tenancy](/docs/concepts/multi-tenancy)
- [Búsqueda FTS5](/docs/concepts/fts5-search)