서비스아키텍처 모듈화 - 100-hours-a-week/3-team-ssammu-wiki GitHub Wiki

1. 전체 서비스 구조

AI서비스아키텍처7 drawio

2. 각 모듈의 역할 및 분리 이유

모듈 이름 역할 분리 이유
프론트엔드 (React 등) 사용자 입력 처리 (면접 질문 선택, 답변 작성, PDF 업로드, 이력서 요청), 결과 출력 (피드백 확인, 이력서 다운로드) UI 중심 역할에 집중. 사용자가 보는 모든 인터페이스는 프론트에서 처리하며, 로직은 전적으로 백엔드와 분리되어 있음.
백엔드 서버 사용자 요청 수신, 사용자 정보 저장/조회, 질문 데이터 조회, AI 서버로 추론 요청 전달, 파싱/이력서 생성 비동기 요청 처리 모든 데이터 흐름의 중심 허브. 프론트와 AI 서버 사이를 연결하고, S3 및 DB 연동도 담당하는 조율자 역할.
AI 서버 (FastAPI + vLLM) 백엔드로부터 전달받은 질문/답변 페어로 Prompt 구성 → vLLM을 통해 피드백 생성 후 백엔드에 응답 반환 추론 전용 모듈로 분리되어 있음. 모델 교체, 추론 성능 최적화, GPU 사용 등을 독립적으로 제어 가능하게 설계됨.
PDF 이력서 파서 업로드된 PDF 파일을 텍스트로 변환 후 이름, 학력, 경력 등의 정보를 추출하여 사용자 DB에 저장 고비용 I/O 및 텍스트 처리 작업이므로 비동기 Celery 태스크로 분리. 메인 API 서버 부하를 줄임.
이력서 자동 생성기 사용자 DB에 저장된 정보를 바탕으로 Word(docx) 형식의 이력서 초안 자동 생성, 생성 파일은 S3에 저장 실시간성이 필요 없는 CPU 중심 작업. 백엔드 요청으로 동작하며, 파일 저장까지 포함한 비동기 처리에 적합.
기업 정보 요약기 (LLM + 배치 파이프라인) 수동 수집한 IR/소개 자료 등 기업 텍스트를 LLM을 통해 요약 후 DB에 저장. 사용자 입력과는 무관 실시간 서비스가 아닌 비동기 백엔드 파이프라인으로 설계. 모델 추론 안정성과 주기적 데이터 처리에 최적화됨.
S3 스토리지 (예: AWS S3) PDF 업로드, Word 이력서 등 사용자 파일 저장 및 presigned URL 기반 다운로드 제공 대용량 파일 저장에 적합. 서버 디스크 IOPS나 용량 부담 없이 파일을 안전하게 관리 가능하며 프론트와 직접 통신 가능.
DB (MySQL 등) 사용자 정보, 질문 목록, AI 피드백 결과, 파싱된 이력 정보, 생성 문서 메타데이터, 기업 요약 결과 등 저장 모든 모듈의 공통 데이터베이스로써 상태를 일관성 있게 관리. 백엔드가 DB를 통해 모든 정보에 접근 가능.

3. 모듈 간 인터페이스 설계

출발 도착 방식 설명
프론트엔드 → 백엔드 서버 면접 질문 선택, 사용자 답변 입력, PDF 업로드, 이력서 요청 REST API 사용자 입력 전달. 백엔드가 DB 저장 또는 후속 처리 수행
백엔드 서버 → AI 서버 (FastAPI) 질문/답변 데이터 전달 fastAPI DB에서 질문 정보 조회 + 사용자 답변을 FastAPI에 전달
AI 서버 (FastAPI) → vLLM 엔진 Prompt 입력, 피드백 추론 요청 내부 함수 또는 API FastAPI 내부에서 vLLM으로 토큰 생성 요청 수행
AI 서버 → 백엔드 서버 생성된 피드백 응답 반환 fastAPI AI 서버가 생성한 피드백을 백엔드에 반환
백엔드 서버 → 프론트엔드 최종 피드백 응답 전송 REST API 백엔드가 프론트에 피드백 결과 전달
백엔드 서버 → PDF 파서 업로드된 파일 경로 전달 Celery 비동기 태스크 I/O 중심 파싱. 텍스트 및 정보 추출 후 DB 저장
백엔드 서버 → 이력서 생성기 사용자 정보 (DB 조회) 전달 Celery 태스크 / 내부 호출 Word 이력서 초안 생성, S3 저장
백엔드 서버 ↔ S3 PDF 저장, Word 다운로드 경로 관리 Boto3 SDK 등 모든 파일은 외부 스토리지에 저장/읽기 처리
프론트엔드 ↔ S3 Presigned URL을 통한 파일 업로드/다운로드 직접 통신 보안 설정 기반으로 FastAPI 거치지 않고 S3 접근 가능
크롤링 파이프라인 → 기업 요약기 수집한 기업 텍스트 배치 처리 / LLM 호출 기업 정보를 LLM이 요약 후 DB 저장. 사용자 요청과는 무관

