📄[문서][README] 아키텍처 및 기술스택 문서화

[Cassiiopeia]

📝현재 문제점

• README에 프로젝트 아키텍처 및 기술스택 정보가 없어 프로젝트 구조를 파악하기 어려움
• 신규 기여자나 평가자가 기술 선택 이유 및 전체 시스템 구조를 이해하는 데 시간이 소요됨
• 공모전·포트폴리오 어필에 필요한 기술적 설명이 부재함

🛠️해결 방안 / 제안 기능

• README에 시스템 아키텍처 섹션 추가 (전체 컴포넌트 구성도, 데이터 흐름)
• 기술스택 섹션 추가 (프론트엔드, 백엔드, AI 서버, DB, 인프라 등 레이어별 분류)
• 각 기술 선택의 이유 또는 역할을 간략히 기재

🙋‍♂️담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: @EM-H20
• 디자인:

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260413_#266_아키텍처_및_기술스택_문서화

커밋 메시지

아키텍처 및 기술스택 문서화 : feat : {변경 사항에 대한 설명} https://github.com/passQL-Lab/passQL/issues/266

[Cassiiopeia]

graph TB
    User["👤 사용자"]

    subgraph CICD["CI/CD — GitHub Actions"]
        direction LR
        CI["Build Check\n(PR 트리거)"]
        CD["Deploy\n(deploy 브랜치)"]
        UTIL["Utility\n버전·CHANGELOG·README 자동화"]
    end

    subgraph VERCEL["Frontend — Vercel"]
        direction TB
        subgraph FE_FRAMEWORK["Framework"]
            React["React 19\nTypeScript 6\nVite 8 + SWC"]
        end
        subgraph FE_STATE["상태 관리"]
            State["Zustand 5\nReact Query 5"]
        end
        subgraph FE_UI["UI / 스타일"]
            UI["Tailwind CSS 4\ndaisyUI 5\nlucide-react\nRecharts\nreact-markdown"]
        end
        subgraph FE_TEST["테스트"]
            Test_FE["Vitest 4\n@testing-library/react"]
        end
    end

    subgraph BACKEND["Backend — Docker · Synology NAS"]
        direction TB
        subgraph SPRING["Spring Boot 3.4 · Java 21 · Gradle 멀티모듈"]
            direction LR
            subgraph SPRING_CORE["Core"]
                S_Core["Spring Web\nSpring Security\nSpring Validation\nSpring Async"]
            end
            subgraph SPRING_DATA["Data"]
                S_Data["Spring Data JPA\nPostgreSQL\nFlyway\nSpring Data Redis\nCaffeine Cache"]
            end
            subgraph SPRING_INFRA["인프라"]
                S_Infra["Resilience4j\nSpring Actuator\nSpringDoc OpenAPI 3\nThymeleaf\nLombok\nJackson"]
            end
            subgraph SPRING_CUSTOM["사내 라이브러리"]
                S_Custom["suh-logger\nsuh-api-log\nsuh-random-engine"]
            end
            subgraph SPRING_EXT["외부 SDK"]
                S_Ext["Google Gemini SDK\nQdrant Client"]
            end
        end
        subgraph BE_DB["데이터 계층"]
            PostgreSQL[("PostgreSQL\n메인 DB")]
            Redis[("Redis\n캐시 / 세션")]
            SandboxDB[("Sandbox DB\nSQL 실행 격리")]
        end
    end

    subgraph AI_SERVICE["AI Service — Docker · Synology NAS"]
        direction TB
        subgraph AI_FRAMEWORK["Framework"]
            AI_Core["FastAPI 0.118\nPython 3.13\nUvicorn\nuv 패키지 관리"]
        end
        subgraph AI_LIBS["라이브러리"]
            AI_Lib["google-genai\nqdrant-client\nhttpx\nredis\npydantic-settings"]
        end
        subgraph AI_MODELS["AI 모델"]
            AI_Model["Gemini 2.5 Flash Lite\nOllama qwen2.5:7b (LLM)\nOllama qwen3-embedding:4b (임베딩)"]
        end
    end

    subgraph EXTERNAL["External Services"]
        Gemini["Google Gemini API"]
        Ollama["Ollama Server\nai.suhsaechan.kr"]
        Qdrant[("Qdrant\n벡터 DB :6333")]
        DockerHub["DockerHub\nImage Registry"]
        Synology["Synology NAS\nSSH 배포"]
    end

    %% 사용자 흐름
    User -- "HTTPS" --> VERCEL
    VERCEL -- "REST API" --> BACKEND
    BACKEND -- "HTTP · x-api-key" --> AI_SERVICE

    %% DB 연결
    SPRING --- PostgreSQL
    SPRING --- Redis
    SPRING --- SandboxDB

    %% AI 외부 서비스
    AI_SERVICE -- "HTTPS" --> Gemini
    AI_SERVICE -- "HTTPS" --> Ollama
    AI_SERVICE -- "HTTP" --> Qdrant

    %% CI/CD 흐름
    CI -.->|"빌드 검증"| VERCEL
    CI -.->|"빌드 검증"| BACKEND
    CI -.->|"빌드 검증"| AI_SERVICE
    CD -- "Docker push" --> DockerHub
    CD -- "Vercel CLI" --> VERCEL
    DockerHub -- "docker pull" --> Synology
    Synology -.->|"컨테이너 실행"| BACKEND
    Synology -.->|"컨테이너 실행"| AI_SERVICE

Loading

[Cassiiopeia]

