# بنية Synapse

Synapse واجهة ذاكرة متعددة المستأجرين مبنية على Fastify، و PostgreSQL مع FTS5،
وخدمة تضمينات اختيارية للبحث الدلالي.

## البنية عالية المستوى

```
┌──────────────────────────────────────────────────────────┐
│                       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 الرئيسي. يتولى:

- نقاط نهاية REST (`/memory`، `/chat`، `/mind/tasks`، إلخ)
- المصادقة (Mind Key للوكلاء، JWT للبشر)
- حدود المعدل (مصادقة `?key=` فقط)
- تقديم الملفات الثابتة (واجهة الويب في `/human`، `/docs`، إلخ)
- إرسال الـ webhooks

بُني بـ **Fastify 5** للأداء. يعمل على المنفذ 12800 في الإنتاج.

### 2. PostgreSQL مع FTS5

مخزن البيانات الأساسي. يستخدم PostgreSQL مع امتداد FTS5 للبحث
بنص كامل.

**الجداول الرئيسية:**

| الجدول | الغرض |
|-------|---------|
| `users` | حسابات المستخدمين |
| `minds` | نطاقات العقل (لكل واحد Mind Key) |
| `memories` | سجلات الذاكرة مع جدول FTS5 الافتراضي |
| `tasks` | إدارة المهام |
| `chat_messages` | سجل الدردشة |
| `scripts` | السكربتات الدائمة |
| `webhooks` | تسجيلات الـ webhooks |
| `cron_jobs` | المهام المجدولة |
| `variables` | تخزين القيم الأساسية |
| `audit_log` | مسار التدقيق |

يُمكّن **FTS5** بحثًا نصيًا كاملًا أقل من مللي ثانية عبر جميع محتويات الذاكرة.
راجع [بحث FTS5](/docs/concepts/fts5-search) للتفاصيل.

### 3. خدمة التضمينات (اختيارية)

للبحث الدلالي، يُولّد Synapse تضمينات متجهة لمحتوى الذاكرة.
تُخزّن بجانب الذكريات وتُستخدم للبحث عن التشابه.

- المزوّد: قابل للإعداد (OpenAI، نموذج محلي، إلخ)
- يُخزَّن كعمود `vector` في جدول `memories`
- يُستخدم بواسطة نقطة النهاية `/memory/semantic-search`
- راجع [البحث الدلالي](/docs/concepts/semantic-search)

### 4. خادم MCP (خدمة منفصلة)

يعمل خادم Synapse MCP كعملية منفصلة (المنفذ 13100). يقوم بـ:

- عرض 79 أداة عبر Model Context Protocol
- دعم نقل stdio و HTTP/SSE و WebSocket
- ترجمة استدعاءات أدوات MCP إلى استدعاءات Synapse API
- متعدد المستأجرين: Mind Key واحد لكل جلسة

### 5. وكيل المتصفح (خدمة منفصلة)

لأتمتة المتصفح، تعمل خدمة منفصلة قائمة على Playwright على المنفذ 13000.
يمكن لخادم MCP استدعاؤها لأدوات `browser_*`.

### 6. وكيل SSH (خدمة منفصلة)

لأوامر 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 Keys الوصول إلى عقل واحد فقط.
تمنح JWTs الوصول إلى حساب المستخدم (لإدارة العقول).

راجع [تعدد المستأجرين](/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=...
```

## خصائص الأداء

| العملية | زمن الاستجابة | الإنتاجية |
|-----------|---------|------------|
| تخزين ذاكرة | ~5 مللي ث | 1000+ طلب/ث |
| استدعاء ذاكرة | ~20 مللي ث | 500 طلب/ث |
| بحث FTS5 | ~10 مللي ث | 800 طلب/ث |
| بحث دلالي | ~50 مللي ث | 200 طلب/ث |
| استطلاع الدردشة | ~5 مللي ث | 2000 طلب/ث |

## الخطوات التالية

- [نموذج الذاكرة](/docs/concepts/memory-model)
- [تعدد المستأجرين](/docs/concepts/multi-tenancy)
- [بحث FTS5](/docs/concepts/fts5-search)