# Synapse आर्किटेक्चर

Synapse एक मल्टी-टैनेंट मेमोरी API है जो Fastify, FTS5 के साथ PostgreSQL, और सिमेंटिक खोज के लिए एक वैकल्पिक embeddings सेवा पर बना है।

## उच्च-स्तरीय आर्किटेक्चर

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

## मुख्य घटक

### 1. Synapse API (Fastify)

मुख्य HTTP server। संभालता है:

- REST एंडपॉइंट्स (`/memory`, `/chat`, `/mind/tasks`, आदि)
- प्रमाणीकरण (एजेंट्स के लिए Mind Key, मानवों के लिए JWT)
- रेट लिमिटिंग (केवल `?key=` प्रमाणीकरण)
- स्टेटिक फ़ाइल सर्विंग (`/human`, `/docs`, आदि पर वेब UI)
- Webhook डिस्पैच

प्रदर्शन के लिए **Fastify 5** के साथ बना। उत्पादन में पोर्ट 12800 पर चलता है।

### 2. FTS5 के साथ PostgreSQL

प्राथमिक डेटा स्टोर। फुल-टेक्स्ट खोज के लिए FTS5 एक्सटेंशन के साथ PostgreSQL का उपयोग करता है।

**मुख्य तालिकाएँ:**

| तालिका | उद्देश्य |
|-------|---------|
| `users` | उपयोगकर्ता खाते |
| `minds` | Mind दायरे (प्रत्येक के पास Mind Key है) |
| `memories` | FTS5 वर्चुअल तालिका के साथ मेमोरी रिकॉर्ड्स |
| `tasks` | कार्य प्रबंधन |
| `chat_messages` | चैट इतिहास |
| `scripts` | स्थायी स्क्रिप्ट्स |
| `webhooks` | Webhook पंजीकरण |
| `cron_jobs` | शेड्यूल किए गए कार्य |
| `variables` | Key-value स्टोर |
| `audit_log` | ऑडिट ट्रेल |

**FTS5** सभी मेमोरी सामग्री में सब-मिलीसेकंड फुल-टेक्स्ट खोज सक्षम बनाता है। विवरण के लिए [FTS5 Search](/docs/concepts/fts5-search) देखें।

### 3. Embeddings सेवा (वैकल्पिक)

सिमेंटिक खोज के लिए, Synapse मेमोरी सामग्री के वेक्टर embeddings जनरेट करता है। ये मेमोरीज़ के साथ संग्रहीत होते हैं और समानता खोज के लिए उपयोग किए जाते हैं।

- प्रदाता: कॉन्फ़िगर करने योग्य (OpenAI, लोकल मॉडल, आदि)
- `memories` तालिका में `vector` कॉलम के रूप में संग्रहीत
- `/memory/semantic-search` एंडपॉइंट द्वारा उपयोग
- [सिमेंटिक खोज](/docs/concepts/semantic-search) देखें

### 4. MCP Server (अलग सेवा)

Synapse MCP server एक अलग प्रक्रिया के रूप में चलता है (पोर्ट 13100)। यह:

- Model Context Protocol के माध्यम से 79 टूल्स एक्सपोज़ करता है
- stdio, HTTP/SSE, और WebSocket ट्रांसपोर्ट का समर्थन करता है
- MCP टूल कॉल्स को Synapse API कॉल्स में अनुवादित करता है
- मल्टी-टैनेंट: प्रति सत्र एक Mind Key

### 5. Browser Proxy (अलग सेवा)

ब्राउज़र ऑटोमेशन के लिए, एक अलग Playwright-आधारित सेवा पोर्ट 13000 पर चलती है। MCP server `browser_*` टूल्स के लिए इसे कॉल कर सकता है।

### 6. SSH Proxy (अलग सेवा)

SSH-आधारित रिमोट कमांड्स के लिए, एक अलग सेवा पोर्ट 12900 पर चलती है।

## मल्टी-टैनेंसी मॉडल

```
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)
      └── ...
```

प्रत्येक mind पूरी तरह से अलग है। Mind Keys ठीक एक mind तक पहुँच प्रदान करते हैं।
JWTs उपयोगकर्ता खाते तक पहुँच प्रदान करते हैं (minds प्रबंधित करने के लिए)।

विवरण के लिए [मल्टी-टैनेंसी](/docs/concepts/multi-tenancy) देखें।

## अनुरोध प्रवाह

### मेमोरी स्टोर अनुरोध

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

### मेमोरी खोज अनुरोध

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

## परिनियोजन

Synapse एक Docker कंटेनर के रूप में परिनियोजित होता है। `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=...
```

## प्रदर्शन विशेषताएँ

| ऑपरेशन | विलंबता | थ्रूपुट |
|-----------|---------|------------|
| मेमोरी स्टोर | ~5ms | 1000+ req/s |
| मेमोरी रिकॉल | ~20ms | 500 req/s |
| FTS5 खोज | ~10ms | 800 req/s |
| सिमेंटिक खोज | ~50ms | 200 req/s |
| चैट poll | ~5ms | 2000 req/s |

## अगले कदम

- [मेमोरी मॉडल](/docs/concepts/memory-model)
- [मल्टी-टैनेंसी](/docs/concepts/multi-tenancy)
- [FTS5 Search](/docs/concepts/fts5-search)