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 접근 권한)

환경 변수 설정

cp backend/.env.example backend/.env

AWS_REGION=us-east-1
BEDROCK_MODEL_ID=global.anthropic.claude-sonnet-4-6
PORT=3001

설치 및 실행

# Backend
cd backend
npm install
npm run dev          # http://localhost:3001

# Frontend (별도 터미널)
cd frontend
npm install
npm run dev          # http://localhost:5173

빌드

# 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	세션별 메시지 삭제

채팅 요청 예시

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	에러 발생

테스트

# Backend 테스트
cd backend
npm test
npm run test:watch   # watch 모드

# Frontend 테스트
cd frontend
npm test
npm run test:watch   # watch 모드