claude-memory-layer 1.0.0

package/specs/web-viewer-ui/spec.md

@@ -0,0 +1,516 @@
+# Web Viewer UI Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 메모리 상태 시각화가 어려움:
+
+1. **CLI 한계**: 대량 데이터 탐색 불편
+2. **실시간 모니터링 없음**: 세션 진행 중 메모리 변화 확인 불가
+3. **디버깅 어려움**: 메모리 저장/검색 과정 추적 어려움
+
+### 1.2 해결 방향
+
+**Web Viewer UI**:
+- HTTP API 서버 (localhost:37777)
+- 실시간 메모리 스트림 대시보드
+- 세션/프로젝트별 탐색 인터페이스
+
+## 2. 핵심 개념
+
+### 2.1 시스템 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Claude Code                              │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ Hooks   │  │ CLI     │  │ Memory  │  │ Web     │        │
+│  │         │  │         │  │ Service │  │ Server  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+│       └────────────┴────────────┴────────────┘              │
+│                          │                                   │
+└──────────────────────────┼───────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Web Server (Bun)                          │
+│                    localhost:37777                           │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │ REST API    │  │ WebSocket   │  │ Static      │         │
+│  │ /api/*      │  │ /ws         │  │ /           │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Web Browser                               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Memory Dashboard                                    │   │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │   │
+│  │  │ Sessions │  │ Timeline │  │ Search   │          │   │
+│  │  └──────────┘  └──────────┘  └──────────┘          │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| **Session Browser** | 세션 목록, 세션별 이벤트 탐색 |
+| **Memory Timeline** | 시간순 메모리 스트림 (실시간) |
+| **Search Interface** | 벡터 검색 + 필터링 |
+| **Stats Dashboard** | 저장소 통계, 사용량 |
+| **Debug View** | Outbox 상태, 임베딩 진행률 |
+| **Settings** | 설정 조회/수정 |
+
+### 2.3 포트 및 경로
+
+```
+http://localhost:37777
+├── /                    # 대시보드 메인
+├── /sessions            # 세션 목록
+├── /sessions/:id        # 세션 상세
+├── /timeline            # 실시간 타임라인
+├── /search              # 검색 인터페이스
+├── /stats               # 통계
+├── /settings            # 설정
+└── /api                 # REST API
+    ├── /api/sessions
+    ├── /api/events
+    ├── /api/search
+    ├── /api/stats
+    └── /api/config
+```
+
+## 3. REST API 스키마
+
+### 3.1 Sessions API
+
+```typescript
+// GET /api/sessions
+interface SessionsResponse {
+  sessions: {
+    sessionId: string;
+    projectPath: string;
+    startedAt: Date;
+    endedAt?: Date;
+    eventCount: number;
+    status: 'active' | 'ended';
+  }[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+// GET /api/sessions/:id
+interface SessionDetailResponse {
+  session: {
+    sessionId: string;
+    projectPath: string;
+    startedAt: Date;
+    endedAt?: Date;
+    summary?: string;
+  };
+  events: Event[];
+  stats: {
+    promptCount: number;
+    responseCount: number;
+    toolCount: number;
+    totalTokens: number;
+  };
+}
+```
+
+### 3.2 Events API
+
+```typescript
+// GET /api/events?sessionId=xxx&type=xxx&limit=100
+interface EventsResponse {
+  events: {
+    eventId: string;
+    eventType: string;
+    timestamp: Date;
+    sessionId: string;
+    preview: string;        // 100자 미리보기
+    metadata: {
+      tokenCount?: number;
+      hasCode?: boolean;
+    };
+  }[];
+  total: number;
+}
+
+// GET /api/events/:id
+interface EventDetailResponse {
+  event: {
+    eventId: string;
+    eventType: string;
+    timestamp: Date;
+    sessionId: string;
+    payload: unknown;       // 전체 페이로드
+  };
+  related: {
+    previous?: string;
+    next?: string;
+  };
+}
+```
+
+### 3.3 Search API
+
+```typescript
+// POST /api/search
+interface SearchRequest {
+  query: string;
+  filters?: {
+    sessionId?: string;
+    eventType?: string[];
+    dateFrom?: Date;
+    dateTo?: Date;
+  };
+  options?: {
+    topK?: number;
+    minScore?: number;
+    progressive?: boolean;
+  };
+}
+
+interface SearchResponse {
+  results: {
+    id: string;
+    score: number;
+    type: string;
+    timestamp: Date;
+    sessionId: string;
+    preview: string;
+    highlight?: string;     // 매칭된 부분 강조
+  }[];
+  meta: {
+    totalMatches: number;
+    searchTime: number;
+    mode: 'vector' | 'fts' | 'hybrid';
+  };
+}
+```
+
+### 3.4 Stats API
+
+```typescript
+// GET /api/stats
+interface StatsResponse {
+  storage: {
+    eventCount: number;
+    vectorCount: number;
+    dbSizeMB: number;
+    vectorSizeMB: number;
+  };
+  sessions: {
+    total: number;
+    active: number;
+    thisWeek: number;
+  };
+  embeddings: {
+    pending: number;
+    processed: number;
+    failed: number;
+    avgProcessTime: number;
+  };
+  memory: {
+    heapUsed: number;
+    heapTotal: number;
+  };
+}
+
+// GET /api/stats/timeline
+interface TimelineStatsResponse {
+  daily: {
+    date: string;
+    eventCount: number;
+    sessionCount: number;
+  }[];
+}
+```
+
+### 3.5 Config API
+
+```typescript
+// GET /api/config
+interface ConfigResponse {
+  config: MemoryConfig;
+  editable: string[];      // 수정 가능한 필드 목록
+}
+
+// PATCH /api/config
+interface ConfigUpdateRequest {
+  updates: Partial<MemoryConfig>;
+}
+
+interface ConfigUpdateResponse {
+  success: boolean;
+  config: MemoryConfig;
+  restartRequired?: boolean;
+}
+```
+
+## 4. WebSocket 인터페이스
+
+### 4.1 실시간 이벤트 스트림
+
+```typescript
+// 연결: ws://localhost:37777/ws
+
+// 클라이언트 → 서버 메시지
+interface WSClientMessage {
+  type: 'subscribe' | 'unsubscribe';
+  channels: ('events' | 'stats' | 'outbox')[];
+  filters?: {
+    sessionId?: string;
+    eventType?: string[];
+  };
+}
+
+// 서버 → 클라이언트 메시지
+interface WSServerMessage {
+  channel: 'events' | 'stats' | 'outbox';
+  data: EventMessage | StatsMessage | OutboxMessage;
+}
+
+interface EventMessage {
+  type: 'new_event';
+  event: {
+    eventId: string;
+    eventType: string;
+    timestamp: Date;
+    sessionId: string;
+    preview: string;
+  };
+}
+
+interface OutboxMessage {
+  type: 'outbox_update';
+  pending: number;
+  processing: string[];
+  completed: string[];
+  failed: string[];
+}
+```
+
+### 4.2 연결 예시
+
+```typescript
+// 클라이언트 코드
+const ws = new WebSocket('ws://localhost:37777/ws');
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'subscribe',
+    channels: ['events', 'outbox']
+  }));
+};
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.channel === 'events') {
+    addToTimeline(msg.data.event);
+  } else if (msg.channel === 'outbox') {
+    updateOutboxStatus(msg.data);
+  }
+};
+```
+
+## 5. UI 컴포넌트
+
+### 5.1 대시보드 레이아웃
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  🧠 Code Memory                           [Search] [Settings]│
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌───────────────────────────────────────┐ │
+│  │             │  │                                       │ │
+│  │  Sessions   │  │           Main Content Area           │ │
+│  │  ─────────  │  │                                       │ │
+│  │  > session1 │  │   - Timeline View                     │ │
+│  │    session2 │  │   - Search Results                    │ │
+│  │    session3 │  │   - Session Details                   │ │
+│  │    ...      │  │   - Stats Dashboard                   │ │
+│  │             │  │                                       │ │
+│  │  ─────────  │  │                                       │ │
+│  │  Projects   │  │                                       │ │
+│  │  > project1 │  │                                       │ │
+│  │    project2 │  │                                       │ │
+│  │             │  │                                       │ │
+│  └─────────────┘  └───────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────────┤
+│  Events: 1,234  │  Vectors: 987  │  Outbox: 5 pending      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 Timeline View
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  📅 Timeline                    [Filter ▼] [Live ●]         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ○─── 14:35 ───────────────────────────────────────────────│
+│  │                                                          │
+│  │  💬 User Prompt                                          │
+│  │  "DuckDB 스키마를 어떻게 설계할까요?"                      │
+│  │                                                          │
+│  ○─── 14:36 ───────────────────────────────────────────────│
+│  │                                                          │
+│  │  🛠️ Tool: Read                                           │
+│  │  /src/core/event-store.ts                               │
+│  │                                                          │
+│  ○─── 14:37 ───────────────────────────────────────────────│
+│  │                                                          │
+│  │  🤖 Assistant Response                                   │
+│  │  "DuckDB를 사용하여 이벤트 소싱 패턴을..."               │
+│  │  [Show Full] [Copy]                                      │
+│  │                                                          │
+│  ○─── 14:40 ───────────────────────────────────────────────│
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.3 Search View
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  🔍 Search                                                   │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Type to search memories...                          │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Filters: [All Types ▼] [All Sessions ▼] [Date Range ▼]    │
+│                                                              │
+│  ─────────────────────────────────────────────────────────  │
+│                                                              │
+│  📄 Result 1 (score: 0.94)                                  │
+│  Session: abc123 │ 2026-01-30 14:05                         │
+│  "DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 방법을..."   │
+│  [View] [Timeline] [Copy ID]                                │
+│                                                              │
+│  📄 Result 2 (score: 0.87)                                  │
+│  Session: def456 │ 2026-01-29 10:20                         │
+│  "타입 시스템 리팩토링 시 고려할 점..."                      │
+│  [View] [Timeline] [Copy ID]                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.4 Stats Dashboard
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  📊 Statistics                           [Refresh] [Export] │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Events     │  │   Vectors    │  │   Sessions   │      │
+│  │    1,234     │  │     987      │  │      45      │      │
+│  │   ↑12 today  │  │   ↑8 today   │  │   3 active   │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│                                                              │
+│  Storage                                                     │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ DuckDB  [████████░░] 156 MB / 500 MB               │   │
+│  │ LanceDB [███░░░░░░░]  45 MB / 500 MB               │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Embedding Pipeline                                          │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Pending: 5  │  Processing: 2  │  Failed: 0          │   │
+│  │ Avg Time: 125ms                                      │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Activity (Last 7 Days)                                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │     ▂▄█▆▃▂▄                                          │   │
+│  │    Mon Tue Wed Thu Fri Sat Sun                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 6. 기술 스택
+
+### 6.1 서버
+
+| 컴포넌트 | 기술 | 이유 |
+|----------|------|------|
+| HTTP Server | Bun.serve | 빠른 성능, 번들 불필요 |
+| WebSocket | Bun WebSocket | 내장 지원 |
+| Router | Hono | 경량, Bun 최적화 |
+
+### 6.2 클라이언트
+
+| 컴포넌트 | 기술 | 이유 |
+|----------|------|------|
+| UI Framework | Preact + HTM | 번들 크기 최소 |
+| Styling | Tailwind CSS | 빠른 개발 |
+| State | Signals | 경량 반응성 |
+| Charts | Chart.js | 간단한 통계 시각화 |
+
+### 6.3 대안
+
+| 옵션 | 장점 | 단점 |
+|------|------|------|
+| React + Vite | 생태계 | 번들 크기 |
+| Vue 3 | 간결함 | 추가 학습 |
+| Svelte | 번들 최소 | 생태계 작음 |
+| **Preact + HTM** | 초경량, JSX 없이 | 생태계 제한 |
+
+## 7. 보안
+
+### 7.1 접근 제어
+
+```typescript
+// localhost만 허용
+const server = Bun.serve({
+  hostname: '127.0.0.1',  // localhost만
+  port: 37777,
+  // ...
+});
+
+// 또는 토큰 기반
+const AUTH_TOKEN = process.env.MEMORY_VIEWER_TOKEN;
+
+function authMiddleware(req: Request): boolean {
+  const token = req.headers.get('Authorization');
+  return token === `Bearer ${AUTH_TOKEN}`;
+}
+```
+
+### 7.2 민감 정보 필터링
+
+```typescript
+// API 응답에서 민감 정보 제거
+function sanitizeEvent(event: Event): SanitizedEvent {
+  return {
+    ...event,
+    payload: maskSensitiveFields(event.payload)
+  };
+}
+```
+
+## 8. 성공 기준
+
+- [ ] localhost:37777에서 대시보드 접근 가능
+- [ ] 세션 목록 및 상세 조회 동작
+- [ ] 실시간 이벤트 스트림 표시
+- [ ] 검색 기능 동작 (벡터 + FTS)
+- [ ] 통계 대시보드 표시
+- [ ] WebSocket 연결 안정적
+- [ ] 첫 로드 < 1초
+- [ ] API 응답 < 200ms