4. 모듈화 기대 효과 및 장점

  • 역할 분리의 명확화:
    FastAPI는 AI 추론 전용, 백엔드는 API 조율/DB 중심, 프론트는 UI만 담당하도록 모듈 분리를 극대화함.
    각 레이어의 책임이 명확하므로 협업과 유지보수에 유리함.

  • LLM 교체 및 확장 유연성:
    AI 서버가 독립되어 있어 Mistral → Gemma, Qwen 등 다양한 모델로 교체/튜닝이 자유롭고, 성능 실험 시에도 영향 최소화.

  • 비동기 처리 최적화 구조:
    PDF 파싱, 이력서 생성, 기업 요약 등 지연 허용 가능한 기능은 모두 Celery 기반 비동기 처리로 백엔드 부하를 분산.

  • 파일 I/O 분리:
    모든 대용량 파일(PDF, Word)은 S3 스토리지를 통해 관리함으로써 API 서버의 디스크, IOPS 부담 최소화.

  • 중간 조율자 역할의 백엔드:
    백엔드가 질문 데이터 조회, 사용자 입력 수집, 결과 전달까지 조율하므로 프론트와 모델 간 연결 구조가 단순하고 안정적임.

  • 비실시간 AI 모듈의 분리 운영:
    기업 요약 AI는 서비스 사용 흐름과 분리된 비동기 구조로 구성되어 실시간성 요구가 없고, 운영 장애로부터 자유로움.

  • 기능별 단위 테스트 및 디버깅 용이:
    모듈 간 독립성이 보장되기 때문에 각 기능 단위로 테스트/오류 추적이 쉬움. 예: AI 서버 오류가 프론트나 PDF 파서에 영향을 미치지 않음.

  • 팀 협업 최적화 구조:
    프론트엔드 팀, 백엔드 팀, AI 팀이 각각 독립된 로직을 기반으로 병렬 개발 가능. 개발 효율이 매우 높음.

5. 우리 팀 서비스에 적합한 구조인 이유

  • AI 피드백 기능의 실시간성 확보:
    CS 면접 피드백은 사용자 경험에 직접 연결된 핵심 기능으로, GPU 기반 FastAPI AI 서버로 분리하여 지연 없는 응답 처리가 가능함.

  • FastAPI는 추론 전용, 백엔드는 데이터 조율 담당:
    모델 서버(FastAPI)는 오직 LLM 추론에만 집중하고, 백엔드는 질문 조회와 사용자 응답 조합을 수행하여 모듈 간 책임이 분명함.

  • PDF 파싱 및 이력서 생성은 비동기 큐로 운영:
    사용자가 바로 결과를 볼 필요 없는 기능은 Celery 기반으로 처리함으로써 API 응답 지연을 방지하고, 리소스 사용을 균형 있게 유지함.

  • 기업 정보 요약은 백엔드 파이프라인으로 독립 운영:
    수동 수집된 텍스트를 AI가 주기적으로 요약해 DB에 저장하므로, 실시간 응답성과는 완전히 분리된 안정적인 AI 활용 구조임.

  • S3 기반 스토리지 설계:
    파일 저장이 API 서버와 완전히 분리되어 성능 저하 없이 대용량 파일을 관리할 수 있고, presigned URL 구조로 클라이언트와 직접 통신도 가능함.

  • 기능별 수평/수직 확장 가능성:
    예: 요청 증가 시 AI 서버만 GPU 노드 추가, 이력서 생성기만 컨테이너 확장 등, 기능 단위 확장이 가능한 구조임.

  • 향후 Gemma, Qwen 등 다양한 모델 통합 가능성 확보:
    LLM 추론 모듈만 교체하면 되므로, 서비스 로직이나 API를 변경하지 않고도 최신 모델 실험/도입이 매우 유연함.