How tndkkim/clovista works
이 프로젝트를 “무엇”으로 보고 그릴지 (프로젝트 타입/목적)
이 레포는 인플루언서 지원 AI 서비스(CLOVISTA)의 해커톤 결과물로 보이며, 형태는 전형적인 Full-stack + AI/LLM 백엔드 + 데이터 수집 파이프라인 구조입니다.
• Frontend: frontend/ (React SPA)
• Backend API: rest_api/ (FastAPI, 라우터 분리)
• LLM/Prompt 기반 기능: prompts/, rest_api/clova_api.py (HyperCLOVA X 연동 추정)
• 데이터 수집/DB 구축(크롤링): core/crawler/*.ipynb (YouTube Data API 기반 수집 + DB insert)
• 분석/모델링/전처리 파이프라인:
• 댓글/반응/논란 가능성(감성/민감도) 실험: core/sensitivity/*.ipynb
• 컨텍스트 청킹/전처리: context_chunking/
• “내 채널 분석”/지표 계산/가공: prs_cns/data_processing.py
따라서 다이어그램은 (1) 런타임 서비스 아키텍처와 (2) 오프라인 데이터 파이프라인/모델 실험을 분리해서 그리는 게 가장 정확합니다(한 장에 다 넣으면 복잡도가 급상승).
파일 트리 기반으로 뽑는 “주요 컴포넌트” 목록 (박스 후보)
아키텍처 다이어그램에서 박스로 분해할 단위(최대한 쪼개기):
API / Application Layer
• FastAPI Server: rest_api/api.py
• Routers (기능별 API 경계): rest_api/routers/
• chatbot_router.py : 챗봇/대화형 기능
• dashboard_router.py : “내 채널 분석” 대시보드
• recommend_router.py : 추천/가이드 생성
• sensitive_router.py : 논란 가능성/민감도 분석
> 다이어그램에서 “FastAPI” 박스 안에 Router들을 서브박스로 넣으면, 실제 코드 구조와 가장 잘 맞습니다.
AI / LLM Integration
• CLOVA / HyperCLOVA X Client: rest_api/clova_api.py
• Prompt Templates: prompts/
• recommend_prompt.py, sensitivity_prompt.py, prs_cns_prompt.py
Data / Storage (명시 파일은 없지만 README/노트북으로 강하게 암시)
• PostgreSQL DB: README에 “PostgreSQL을 통해 관계형 DB 구축”
• (선택) Object Storage / File Storage: context_chunking/data/* 로컬 파일이지만 운영 관점에선 스토리지로 표현 가능
Offline Pipelines / Jobs (노트북/스크립트)
• YouTube Data Collector: core/crawler/youtube_data_api*.ipynb
• DB Insert Jobs: core/crawler/db_insert*.ipynb
• Sensitivity Experiments / Classifier: core/sensitivity/*.ipynb
• Context Chunking + Preprocess: context_chunking/context_chunking.py, stt_result_preprocess.py
• PRS/CNS Data Processing: prs_cns/data_processing.py
External Systems
• YouTube Data API (외부)
• HyperCLOVA X API (외부)
관계/상호작용(화살표) “정답” 구조
Principal 레벨 다이어그램은 화살표가 “누가 누구를 호출하고 무엇이 오가는지”가 핵심입니다.
User Browser
→ React SPA (frontend)
→ FastAPI (rest_api/api.py)
→ (기능별) Router
→ (필요시) PostgreSQL 조회/저장
→ (필요시) CLOVA API (clova_api.py) + Prompt
→ 결과 반환
→ React가 렌더링
• 챗봇: SurveyChatbot 화면 → chatbot_router → clova_api(+ prompts) → 응답
• 논란 분석: Sense 화면 → sensitive_router → (규칙/모델/LLM) → 점수/근거/가이드
• 추천: recommend_router → prompt 기반 생성
• 대시보드: dashboard_router → DB에서 채널/댓글/지표 로딩 → 요약/시각화 데이터 반환
YouTube Data API
→ Crawler Notebooks (core/crawler)
→ PostgreSQL DB
(선택) STT 결과/텍스트 파일
→ context_chunking/stt_result_preprocess.py
→ context_chunking/context_chunking.py
→ (산출물) context_chunking/data/processed/*
→ (필요 시) DB 적재 또는 LLM 입력 컨텍스트로 사용
Model/Experiment Notebooks (core/sensitivity)
→ 평가/피처/라벨링/규칙 산출
→ (운영 반영 시) rest_api/routers/sensitive_router.py 로직/프롬프트에 반영
> 오프라인 파이프라인은 “스케줄러(크론, Airflow 등)”가 파일트리에 없으므로, 다이어그램에서는 Manual/Notebook Job 또는 Batch Job(운영 전환 가능) 형태로 표현하면 정확합니다.
이 프로젝트에서 강조해야 할 아키텍처 패턴/원칙
다이어그램에 드러나야 “이 레포를 제대로 읽었다”가 됩니다.
Frontend–Backend 분리 (SPA + REST API)
• frontend/ 와 rest_api/가 강하게 분리됨
Backend 내부의 Router 기반 수직 분할
• 기능 도메인 단위로 API 경계가 나뉨 (chatbot/dashboard/recommend/sensitive)
LLM Orchestration (Prompt + LLM Client)
• prompts/는 “템플릿 저장소”, clova_api.py는 “실제 호출 어댑터”
• Router → Prompt 선택/조립 → LLM 호출의 흐름을 박스로 표현
데이터 수집/분석은 서비스 런타임과 분리된 Batch 영역
• 크롤러/실험은 core/와 노트북으로 분리되어 있어, “운영 API 서버”와 다른 생명주기임
다이어그램을 “어떤 수준”으로 몇 장 그리면 가장 정확한가
한 장에 끝내려 하지 말고, 3장 세트를 추천합니다(이 레포 구조에 최적).
박스:
• User/Browser
• React Frontend
• FastAPI Backend
• PostgreSQL
• HyperCLOVA X API
• YouTube Data API
화살표:
• Browser ↔ Frontend ↔ Backend
• Backend ↔ DB
• Backend ↔ HyperCLOVA X
• Crawler/Batch ↔ YouTube API ↔ DB
FastAPI 박스 내부를 세분:
• api.py (App entry)
• Routers 4개
• clova_api.py (LLM adapter)
• prompts/ (template library)
• (선택) “Service Layer”를 논리 박스로 추가: 현재 코드상 디렉토리는 없지만, Router가 비즈니스 로직을 들고 있을 가능성이 크니 Router→(Service)→(DB/LLM)로 논리 분리해서 그리면 “확장 가능한 설계”를 보여줄 수 있음(현 코드와 불일치가 걱정이면 점선 박스로 표기)
• YouTube API → crawler notebooks → PostgreSQL
• sensitivity experiments → (결과/규칙/모델) → sensitive_router 반영(점선)
• context_chunking preprocess → processed text → (DB 적재 or LLM 컨텍스트 입력) (점선)
컴포넌트를 “최대한 많이” 쪼개서 그리는 요령 (이 레포 기준)
요구사항(“가능한 많이 컴포넌트 분리”)에 맞춰, 박스 분해 기준을 명확히 하세요.
• Frontend는 화면/기능 단위로:
• Auth 영역: Login, Signup, LoginPopup
• 진단/분석: Sense, Sense_List, Sense_Result
• 설문/챗봇: Survey, SurveyChatbot
• SWOT: Swot, Swot_*
• 공통: Loader, PopupGuide, Identity
• (단, 시스템 다이어그램에서는 “Frontend 내부 상세”는 별도 서브 다이어그램로)
• Backend는 라우터=서비스 도메인 단위로:
• Chatbot Service
• Dashboard Service
• Recommendation Service
• Sensitivity Service
• LLM은 “Prompt”와 “Provider Adapter”를 분리:
• Prompt Repository (prompts)
• LLM Gateway/Adapter (clova_api.py)
• LLM Provider (HyperCLOVA X, 외부)
• 데이터는 “원천/가공/서빙”으로 분리:
• YouTube 원천 데이터
• DB (서빙용)
• STT/텍스트 파일 (원천/가공 산출물)
다이어그램 표기 규칙(라벨, 화살표, 색/도형) — 이 프로젝트에 맞춘 추천
Principal 엔지니어가 보는 다이어그램이라면 표준화가 중요합니다.
라벨링
• 박스 이름에 폴더/파일 근거를 괄호로 표기:
• “FastAPI API Server (rest_api/api.py)”
• “Sensitivity Router (rest_api/routers/sensitive_router.py)”
• “Prompt Templates (prompts/)”
• “Crawler Jobs (core/crawler/*.ipynb)”
화살표(방향/데이터 타입)
• 실선: 런타임 트래픽
• 점선: 오프라인 산출물이 런타임 로직에 “반영됨”(실험 결과/프롬프트 개선 등)
• 화살표 라벨 예시:
• “HTTP/JSON”
• “SQL”
• “LLM Inference Request/Response”
• “Batch ingest (video/comments metadata)”
색/도형
• 색상 추천(의미 고정):
• 파란색: 런타임 서비스(Frontend/Backend)
• 초록색: 데이터 저장소(DB/파일 스토리지)
• 보라색: AI/LLM 컴포넌트(prompts, clova adapter, external LLM)
• 주황색: 배치/노트북/실험 파이프라인(core/, context_chunking/)
• 도형:
• 실린더: DB
• 둥근 사각형: 서비스/컨테이너
• 문서 아이콘: 노트북/배치 스크립트
• 클라우드: 외부 API (YouTube, HyperCLOVA X)
마지막 체크리스트 (정확도 높이는 검증 포인트)
• [ ] frontend → rest_api 호출 경로가 명확한가 (단방향/양방향 혼동 X)
• [ ] Router 4종이 다이어그램에 모두 등장하는가
• [ ] prompts/와 clova_api.py가 “LLM 연동 레이어”로 분리돼 있는가
• [ ] DB는 “크롤러가 채우고 API가 읽는다”가 보이는가
• [ ] 노트북/실험은 운영 트래픽과 분리(점선/별도 영역)했는가
• [ ] 아직 레포에 없는 요소(배포, 큐, 스케줄러)를 단정적으로 그리지 않았는가
• 필요하면 “Future/Optional” 레이어로 점선 표기
추천 산출물 형태
• 1페이지 요약(High-level) + 1페이지 Backend 상세 + 1페이지 Offline 파이프라인