# tndkkim/clovista architecture

> Architecture diagram of the GitHub repository tndkkim/clovista, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tndkkim/clovista
- Repository: https://github.com/tndkkim/clovista

## Overview

##### 이 프로젝트를 “무엇”으로 보고 그릴지 (프로젝트 타입/목적)
이 레포는 **인플루언서 지원 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 파이프라인

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1) High-level Context (C4 L1)
  %% =========================
  subgraph D1["Diagram 1 — High-level Runtime Context (C4 L1)"]
    direction TB

    U["User / Browser"]:::external
    FE["Web Client (React SPA)"]:::frontend
    BE["FastAPI Backend API"]:::backend
    DB[("PostgreSQL DB")]:::data
    YT["YouTube Data API"]:::external
    LLM["HyperCLOVA X API"]:::external

    U -->|"HTTPS"| FE
    FE -->|"HTTP/JSON"| BE
    BE -->|"SQL"| DB
    BE -->|"LLMInferenceReq/Res"| LLM
  end

  %% =========================
  %% Diagram 2) Backend Container/Component (C4 L2~L3)
  %% =========================
  subgraph D2["Diagram 2 — Backend Container/Component (C4 L2~L3)"]
    direction TB

    subgraph BEBOX["FastAPI API Server"]
      direction TB
      APIENTRY["App Entry (api.py)"]:::backend

      subgraph ROUTERS["Routers (domain boundaries)"]
        direction TB
        R_CHAT["Chatbot Router"]:::api
        R_DASH["Dashboard Router"]:::api
        R_REC["Recommendation Router"]:::api
        R_SENS["Sensitivity Router"]:::api
      end

      subgraph LLMINT["LLM Orchestration"]
        direction TB
        CLOVA["CLOVA Client Adapter (clova_api.py)"]:::llm

        subgraph PROMPTS["Prompt Templates Repository (prompts/)"]
          direction TB
          P_REC["recommend_prompt.py"]:::llm
          P_SENS["sensitivity_prompt.py"]:::llm
          P_PRS["prs_cns_prompt.py"]:::llm
        end
      end

      SVC["(Optional) Service Layer\n(logical separation; may live in routers)"]:::optional

      APIENTRY -->|"mount"| R_CHAT
      APIENTRY -->|"mount"| R_DASH
      APIENTRY -->|"mount"| R_REC
      APIENTRY -->|"mount"| R_SENS

      R_CHAT -->|"calls"| SVC
      R_DASH -->|"calls"| SVC
      R_REC -->|"calls"| SVC
      R_SENS -->|"calls"| SVC

      SVC -->|"reads/writes"| DB
      SVC -->|"selectsPrompt"| PROMPTS
      SVC -->|"LLMcall"| CLOVA
      CLOVA -->|"LLMInferenceReq/Res"| LLM

      R_CHAT -->|"promptUse"| P_REC
      R_REC -->|"promptUse"| P_REC
      R_SENS -->|"promptUse"| P_SENS
      R_DASH -->|"promptUse"| P_PRS
    end

    FE -->|"HTTP/JSON"| APIENTRY
  end

  %% =========================
  %% Diagram 3) Offline Data/ML Pipeline
  %% =========================
  subgraph D3["Diagram 3 — Offline Data/ML/ETL Pipelines (Batch/Notebook)"]
    direction TB

    subgraph OFFLINE["Offline Jobs (manual/notebook; separate lifecycle)"]
      direction TB

      subgraph CRAWL["YouTube Data Collection + DB Insert (core/crawler)"]
        direction TB
        YTJOB1["youtube_data_api.ipynb"]:::batch
        YTJOB2["youtube_data_api2.ipynb"]:::batch
        INS1["db_insert.ipynb"]:::batch
        INS2["db_insert2.ipynb"]:::batch
      end

      subgraph SENSEXP["Sensitivity Experiments (core/sensitivity)"]
        direction TB
        EXP1["experiments.ipynb"]:::batch
        EXP2["sentiment_classifier.ipynb"]:::batch
        RULES["Derived rules/metrics\n(features/labels/thresholds)"]:::batchOut
      end

      subgraph CHUNK["Context Chunking + Preprocess (context_chunking)"]
        direction TB
        ORIGIN[("Raw STT/Text Files\n(context_chunking/data/origin)")]:::data
        PRE["stt_result_preprocess.py"]:::batch
        CHUNKER["context_chunking.py"]:::batch
        PROCESSED[("Processed Text Chunks\n(context_chunking/data/processed)")]:::data
      end

      subgraph PRSCNS["Channel Metrics Processing (prs_cns)"]
        direction TB
        PRSJOB["data_processing.py"]:::batch
        METRICS["Channel KPIs / Aggregates"]:::batchOut
      end
    end

    YT -->|"BatchIngest(video/comments)"| YTJOB1
    YT -->|"BatchIngest(video/comments)"| YTJOB2
    YTJOB1 -->|"extract"| INS1
    YTJOB2 -->|"extract"| INS2
    INS1 -->|"SQLinsert"| DB
    INS2 -->|"SQLinsert"| DB

    ORIGIN -->|"input"| PRE
    PRE -->|"clean/normalize"| CHUNKER
    CHUNKER -->|"write"| PROCESSED
    PROCESSED -.->|"optional:loadToDB"| DB
    PROCESSED -.->|"optional:LLMcontext"| CLOVA

    DB -->|"readForKPIs"| PRSJOB
    PRSJOB -->|"compute"| METRICS
    METRICS -->|"writeBack(optional)"| DB

    EXP1 -->|"train/evaluate"| EXP2
    EXP2 -->|"derive"| RULES
    RULES -.->|"informLogicOrPrompts"| R_SENS
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click FE "https://github.com/tndkkim/clovista/tree/main/frontend/"
  click APIENTRY "https://github.com/tndkkim/clovista/blob/main/rest_api/api.py"
  click ROUTERS "https://github.com/tndkkim/clovista/tree/main/rest_api/routers/"
  click R_CHAT "https://github.com/tndkkim/clovista/blob/main/rest_api/routers/chatbot_router.py"
  click R_DASH "https://github.com/tndkkim/clovista/blob/main/rest_api/routers/dashboard_router.py"
  click R_REC "https://github.com/tndkkim/clovista/blob/main/rest_api/routers/recommend_router.py"
  click R_SENS "https://github.com/tndkkim/clovista/blob/main/rest_api/routers/sensitive_router.py"
  click CLOVA "https://github.com/tndkkim/clovista/blob/main/rest_api/clova_api.py"
  click PROMPTS "https://github.com/tndkkim/clovista/tree/main/prompts/"
  click P_REC "https://github.com/tndkkim/clovista/blob/main/prompts/recommend_prompt.py"
  click P_SENS "https://github.com/tndkkim/clovista/blob/main/prompts/sensitivity_prompt.py"
  click P_PRS "https://github.com/tndkkim/clovista/blob/main/prompts/prs_cns_prompt.py"

  click YTJOB1 "https://github.com/tndkkim/clovista/blob/main/core/crawler/youtube_data_api.ipynb"
  click YTJOB2 "https://github.com/tndkkim/clovista/blob/main/core/crawler/youtube_data_api2.ipynb"
  click INS1 "https://github.com/tndkkim/clovista/blob/main/core/crawler/db_insert.ipynb"
  click INS2 "https://github.com/tndkkim/clovista/blob/main/core/crawler/db_insert2.ipynb"
  click EXP1 "https://github.com/tndkkim/clovista/blob/main/core/sensitivity/experiments.ipynb"
  click EXP2 "https://github.com/tndkkim/clovista/blob/main/core/sensitivity/sentiment_classifier.ipynb"
  click CHUNKER "https://github.com/tndkkim/clovista/blob/main/context_chunking/context_chunking.py"
  click PRE "https://github.com/tndkkim/clovista/blob/main/context_chunking/stt_result_preprocess.py"
  click ORIGIN "https://github.com/tndkkim/clovista/tree/main/context_chunking/data/origin/"
  click PROCESSED "https://github.com/tndkkim/clovista/tree/main/context_chunking/data/processed/"
  click PRSJOB "https://github.com/tndkkim/clovista/blob/main/prs_cns/data_processing.py"

  %% Frontend detailed mappings (kept in runtime grouping; clickable)
  FEDETAIL["Frontend Screens/Widgets (components)"]:::frontend
  FE -->|"renders"| FEDETAIL
  click FEDETAIL "https://github.com/tndkkim/clovista/tree/main/frontend/src/components/"

  APPENTRYFE["Frontend App Entry (App.js)"]:::frontend
  FE -->|"bootstraps"| APPENTRYFE
  click APPENTRYFE "https://github.com/tndkkim/clovista/blob/main/frontend/src/App.js"

  MAIN["Dashboard/Main Screen"]:::frontend
  CHATUI["Survey Chatbot Screen"]:::frontend
  SENSE["Sensitivity Screen (Sense)"]:::frontend
  SENSEL["Sensitivity List"]:::frontend
  SENSER["Sensitivity Result"]:::frontend
  SWOT["SWOT Screen"]:::frontend
  SWOTENG["SWOT Engagement"]:::frontend
  SWOTPERF["SWOT Performance"]:::frontend
  SWOTREV["SWOT Revenue"]:::frontend
  LOGIN["Login"]:::frontend
  SIGNUP["Signup"]:::frontend
  LOGINPOP["Login Popup"]:::frontend

  FEDETAIL --> MAIN
  FEDETAIL --> CHATUI
  FEDETAIL --> SENSE
  SENSE --> SENSEL
  SENSEL --> SENSER
  FEDETAIL --> SWOT
  SWOT --> SWOTENG
  SWOT --> SWOTPERF
  SWOT --> SWOTREV
  FEDETAIL --> LOGIN
  FEDETAIL --> SIGNUP
  FEDETAIL --> LOGINPOP

  CHATUI -->|"HTTP/JSON"| R_CHAT
  MAIN -->|"HTTP/JSON"| R_DASH
  SENSER -->|"HTTP/JSON"| R_SENS
  SWOTREV -->|"HTTP/JSON"| R_REC

  click CHATUI "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/SurveyChatbot.js"
  click SENSE "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Sense.js"
  click SENSEL "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Sense_List.js"
  click SENSER "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Sense_Result.js"
  click SWOT "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Swot.js"
  click SWOTENG "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Swot_Engagement.js"
  click SWOTPERF "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Swot_Performance.js"
  click SWOTREV "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Swot_Revenue.js"
  click LOGIN "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Login.js"
  click SIGNUP "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Signup.js"
  click LOGINPOP "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/LoginPopup.js"
  click MAIN "https://github.com/tndkkim/clovista/blob/main/frontend/src/components/Main.js"

  %% =========================
  %% Styles
  %% =========================
  classDef frontend fill:#1E88E5,stroke:#0D47A1,stroke-width:1.5px,color:#FFFFFF;
  classDef backend fill:#1565C0,stroke:#0D47A1,stroke-width:1.5px,color:#FFFFFF;
  classDef api fill:#1976D2,stroke:#0D47A1,stroke-width:1.5px,color:#FFFFFF;

  classDef data fill:#2E7D32,stroke:#1B5E20,stroke-width:1.5px,color:#FFFFFF;

  classDef llm fill:#6A1B9A,stroke:#4A148C,stroke-width:1.5px,color:#FFFFFF;
  classDef external fill:#546E7A,stroke:#263238,stroke-width:1.5px,color:#FFFFFF;

  classDef batch fill:#FB8C00,stroke:#E65100,stroke-width:1.5px,color:#1B1B1B;
  classDef batchOut fill:#FFB74D,stroke:#E65100,stroke-width:1.5px,color:#1B1B1B;

  classDef optional fill:#FFFFFF,stroke:#9E9E9E,stroke-width:1.5px,stroke-dasharray: 5 4,color:#424242;
```
