# CTRL-F 백엔드 아키텍처

## 1. 시스템 아키텍처 개요

```mermaid
flowchart TB
    subgraph Client["클라이언트"]
        FE["Frontend<br/>(React)"]
    end

    subgraph Gateway["API Gateway Layer"]
        GW["API Gateway<br/>:8085<br/>(Spring Cloud Gateway)"]
    end

    subgraph Backend["Backend Services"]
        CHAT["Chat Service<br/>:9005"]
        EDU["Education Service<br/>:9002"]
        INFRA["Infra Service<br/>:9003"]
    end

    subgraph External["External Services"]
        AI["AI Server<br/>:8000<br/>(FastAPI)"]
        KC["Keycloak<br/>:8090"]
    end

    subgraph Storage["Data Storage"]
        DB[("PostgreSQL<br/>:5432<br/>(pgvector)")]
        S3[("AWS S3")]
    end

    FE -->|HTTPS| GW
    GW -->|JWT 검증| KC
    GW -->|/chat/**<br/>/api/chat/**| CHAT
    GW -->|/edu/**<br/>/video/**| EDU
    GW -->|/admin/**<br/>/rag/**| INFRA
    GW -->|/auth/**| KC

    CHAT -->|WebClient| AI
    EDU -->|RestClient| AI
    EDU -->|RestClient| INFRA
    INFRA -->|RestClient| AI
    INFRA -->|RestClient| EDU
    INFRA -->|RestTemplate| KC

    CHAT --> DB
    EDU --> DB
    INFRA --> DB
    INFRA --> S3

2. 상세 서비스 아키텍처

flowchart LR
    subgraph Frontend
        REACT["React App<br/>:5173 / :3000"]
    end

    subgraph API_Gateway["API Gateway :8085"]
        direction TB
        GW_MAIN["Spring Cloud Gateway"]
        GW_SEC["OAuth2 Resource Server<br/>(JWT 검증)"]
        GW_ROUTE["Route Configuration"]
        GW_CORS["CORS Filter"]
        GW_MAIN --> GW_SEC
        GW_SEC --> GW_ROUTE
        GW_ROUTE --> GW_CORS
    end

    subgraph Chat_Service["Chat Service :9005"]
        direction TB
        CHAT_API["Chat API<br/>(REST)"]
        CHAT_FAQ["FAQ Management"]
        CHAT_AI["AI Client<br/>(WebClient)"]
        CHAT_DB["JPA Repository"]
    end

    subgraph Education_Service["Education Service :9002"]
        direction TB
        EDU_API["Education API"]
        EDU_VIDEO["Video Management"]
        EDU_SCRIPT["Script Management"]
        EDU_QUIZ["Quiz Management"]
        EDU_SOURCE["Source Set Management"]
        EDU_CLIENT["RestClient"]
        EDU_DB["JPA Repository"]
    end

    subgraph Infra_Service["Infra Service :9003"]
        direction TB
        INFRA_API["Infra API"]
        INFRA_S3["S3 Presigned URL"]
        INFRA_RAG["RAG Document"]
        INFRA_USER["User Management"]
        INFRA_TELE["Telemetry"]
        INFRA_KC["Keycloak Admin Client<br/>(RestTemplate)"]
        INFRA_DB["JPA Repository"]
    end

    REACT --> API_Gateway
    API_Gateway --> Chat_Service
    API_Gateway --> Education_Service
    API_Gateway --> Infra_Service

3. 서비스 간 통신 상세

HTTP 클라이언트 매핑

flowchart LR
    subgraph chat["Chat Service"]
        C_AI["ChatAiClient<br/>(WebClient)"]
    end

    subgraph edu["Education Service"]
        E_VIDEO["VideoAiClient<br/>(RestClient)"]
        E_QUIZ["QuizAiClient<br/>(RestClient)"]
        E_SOURCE["SourceSetAiClient<br/>(RestClient)"]
        E_INFRA["InfraRagClient<br/>(RestClient)"]
    end

    subgraph infra["Infra Service"]
        I_RAG["RagAiClient<br/>(RestClient)"]
        I_EDU["EducationServiceClient<br/>(RestClient)"]
        I_KC["KeycloakAdminClient<br/>(RestTemplate)"]
    end

    subgraph external["External"]
        AI["AI Server<br/>:8000"]
        KC["Keycloak<br/>:8090"]
    end

    C_AI -->|POST /ai/chat/messages| AI
    E_VIDEO -->|POST /ai/video/**| AI
    E_QUIZ -->|POST /ai/quiz/generate| AI
    E_SOURCE -->|POST /internal/ai/source-sets/**| AI
    E_INFRA -->|GET /rag/documents/**| infra
    I_RAG -->|POST /v1/internal_ragflow/**| AI
    I_EDU -->|GET /internal/quiz/**| edu
    I_KC -->|Admin API| KC

4. 서비스 간 통신 흐름

sequenceDiagram
    participant FE as Frontend
    participant GW as API Gateway
    participant KC as Keycloak
    participant CHAT as Chat Service
    participant EDU as Education Service
    participant INFRA as Infra Service
    participant AI as AI Server
    participant DB as PostgreSQL
    participant S3 as AWS S3

    Note over FE,S3: 사용자 인증 흐름
    FE->>KC: 로그인 요청
    KC-->>FE: JWT Access Token

    Note over FE,S3: 채팅 요청 흐름 (WebClient)
    FE->>GW: 채팅 메시지 (Authorization: Bearer JWT)
    GW->>KC: JWT 토큰 검증
    KC-->>GW: 토큰 유효
    GW->>CHAT: /api/chat/messages
    CHAT->>AI: WebClient - POST /ai/chat/messages
    AI-->>CHAT: AI 응답
    CHAT->>DB: 대화 기록 저장
    CHAT-->>GW: 응답
    GW-->>FE: 채팅 응답

    Note over FE,S3: 영상 생성 요청 흐름 (RestClient)
    FE->>GW: 영상 생성 요청
    GW->>EDU: /video/generate
    EDU->>INFRA: RestClient - Presigned URL 요청
    INFRA->>S3: Generate Presigned URL
    S3-->>INFRA: Presigned URL
    INFRA-->>EDU: URL 반환
    EDU->>AI: RestClient - 영상 생성 요청
    AI-->>EDU: 생성 작업 ID
    EDU->>DB: 작업 상태 저장
    EDU-->>FE: 작업 ID 반환

    Note over FE,S3: 사용자 관리 흐름 (RestTemplate)
    FE->>GW: 사용자 목록 조회 (Admin)
    GW->>INFRA: /admin/users
    INFRA->>KC: RestTemplate - Admin API
    KC-->>INFRA: 사용자 목록
    INFRA-->>FE: 응답

    Note over FE,S3: 개인화 데이터 조회 (RestClient)
    INFRA->>EDU: RestClient - /internal/quiz/my-attempts
    EDU-->>INFRA: 퀴즈 응시 내역

5. 데이터베이스 스키마 구조

erDiagram
    CHAT_SCHEMA {
        chat_session UUID PK
        chat_message UUID PK
        faq UUID PK
        faq_candidate UUID PK
        faq_draft UUID PK
        faq_revision UUID PK
        faq_ui_category UUID PK
    }

    EDUCATION_SCHEMA {
        education UUID PK
        education_video UUID PK
        education_script UUID PK
        education_script_chapter UUID PK
        education_script_scene UUID PK
        source_set UUID PK
        source_set_document UUID PK
        quiz_question UUID PK
        quiz_attempt UUID PK
        video_review UUID PK
    }

    INFRA_SCHEMA {
        rag_document UUID PK
        ai_log UUID PK
    }

    CHAT_SCHEMA ||--o{ CHAT_SCHEMA : "references"
    EDUCATION_SCHEMA ||--o{ EDUCATION_SCHEMA : "references"

6. 배포 아키텍처 (Kubernetes)

flowchart TB
    subgraph Internet
        USER["Users"]
    end

    subgraph AWS_Cloud["AWS Cloud (ap-northeast-2)"]
        subgraph K8S["Kubernetes Cluster (ArgoCD)"]
            subgraph Ingress_Layer["Ingress"]
                ING["Ingress Controller"]
            end

            subgraph Services["Backend Services"]
                GW_POD["api-gateway<br/>Deployment"]
                CHAT_POD["chat-service<br/>Deployment"]
                EDU_POD["education-service<br/>Deployment"]
                INFRA_POD["infra-service<br/>Deployment"]
            end

            subgraph Auth["Authentication"]
                KC_POD["keycloak<br/>Deployment"]
            end

            subgraph Database["Database"]
                PG_POD["PostgreSQL<br/>(pgvector)"]
            end

            subgraph K8S_Services["Kubernetes Services"]
                GW_SVC["api-gateway-service"]
                CHAT_SVC["chat-service"]
                EDU_SVC["education-service"]
                INFRA_SVC["infra-service"]
                KC_SVC["keycloak-service"]
                DB_SVC["keycloak-db"]
            end
        end

        subgraph ECR["AWS ECR"]
            IMG_GW["api-gateway:latest"]
            IMG_CHAT["chat-service:latest"]
            IMG_EDU["education-service:latest"]
            IMG_INFRA["infra-service:latest"]
            IMG_KC["keycloak:latest"]
        end

        subgraph S3_Bucket["AWS S3"]
            S3["ctrl-s3 bucket"]
        end
    end

    USER --> ING
    ING --> GW_SVC
    GW_SVC --> GW_POD
    GW_POD --> CHAT_SVC --> CHAT_POD
    GW_POD --> EDU_SVC --> EDU_POD
    GW_POD --> INFRA_SVC --> INFRA_POD
    GW_POD --> KC_SVC --> KC_POD

    CHAT_POD --> DB_SVC --> PG_POD
    EDU_POD --> DB_SVC
    INFRA_POD --> DB_SVC
    KC_POD --> DB_SVC

    INFRA_POD --> S3

    ECR -.->|Pull Image| GW_POD
    ECR -.->|Pull Image| CHAT_POD
    ECR -.->|Pull Image| EDU_POD
    ECR -.->|Pull Image| INFRA_POD
    ECR -.->|Pull Image| KC_POD

7. 공통 라이브러리 의존성

flowchart BT
    subgraph Services["Backend Services"]
        CHAT["chat-service"]
        EDU["education-service"]
        INFRA["infra-service"]
        GW["api-gateway"]
    end

    subgraph Libs["Common Libraries"]
        DTO["common-dto<br/>(공통 DTO, Lombok)"]
        SEC["common-security<br/>(Spring Security, OAuth2)"]
        UTIL["common-utils<br/>(유틸리티, Swagger)"]
        CONST["common-constants<br/>(상수 정의)"]
    end

    CHAT --> DTO
    CHAT --> SEC
    CHAT --> UTIL
    CHAT --> CONST

    EDU --> DTO
    EDU --> SEC
    EDU --> UTIL
    EDU --> CONST

    INFRA --> DTO
    INFRA --> SEC
    INFRA --> CONST

    GW --> CONST

8. API 라우팅 맵

9. 기술 스택 요약 다이어그램

mindmap
  root((CTRL-F<br/>Backend))
    Framework
      Java 17
      Spring Boot 3.3.3
      Spring Cloud 2023.0.4
    Gateway
      Spring Cloud Gateway
      Spring Boot 3.1.5
      Spring Cloud 2022.0.5
    HTTP_Clients
      WebClient
        chat-service → AI
      RestClient
        education-service → AI
        education-service → infra
        infra-service → AI
        infra-service → education
      RestTemplate
        infra-service → Keycloak
    Database
      PostgreSQL 16
      pgvector
      Flyway 10.10.0
      Spring Data JPA
    Auth
      Keycloak 24.0
      JWT
      OAuth2
    DevOps
      Docker
      Kubernetes
      ArgoCD
      AWS ECR
    Documentation
      SpringDoc OpenAPI 2.5.0
      Swagger UI

10. 보안 아키텍처

flowchart LR
    subgraph Client
        FE["Frontend"]
    end

    subgraph Auth_Flow["인증 흐름"]
        KC["Keycloak<br/>(OAuth2/OIDC)"]
    end

    subgraph Gateway_Security["Gateway 보안"]
        GW["API Gateway"]
        JWT_FILTER["JWT Validation<br/>Filter"]
        CORS["CORS Filter"]
    end

    subgraph Internal_Auth["내부 통신 보안"]
        INT_TOKEN["X-Internal-Token<br/>(AI_INTERNAL_TOKEN)"]
    end

    subgraph Backend
        CHAT["Chat"]
        EDU["Education"]
        INFRA["Infra"]
        AI["AI Server"]
    end

    FE -->|1. Login| KC
    KC -->|2. JWT Token| FE
    FE -->|3. Request + Bearer Token| GW
    GW --> JWT_FILTER
    JWT_FILTER -->|4. Validate| KC
    JWT_FILTER -->|5. Forward| CORS
    CORS --> CHAT
    CORS --> EDU
    CORS --> INFRA

    CHAT -->|X-Internal-Token| AI
    EDU -->|X-Internal-Token| AI
    INFRA -->|X-Internal-Token| AI
    INFRA -->|Service Account| KC

11. 데이터 흐름 다이어그램

flowchart TB
    subgraph User_Actions["사용자 액션"]
        A1["채팅 질문"]
        A2["교육 콘텐츠 조회"]
        A3["영상 생성 요청"]
        A4["퀴즈 응시"]
        A5["RAG 문서 검색"]
    end

    subgraph Processing["처리"]
        P1["AI 챗봇 응답 생성"]
        P2["교육/영상 데이터 조회"]
        P3["스크립트 생성 → 영상 생성"]
        P4["퀴즈 채점"]
        P5["벡터 검색 (pgvector)"]
    end

    subgraph Storage["저장소"]
        DB["PostgreSQL"]
        S3["AWS S3"]
        VEC["Vector Store<br/>(pgvector)"]
    end

    A1 --> P1 --> DB
    A2 --> P2 --> DB
    A3 --> P3 --> S3
    A4 --> P4 --> DB
    A5 --> P5 --> VEC

12. 포트 및 서비스 매핑

13. 내부 API 엔드포인트 상세

Education Service → AI Server (RestClient)

Education Service → Infra Service (RestClient)

Infra Service → AI Server (RestClient)

Infra Service → Education Service (RestClient)

Chat Service → AI Server (WebClient)