# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
npm run dev           # 로컬 개발 (wrangler dev)
npm run deploy        # Cloudflare Workers 배포
npm run db:init       # D1 스키마 초기화 (production)
npm run db:init:local # D1 스키마 초기화 (local)
npm run tail          # Workers 로그 스트리밍
```

**Secrets 설정**:
```bash
wrangler secret put BOT_TOKEN        # Telegram Bot Token
wrangler secret put WEBHOOK_SECRET   # Webhook 검증용
wrangler secret put OPENAI_API_KEY   # OpenAI API 키
```

## Architecture

**Message Flow**:
```
Telegram Webhook → Security Validation → Command/Message Router
                                              ↓
                   ┌──────────────────────────┴──────────────────────────┐
                   ↓                                                      ↓
            Command Handler                                    AI Response Generator
            (commands.ts)                                      (openai-service.ts)
                                                                      ↓
                                                              Function Calling
                                                    (weather, search, time, calc, docs)
                                                                      ↓
                                                              Profile System
                                                            (summary-service.ts)
```

**Core Services**:
- `openai-service.ts` - GPT-4o-mini + Function Calling (6개 도구: weather, search, time, calculate, lookup_docs, manage_domain)
- `summary-service.ts` - 메시지 버퍼링 + 20개마다 프로필 추출 (슬라이딩 윈도우 3개)
- `security.ts` - Webhook 검증 (timing-safe comparison, timestamp validation, rate limiting 30req/min)
- `commands.ts` - 봇 명령어 핸들러 (/start, /help, /profile, /reset, /context, /stats, /debug)

**Data Layer** (D1 SQLite):
- `users` - telegram_id 기반 사용자
- `message_buffer` - 롤링 대화 기록
- `summaries` - 프로필 버전 관리 (generation 추적)

**AI Fallback**: OpenAI 미설정 시 Workers AI (Llama 3.1 8B) 자동 전환

## Key Patterns

**Function Calling**: `openai-service.ts`의 `tools` 배열에 JSON Schema 정의, `executeFunctionCall()`에서 실행

**Profile System**: 매 20개 메시지마다 사용자 발언 분석 → 관심사/목표/맥락 추출 → summaries 테이블에 generation 증가하며 저장

**Context Enrichment**: `getConversationContext()`로 이전 프로필 + 최근 10개 메시지 조합하여 AI 프롬프트에 포함

## Configuration

`wrangler.toml` 환경변수:
- `SUMMARY_THRESHOLD`: 프로필 업데이트 주기 (기본 20)
- `MAX_SUMMARIES_PER_USER`: 유지할 프로필 버전 수 (기본 3)
- `DOMAIN_AGENT_ID`: OpenAI Assistant ID (도메인 관리 에이전트)
- `DOMAIN_OWNER_ID`: 도메인 관리 권한 Telegram ID (소유권 검증용)

## External Integrations

- **Context7 API**: `lookup_docs` 함수로 라이브러리 문서 조회
- **Domain Agent**: `manage_domain` 함수 → OpenAI Assistants API (`asst_MzPFKoqt7V4w6bc0UwcXU4ob`)
- **Namecheap API**: `https://namecheap-api.anvil.it.com` (Domain Agent 백엔드)
- **wttr.in**: 날씨 API
- **DuckDuckGo**: 웹 검색 API
- **Vault**: `vault.anvil.it.com`에서 API 키 중앙 관리