https://github.com/claude-code-expert/chatbot
https://github.com/claude-code-expert/chatbot
Last synced: about 12 hours ago
JSON representation
- Host: GitHub
- URL: https://github.com/claude-code-expert/chatbot
- Owner: claude-code-expert
- Created: 2026-02-03T03:21:08.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T00:14:24.000Z (4 months ago)
- Last Synced: 2026-03-21T15:52:58.693Z (4 months ago)
- Language: TypeScript
- Size: 139 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# AI Chatbot
AWS Bedrock의 Claude 모델을 활용한 웹 기반 AI 챗봇 애플리케이션입니다.
실시간 스트리밍 응답과 도구 사용(Tool Use)을 지원합니다.
## 기술 스택
| 구분 | 기술 |
|------|------|
| Frontend | React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui |
| Backend | Node.js, Express 5, TypeScript |
| AI | AWS Bedrock (Claude Sonnet 4.6 / Haiku 4.5) |
| API | Converse API + ConverseStream |
| 스트리밍 | Server-Sent Events (SSE) |
| 테스트 | Jest (backend), Vitest (frontend) |
## 아키텍처
```
React (Vite) → Express API → AWS Bedrock
↑ ↓
└── SSE 스트리밍 ──┘
```
**3-tier 구조**: 프론트엔드가 Express 서버에 요청을 보내고, 서버가 AWS Bedrock API를 호출하여 SSE로 응답을 스트리밍합니다.
## 프로젝트 구조
```
chatbot/
├── frontend/ # React 클라이언트
│ └── src/
│ ├── components/
│ │ ├── chat/ # MessageList, MessageInput, MarkdownRenderer, ToolResult
│ │ ├── layout/ # Header, Sidebar, Layout
│ │ └── ui/ # button, card, scroll-area, textarea (shadcn/ui)
│ ├── hooks/ # useChat, useSession, useTheme
│ ├── services/sse.ts # SSE 스트리밍 클라이언트
│ └── types/
├── backend/ # Express 서버
│ └── src/
│ ├── config/ # systemPrompt (페르소나)
│ ├── middleware/ # errorHandler, requestLogger
│ ├── routes/ # chat (SSE), sessions (CRUD)
│ ├── services/ # bedrock, sessionManager, messageHistory, toolOrchestrator
│ ├── tools/ # calculator, getCurrentTime, getWeather
│ ├── types/ # Message, Session, Tool 인터페이스
│ └── utils/ # fallback, permission, retry, timeout, validation
│ └── tests/ # 단위/통합 테스트
└── docs/ # 와이어프레임 등
```
## 주요 기능
### 실시간 스트리밍 채팅
- SSE를 통한 토큰 단위 실시간 응답
- 스트리밍 취소 지원 (AbortController)
### 도구 사용 (Tool Use)
Claude가 자동으로 도구를 선택하여 실행합니다:
- **calculator** - 수학 수식 계산 (사칙연산, 거듭제곱, 제곱근)
- **get_current_time** - 타임존별 현재 시간 조회
- **get_weather** - 도시별 현재 날씨 조회 (Open-Meteo API)
### 세션 관리
- 다중 채팅 세션 생성/조회/수정/삭제
- 세션별 메시지 히스토리 관리 (인메모리)
- user-assistant 쌍 단위 히스토리 트리밍
### UI
- 다크/라이트 테마 전환
- Markdown 렌더링 (코드 하이라이팅 포함)
- 도구 실행 상태 표시
- 사이드바 세션 목록
## 시작하기
### 사전 요구사항
- Node.js 18+
- AWS 자격증명 (Bedrock 접근 권한)
### 환경 변수 설정
```bash
cp backend/.env.example backend/.env
```
```env
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=global.anthropic.claude-sonnet-4-6
PORT=3001
```
### 설치 및 실행
```bash
# Backend
cd backend
npm install
npm run dev # http://localhost:3001
# Frontend (별도 터미널)
cd frontend
npm install
npm run dev # http://localhost:5173
```
### 빌드
```bash
# Backend
cd backend
npm run build # dist/ 출력
# Frontend
cd frontend
npm run build # dist/ 출력
```
## API 엔드포인트
| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/health` | 헬스 체크 |
| POST | `/api/chat` | 채팅 (SSE 스트리밍) |
| POST | `/api/sessions` | 세션 생성 |
| GET | `/api/sessions` | 전체 세션 조회 |
| GET | `/api/sessions/:id` | 세션 조회 |
| PUT | `/api/sessions/:id` | 세션 수정 |
| DELETE | `/api/sessions/:id` | 세션 삭제 |
| GET | `/api/sessions/:id/messages` | 세션별 메시지 조회 |
| DELETE | `/api/sessions/:id/messages` | 세션별 메시지 삭제 |
### 채팅 요청 예시
```bash
curl -N -X POST http://localhost:3001/api/chat \
-H "Content-Type: application/json" \
-d '{"sessionId": "test-session", "message": "안녕하세요"}'
```
### SSE 이벤트 타입
| 이벤트 | 설명 |
|--------|------|
| `text` | 텍스트 토큰 스트리밍 |
| `tool_start` | 도구 실행 시작 |
| `tool_delta` | 도구 입력 스트리밍 |
| `tool_result` | 도구 실행 결과 |
| `done` | 응답 완료 (토큰 사용량 포함) |
| `error` | 에러 발생 |
## 테스트
```bash
# Backend 테스트
cd backend
npm test
npm run test:watch # watch 모드
# Frontend 테스트
cd frontend
npm test
npm run test:watch # watch 모드
```