# Synapse 아키텍처

Synapse는 Fastify, FTS5가 포함된 PostgreSQL, 그리고 의미론적 검색을 위한
선택적 임베딩 서비스를 기반으로 구축된 다중 테넌트 메모리 API입니다.

## 고수준 아키텍처

```
┌──────────────────────────────────────────────────────────┐
│                       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` 등의 웹 UI)
- 웹훅 디스패치

성능을 위해 **Fastify 5**로 구축되었습니다. 프로덕션에서는 포트 12800에서
실행됩니다.

### 2. FTS5가 포함된 PostgreSQL

기본 데이터 저장소입니다. 전문 검색을 위해 FTS5 확장이 포함된
PostgreSQL을 사용합니다.

**주요 테이블:**

| 테이블 | 용도 |
|-------|---------|
| `users` | 사용자 계정 |
| `minds` | 마인드 범위 (각각 Mind Key 보유) |
| `memories` | FTS5 가상 테이블이 있는 메모리 레코드 |
| `tasks` | 작업 관리 |
| `chat_messages` | 채팅 기록 |
| `scripts` | 영구 스크립트 |
| `webhooks` | 웹훅 등록 |
| `cron_jobs` | 예약된 작업 |
| `variables` | 키-값 저장소 |
| `audit_log` | 감사 추적 |

**FTS5**는 모든 메모리 콘텐츠에 대해 서브밀리초 전문 검색을 가능하게
합니다. 자세한 내용은 [FTS5 검색](/docs/concepts/fts5-search)을 참조하십시오.

### 3. 임베딩 서비스 (선택 사항)

의미론적 검색을 위해 Synapse는 메모리 콘텐츠의 벡터 임베딩을 생성합니다.
이는 메모리와 함께 저장되며 유사도 검색에 사용됩니다.

- 제공자: 구성 가능 (OpenAI, 로컬 모델 등)
- `memories` 테이블의 `vector` 컬럼으로 저장
- `/memory/semantic-search` 엔드포인트에서 사용
- [의미론적 검색](/docs/concepts/semantic-search) 참조

### 4. MCP 서버 (별도 서비스)

Synapse MCP 서버는 별도의 프로세스 (포트 13100)로 실행됩니다. 다음을
수행합니다:

- Model Context Protocol을 통해 79개 도구 노출
- stdio, HTTP/SSE, WebSocket 전송 지원
- MCP 도구 호출을 Synapse API 호출로 변환
- 다중 테넌트: 세션당 하나의 Mind Key

### 5. Browser Proxy (별도 서비스)

브라우저 자동화를 위해 Playwright 기반의 별도 서비스가 포트 13000에서
실행됩니다. MCP 서버는 `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 Key는 정확히 하나의 마인드에만
접근 권한을 부여합니다. JWT는 사용자 계정 (마인드 관리용)에 접근 권한을
부여합니다.

자세한 내용은 [다중 테넌시](/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 |
| 채팅 폴링 | ~5ms | 2000 req/s |

## 다음 단계

- [메모리 모델](/docs/concepts/memory-model)
- [다중 테넌시](/docs/concepts/multi-tenancy)
- [FTS5 검색](/docs/concepts/fts5-search)