graph LR
    User["👤 사용자"]

    subgraph VERCEL["Vercel"]
        FE["React SPA"]
    end

    subgraph NAS["Synology NAS (SSH :2022)"]
        BE["Spring Boot\nDocker :8097"]
        AI["FastAPI\nDocker :8098"]
        PG[("PostgreSQL")]
        RD[("Redis")]
        QD[("Qdrant :6333")]
    end

    subgraph ORACLE["Oracle Cloud"]
        ORA[("Oracle DB\nSandbox :1521")]
    end

    subgraph EXTERNAL["External"]
        Gemini["Google Gemini API"]
        Ollama["Ollama\nai.suhsaechan.kr"]
        DockerHub["DockerHub"]
        GitHub["GitHub Actions"]
    end

    User -- HTTPS --> FE
    FE -- REST API --> BE
    BE -- HTTP x-api-key --> AI
    BE --- PG & RD
    BE -- JDBC --> ORA
    AI --- QD
    AI --> Gemini & Ollama

    GitHub -- "docker push" --> DockerHub
    GitHub -- "Vercel CLI" --> VERCEL
    DockerHub -- "docker pull" --> NAS

Loading

[Cassiiopeia]

graph TB
    subgraph REACT["React 19 + TypeScript + Vite 8"]
        subgraph ROUTING["라우팅"]
            Router["react-router-dom 7"]
        end

        subgraph STATE["상태 관리"]
            Zustand["Zustand 5\n(클라이언트 상태)"]
            RQ["React Query 5\n(서버 상태 / 캐싱)"]
        end

        subgraph UI["UI 레이어"]
            Tailwind["Tailwind CSS 4\n+ daisyUI 5"]
            Icons["lucide-react"]
            Chart["Recharts\n(히트맵 / 차트)"]
            MD["react-markdown\n(AI 응답 렌더링)"]
        end

        subgraph API["API 레이어"]
            Client["api/client.ts\n(fetch wrapper, timeout 25s)"]
        end

        subgraph TEST["테스트"]
            Vitest["Vitest 4\n+ @testing-library/react"]
        end
    end

    Router --> UI
    UI --> STATE
    STATE --> API
    API -- "REST" --> Backend["Spring Boot API"]

Loading

[Cassiiopeia]

graph TB
    subgraph SPRING["Spring Boot 3.4 · Java 21 · Gradle 멀티모듈"]
        subgraph WEB["Web 레이어"]
            REST["Spring Web\n(REST API)"]
            Admin["Thymeleaf\n(Admin 관리자 UI)"]
            Swagger["SpringDoc OpenAPI 3\n(Swagger UI)"]
            Security["Spring Security\n(CORS / CSRF / STATELESS)"]
        end

        subgraph DOMAIN["Domain 레이어"]
            Domains["멀티모듈\nMember / Question\nSubmission / AI\nMeta / Application"]
        end

        subgraph DATA["Data 레이어"]
            JPA["Spring Data JPA\n+ Hibernate"]
            Flyway["Flyway\n(DB 마이그레이션)"]
            Redis["Spring Data Redis\n(L2 캐시)"]
            Caffeine["Caffeine\n(L1 로컬 캐시)"]
        end

        subgraph INFRA["인프라 레이어"]
            Resilience["Resilience4j\n(Circuit Breaker / Retry)"]
            Actuator["Spring Actuator\n(헬스체크)"]
            SuhLib["suh-logger\nsuh-api-log\nsuh-random-engine"]
        end

        subgraph EXT["외부 SDK"]
            GeminiSDK["Google Gemini SDK"]
            QdrantSDK["Qdrant Client"]
        end
    end

    WEB --> DOMAIN --> DATA
    DOMAIN --> INFRA
    DOMAIN --> EXT

Loading

[Cassiiopeia]

graph TB
    subgraph AI["FastAPI · Python 3.13 · uv"]
        subgraph SERVER["서버"]
            FastAPI["FastAPI 0.118\n(10개 엔드포인트)"]
            Uvicorn["Uvicorn\n(ASGI 서버)"]
            Auth["x-api-key 인증"]
        end

        subgraph CONFIG["설정"]
            Pydantic["pydantic-settings\n(.env / .env.prod)"]
        end

        subgraph CLIENTS["외부 클라이언트"]
            GeminiC["google-genai\n→ Gemini 2.5 Flash Lite\n(해설 / 선택지 생성)"]
            OllamaC["httpx\n→ Ollama qwen2.5:7b (LLM)\n→ qwen3-embedding:4b (임베딩)"]
            QdrantC["qdrant-client\n→ Qdrant 벡터 DB\n(유사 문제 검색)"]
            RedisC["redis\n(AI 결과 캐싱)"]
        end
    end

    Spring["Spring Boot"] -- "HTTP" --> FastAPI
    FastAPI --> GeminiC & OllamaC & QdrantC & RedisC

Loading

[Cassiiopeia]

graph LR
    User["사용자"]

    subgraph VERCEL["Vercel"]
        FE["웹 클라이언트"]
    end

    subgraph NAS["Synology NAS"]
        BE["애플리케이션 서버"]
        AI["AI 서버"]
        PG[("PostgreSQL")]
        RD[("Redis")]
        QD[("Qdrant")]
    end

    subgraph ORACLE["Oracle Cloud"]
        ORA[("Oracle DB\nSandbox")]
    end

    subgraph EXTERNAL["External"]
        Gemini["Google Gemini API"]
        Ollama["Ollama"]
        DockerHub["DockerHub"]
        GitHub["GitHub Actions"]
    end

    User -- HTTPS --> FE
    FE -- REST API --> BE
    BE -- HTTP x-api-key --> AI
    BE --- PG & RD
    BE -- JDBC --> ORA
    AI --- QD
    AI --> Gemini & Ollama

    GitHub -- "docker push" --> DockerHub
    GitHub -- "Vercel CLI" --> VERCEL
    DockerHub -- "docker pull" --> NAS

Loading

[Cassiiopeia]