2. 코드 전수 분석

TL;DR

KSEL 7-KPI 평가용 풀스택 모놀리식 PoC. FastAPI 백엔드 + React 19 SPA + nginx 정적 + Claude Agent SDK 통합. 단일 EC2 (t4g.xlarge AL2023) · alpha push → GitHub Actions → rsync → Infisical export → rolling restart → smoke (deploy_id 일치). 3-tier requirements (vercel stub / EC2 real / dev) 로 250MB Vercel 제약과 ~7GB HF 모델을 같은 코드베이스에서 처리.

2.1 레포 구조

2.2 백엔드 핵심

진입점

FastAPI app

src/api.py:235 — title "TIPS R&D KPI Evaluation API" v0.6.0

Vercel 진입

api/index.py — builder 가 app 심볼 인식

로컬

uvicorn src.api:app --host 0.0.0.0 --port 8000

전역 시드

SEED=20260514 — KPI별 stub 결정성

미들웨어

x-request-id 주입 · CORS · 구조화 로깅 ContextVar

7 KPI 구현 매트릭스

AI 모델 어댑터 (src/ai_clients/)

공통 베이스 _base.py::BaseClient ABC. SDK 없이도 import 성공, 호출 시점만 NotImplementedError.

Claude Agent (/api/chat, /api/agent/*)

구현

src/agents/financial_agent.py::FinancialAgent

모델

기본 claude-opus-4-7 · max_tokens 4096 · effort "high" · max_turns 6 (운영은 sonnet-4-5)

Prompt cache

시스템 + 8 도구에 cache_control={"type":"ephemeral"} — ~10× 절감

Fallback

Claude → OpenAI gpt-4o-mini → canned 응답

등록 8 도구 (src/agents/tools.py)

1. get_portfolio_overview
2. get_recent_transactions
3. classify_intent (KPI ②)
4. recommend_products (KPI ⑦)
5. simulate_financial_plan
6. search_finance_knowledge (KPI ⑥)
7. calculate_dti_ltv
8. classify_finance_scenario (KPI ①)

측정 결과 & 로깅

• 결과 파일: RESULTS_DIR=/app/results · {kpi_id}_{UTC}.json
• NDJSON: KPI_NDJSON_DUMP=1 시 /tmp/results/runs/{run_id}.ndjson
• 로깅: JsonFormatter 한 줄 JSON · ContextVar (request_id / run_id / kpi)
• 이벤트: api.boot · api.request.done · kpi.bulk.{start,progress,done} · kpi.single.measured · result.saved

페르소나 6명 (api/personas_data.py)

2.3 프론트엔드 (React 19 SPA)

스택

프레임워크

React 19.0.0 · Vite 6.0.0 · TS 5.6.0 · pnpm 10.20

라우팅

react-router-dom 7.1

상태

React Context × 3 + TanStack Query 5.59

스타일

Tailwind CSS 4.0 (Vite plugin)

차트

recharts 3.8.1

CSV

papaparse 5.5.3

4 페이지 + KPI 매핑

측정 컨텍스트 (3 Context)

• PersonaContext — localStorage + StorageEvent 멀티탭 동기화
• KpiHistoryContext — 대화별 KPI ①②③⑤⑥ 누적 (~500건)
• Kpi4MeasurementContext — 1분×5회 정밀 검증 백그라운드 보존

SSE 구현: EventSource 미사용. POST + ReadableStream 직접 파싱 (AbortController 호환). 이벤트 타입 — text_delta · thinking_delta · tool_use_start · done.

2.4 인프라 · CI/CD

워크플로

배포 흐름 (scripts/deploy.sh)

1. SSH 키 로드 (webfactory/ssh-agent)
2. rsync 동기화 (.git/node_modules/.env* 제외)
3. 원격 infisical export --env=beta --path=/fingu-tips --format=dotenv → .env
4. DEPLOY_ID=${{github.sha}} append
5. docker compose build --quiet → rolling restart (api healthcheck wait → web)
6. 외부 smoke — /api/health.deploy_id == github.sha 매칭 (5회 지수백오프)

Requirements 3-tier

nginx (nginx.conf)

• HTTP/2 활성 · TLS 1.2/1.3 · Cloudflare Origin cert (/etc/nginx/certs/origin.{crt,key})
• access log masked: $request 대신 $request_method $uri $server_protocol
• /api/ → http://fingu_api:8001 · keepalive 32 · timeout 90s
• 정적 자산 Cache-Control: max-age=604800, immutable
• SPA fallback try_files $uri $uri/ /index.html

2.5 테스트 · 증빙 · 데이터셋 (PR #62 이전)

pytest 파일

31 개 · 3,289 LOC

conftest

autouse fixture _clear_ai_secrets — 모든 AI 키 제거

contract test

test_kpi_contract.py — 7 KPI parametrize · MIN_SAMPLES KSEL 기준 일치

메트릭 단위

test_f1_score · test_bleu · test_nq_em · test_llm_rec_score · test_throughput

CI

pytest tests/ -x --tb=short -q --timeout=30 \|\| true — 실패해도 통과 (PR #62에서 보강)

데이터셋 (15,050 sample)

evidence/

• Technical-overview-of-data-collection-and-model-fine-tuning.pdf 211 KB
• KSEL_시험의뢰서_2026-05-08.docx 21 KB (제출 완료)
• TIPS_성능평가_의뢰서_참고자료_2026-05-08.docx 15 KB

2.6 API 라우트 전체