backend-api-ai-monorepo 는 FastAPI API 서버와 LangChain/LangGraph AI 서비스를 하나의 모노레포로 통합한 프로젝트입니다.
항공 가격 · 날씨 · 정책 · 추천 데이터를 LLM 파이프라인에 연결해 대화형 원스톱 여행 플래너 기능을 제공합니다.
- 1. 서비스 기능 개요
- 2. 데모
- 3. 팀원별 기여 현황
- 4. 구현 기능 관련
- 5. 아키텍처 구성
- 6. 레이어 구성
- 7. 프로젝트 구조
- 8. 설치 및 실행
- 9. 테스트 스크립트
- 10. 브랜치 전략
- 11. Conventional Commits 가이드
여행자는 노선·시즌·발권 시점·환불‧수수료 규정 등 수십 개 옵션을 직접 설정해야만 합리적인 결정을 내릴 수 있습니다.
기존 플랫폼은 이 복잡도를 그대로 노출해 ‘정보만 던져주는 리스트 UI’에 머무르기 때문에 ▲가격 변동 추적 부재 ▲약관 해석 난이도 ▲결정 피로도가 큰 문제가 됩니다.
backend-api-ai-monorepo는 이러한 한계를 해결하기 위해 ―
- LLM 기반 Intent Router로 사용자의 자연어 의도를 구분하고,
- 7개의 체인(가격·추천·날씨·정책·알림 등)으로 기능을 모듈화하며,
- Amadeus·OpenWeather MCP + PDF RAG + Celery 알림을 결합해,
- 챗(UI) 한 줄 ↔ 추천 → 예약 → 알림까지 원스톱 UX를 제공합니다.
아래 표는 각 Intent·체인·UI 컴포넌트가 어떻게 매핑되어 있는지 한눈에 정리한 것입니다.
| 기능 분류 | Intent ID | 백엔드 Chain (LangChain) | 외부/API 의존 | UI 컴포넌트 |
|---|---|---|---|---|
| 요금 조회·추적 | PRICE_SEARCH | price search는 총 두 부분으로 나뉜다. 1번째는 기본 chat post api 호출을 통해, ‘price - search’ intent로 분류되는 llm 부분이다. 두 번째는, 백의 Amadeus Flight Offer Search 연동을 통한 프론트 - 백의 사용자가 설정한 필드 조건에 따른 항공권 결과 조회 리스트이다. llm chain price_search_chain– Amadeus Flight Offer Search → Cheapest N 추출 |
1: Amadeus MCP 2: amadeus flight offer search api 연동 |
FlightCardList |
| 가장 저렴한 가격 | CHEAPEST_PRICE | cheapest_price_chain – Offer 리스트 중, 아마데우스 mcp 내 쿼리 아날라이저와 ,tool을 통해, → min price 선택 → 이를 해당 intent에 대한 chat post 응답으로 반환 |
Amadeus MCP | BestDealCard |
| 가격 트래킹 | PRICE_tracking | price_tracke 클러리 특정 주기 단위 캐싱 → redis/clery → 이동평균·변동량 분석 | redis, clery | PriceTrendSection |
| 가격 분석 | PRICE_ANALYSIS | price_analysis_chain– 사용자 쿼리에 해당하는 날짜의 항공권 가격 기반으로 아마데우스 mcp 내 쿼리 아날라이저와 ,tool을 통해, Metrics 분석 후 프론트에 반환 |
Amadeus MCP 서버 | InsightBubble |
| 정책 QA | POLICY_QA | policy_qa_rag_chainLoader (PDFPlumber) → Splitter (Recursive) → Chroma → Reranker (Cross-Encoder), 메타 데이터 활용 -> 항공기 기반 정책 qa | PDF 규정 벡터 | PolicyAnswerCard |
| 목적지 추천 | DEST_RECOMMEND | create_react_agent 함수를 활용하여, Web Search → ReAct 에이전트 → Google Places 툴 연동 -> 이에 대한 top-3 추천 목적지를 반환하는 카드 구성 -> 이를 chat post api의 response로 줌 |
open a Web Search Google Places api 연동 진행 | RecoCarousel |
| 날씨 요약 | WEATHER_SUMMARY | weather_summary_chain 5-day forecast fetch → LLM |
OpenWeather mcp 서버 활용 |
WeatherStrip |
| 알림 문구 생성 | ALERT_DISPATCH | alert_dispatch_chain– threshold 저장(MySQL) → Celery → Kakao/Email | MySQL Celery Kakao/Email |
AlertModal |
| 일반 대화 | GENERAL_CHAT | chat_fallback_chain | – | ChatBubble |
요약
한 줄 대화로 ▲항공권 탐색 ▲가격 알림 ▲날씨 위험 경고 ▲정책 FAQ ▲개인화 추천을 실시간·능동형으로 수행하며, 사용자는 복잡한 필터링 없이 “지금 예약할까?” 버튼만 누르면 됩니다.
기존 항공권 플랫폼이 “필터 - 리스트 - 직접 판단” 방식이라면, Bookie는
자연어 1문장 → 분석 → 능동 제안 흐름으로 사용자의 의사결정 피로를 크게 줄입니다.
| 구분 | 기존 서비스 (예: 스카이스캐너/구글플라이트) | Bookie 챗봇 | 사용자가 체감하는 변화 |
|---|---|---|---|
| 예약 인터페이스 | 복잡한 필터·표 형식 | 카드·버튼 중심 챗 UI | 클릭 ↓, 정보 탐색 시간 ↓ |
| 가격 알림 등록 | 버튼 → 이메일만 지원 | “15만원 이하 되면 알려줘” 즉시 등록 | 알림 설정 시간 ↓, 실시간성 ↑ |
| 실시간 대화 대응 | 불가 | 가능 (LLM 7-chain) | 탐색→결정 턴 ↓ |
| 취소·변경 규정 | 약관 PDF 링크 | 200자 요약 + 근거 하이라이트 | 이해도 ↑, 오류 ↓ |
| 가격 트렌드 | 사용자가 직접 조회 | “가격 추이 분석 그래프 제공 | 최적 예약 타이밍 제시 |
| *가격 트래킹 | 없음 | 카톡/메일 자동 발송 | 불필요 수수료 ↓ |
핵심: Bookie는 정보를 넘어서 행동(Action) 을 유도합니다.
예) 가격 하락 알림 → “지금 예약할까요?” 버튼으로 즉시 전환,
-
시작 대화
사용자가 “지금 종강하고 동남아 여행 가고 싶은데 … 말레이시아 여행지 추천해줘”라고 입력하면 DEST_RECOMMEND 체인이 작동합니다. -
여행지 추천 – DEST_RECOMMEND (결과 부키 ①)
ReAct Agent + Google Places 가 쿠알라룸푸르·조지타운을 카드 형태로 제시합니다 → 사용자는 카드 스와이프로 상세 정보를 확인할 수 있습니다. -
날씨 요약 – WEATHER_SUMMARY (부키 ②)
“쿠알라룸푸르 날씨 어때?” 질문 → OpenWeather MCP 를 호출해 현재 기온·체감·강수 가능성을 1문단 요약으로 반환합니다. -
가격 추세 분석 – PRICE_ANALYSIS (부키 ②-③)
“6월 30일 인천 → KUL 항공권 가격 추이 분석해줘” →
*MCP-subchain -> Amadeus MCP + 가격 히스토리 * 로 최소·최대·중간값을 계산, 추세 그래프와 함께 응답합니다. -
최저가 조회 – CHEAPEST_PRICE (부키 ③-④)
“그럼 그 날짜에 지금 살 수 있는 가장 싼 항공권 알려줘” →
최저가 항공편(₩172,400) 카드 + ‘예약하러 가기 →’ 버튼이 제공됩니다. -
외부 리다이렉트 – REDIRECTING (부키 ④-⑤)
버튼 클릭 시 스카이스캐너로 심리스 딥링크되어, 동일 편명을 이미 필터링한 상태로 바로 이동합니다. -
맞춤 가격 재질문 & 알림 등록 – PRICE_SEARCH → ALERT_DISPATCH (부키 ④-⑤)
“15만원 이하로 떨어지면 알려줘” →
· 프런트에서 AlertModal 을 열어 임계값(150,000) 확인
· 백엔드가alert_dispatch_chain을 통해 MySQL 저장 → Celery 등록
· 추후 30초 주기로 가격이 떨어지면 카카오톡/이메일 실시간 알림 전송 (부키 ⑤-⑧). -
가격 트래킹 결과 – PRICE_TRACK (부키 ⑤-⑧)
데모에서는 30초 간격 시뮬레이션으로 가격이 변동될 때마다 알림이 카톡·메일로 누적 발송되는 모습을 확인할 수 있습니다. -
정책 FAQ – POLICY_QA (부키 ⑤-⑨)
“과자·액체류 기내 반입 가능해?” →
· PDFPlumber → Chroma 로 벡터화된 항공사 규정에서 근거 + 출처 페이지를 찾아 200자 내외로 답변합니다.
· 하단 ‘출처: ㉿항공사 규정 (§5) 개정: 2023-10-01’ 링크로 신뢰도를 확보합니다.
| 이름 | 역할 | 핵심 기여 |
|---|---|---|
| 이지인 | 팀장 · LLM(서비스) | · 아키텍처 설계 · RAG 체인 · Git 관리, 일정/경로 관리 · message fastapi 구현 · Intent Router · Pydantic 모델 구상, 구현 · dest_recommend_chain 구현 · Kakao 알림 모듈 구현 · Amadeus MCP · Sub-chain 구현, 병합 · LLM 평가 · 모노레포 통합 |
| 신승철 | LLM(전처리) | · 정책 PDF 전처리 · Policy Vector DB, Policy 체인 · Weather MCP · Query Vector DB · Pydantic 모델 구현 · Prompt 컨텍스트 보강 |
| 김도의 | 백엔드 | · FastAPI REST · Celery + Redis · MySQL ERD · Amadeus API 래퍼 · AWS 배포(HTTPS) |
| 이신행 | 프론트 | · React + Vite Chat UI · Intent별 컴포넌트 · 가격 알림/리마인드 UX · API 연동(fetch/axios) · Cloudflare 배포 · 스카이스캐너 딥링크 |
| 구분 | 기능 | MVP | 구현 | 비고 |
|---|---|---|---|---|
| A₁ | 실시간 날씨 반영 | ✔︎ | ✔︎ | OpenWeather MCP |
| A₂ | 사용자 맞춤 정보 | ✔︎ | ✔︎ | 컨텍스트 기반 추천 |
| A₃ | 항공권 가격 조회·알림 | ✔︎ | ✔︎ | Amadeus MCP, API + Celery |
| A₄ | 여행지 옵션 추천 | ✔︎ | ✔︎ | 예산·날씨·취향 카드 |
| A₅ | 항공 정책 Q&A | ✔︎ | ✔︎ | PDF RAG 요약 |
| A₆ | 예약 딥링크 | ✔︎ | ✔︎ | 스카이스캐너 리다이렉트 |
| 레이어 | 기술 스택 | 핵심 기능 |
|---|---|---|
API Serverapps/api-server |
FastAPI · SQLAlchemy · MySQL · Amadeus SDK | 사용자·호텔·항공 CRUD, JWT 인증, Amadeus 최저가 조회, Alert Webhook, 도메인 모델 |
AI Serviceapps/ai-service |
LangGraph · OpenAI API · ChromaDB | 7개 RAG 파이프라인 · Flight Price Tracker · Weather Summariser (MCP 연동) · Destination Recommender (MCP 캐시 활용) · Hotel Finder · Air-Policy QA · Redirect Service · Alert Dispatcher(카카오·이메일) |
Core 패키지packages/core-backend |
Pydantic · 공용 유틸 | Amadeus 래퍼, MCP(OpenWeather) 클라이언트, 캐시 관련, 알림 템플릿 |
디렉토리 구조 아래는 실제 디렉터리 구조를 반영한 backend-api-ai-monorepo/의 구조입니다.
backend-api-ai-monorepo/
```text
.
├── apps/ # 독립 실행 서비스 모음
│ ├── ai_preprocess/ # · 전처리용 모듈
│ ├── ai_service/ # · 전처리된 데이터로 실제 RAG 서비스 (챗봇 응답 생성) 수행
│ ├── amadeus_mcp_server/ # · Amadeus API를 MCP(SSE)로 노출하는 Node.js 서버
│ └── api-server/ # · 챗봇 클라이언트용 메인 FastAPI REST 서버
├── bookie.egg-info/ # Python 패키지 배포 메타데이터
├── cache/ # · HuggingFace·OpenAI 모델 캐시 저장소
├── db_FAISS/ # · 벡터 검색용 FAISS 인덱스 파일(index.faiss, index.pkl)
├── launch_api.py # · 전체 서버(FastAPI + MCP) 실행·모니터링 진입 스크립트
├── packages/ # · 사내 공통 모듈
│ ├── chatbot_contents/ # – Intent별 응답 핸들러 & Pydantic 스키마
│ └── core_backend/ # – Amadeus 클라이언트 래퍼, 유틸리티
├── requirements.txt # · Python 종속성 목록
├── root_data/ # · 원본 참조 데이터(e.g. koreanair.pdf)
├── runs/ # · 테스트·실험 스크립트 모음(main.py, mcp_client.py 등)
├── setup.py # · 패키지 설치용 설정 파일
└── tmp/ # · 임시 결과물(dest_reco_*.html 등)
- 파이썬 가상환경 생성 및 활성화
-
가상환경 생성
python -m venv env
-
가상환경 활성화
-
Windows
env\Scripts\activate
-
macOS/Linux
source env/bin/activate
-
-
패키지 설치
-
가상환경이 활성화된 상태에서 루트 디렉토리에서, 아래 명령어로 패키지를 한 번에 설치합니다.
pip install -r requirements.txt // 패키지 삭제 pip uninstall -r requirements.txt -yfastapi sqlalchemy pydantic alembic uvicorn pymysql python-dotenv amadeus # --- AI/RAG 쪽 --- langchain huggingface_hub langchain-openai pypdf numpy==1.26.2 langsmith openai langgraph python-dateutil
-
-
환경변수 설정
- 프로젝트 루트에
.env파일을 생성하고,OPENAI_API_KEY및AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRET등 필요한 환경변수를 설정합니다.
- 프로젝트 루트에
# 1. 프로젝트 루트에서 개발 모드로 설치
pip install -e . (requirments.txt에 있으므로 별도 설치 불필요)
# 2. entry point로 제공되는 명령어 예시
# - MCP 서버·클라이언트·테스트
mcp-server # MCP 서버 기동
mcp-client # MCP 클라이언트 호출
mcp-test # 통합 테스트 스크립트 실행
# - 전처리 및 챗봇 서비스
preprocess # PDF → FAISS, 혹은 기존 FAISS에 추가
bookie-chat # 대화형 AI 서비스 실행
# - FastAPI 서버 (Uvicorn wrapper)
api-server # uvicorn으로 FastAPI 앱 기동프로젝트를 쉽고 간편하게 설치·실행하기 위해 setup.py에 다음과 같은 설정을 해두었습니다:
-
packages및package_dirfind_packages(where=".")로 최상위 패키지 전부를 자동으로 수집합니다.- 추가로 “싱글 파일 모듈”(
launch_api.py)과, 앱별 디렉터리 위치를package_dir로 1:1 매핑하여 패키지로 인식되도록 설정합니다."": ".", "mcp": "apps/ai_preprocess/src/mcp", "app_preprocess": "apps/ai_preprocess/src/app", "service": "apps/ai_service/src", "app_service": "apps/ai_service/src/app", "app_service.service": "apps/ai_service/src/app/service", "api_server": "apps/api-server/workspace/fastapi-project", "api_server.routers": "apps/api-server/workspace/fastapi-project/routers", "core_backend": "packages/core_backend",
-
py_modules- 패키지로 묶이지 않는 단일 모듈(
launch_api.py)을 포함시켜, CLI 엔트리포인트에서 사용할 수 있게 합니다.
- 패키지로 묶이지 않는 단일 모듈(
-
entry_points.console_scripts- 설치 후 패스(Path)에 자동 등록되는 실행 명령어를 정의합니다.
- 예)
preprocess,bookie-chat,api-server등을 터미널에서 바로 호출할 수 있습니다.
runs/test 디렉터리안에 다음과 같은 스크립트를 배치해 두었습니다. 모두 mcp-test, preprocess, bookie-chat 등의 entry point로 쉽게 실행할 수 있습니다.
| 파일명 | 설명 |
|---|---|
| imports.py | - setup.py에 정의된 console_scripts 엔트리포인트가 잘 작동하는지 테스트- data, app_service.virtual_db, core_backend.amadeus_client 등 주요 모듈 임포트 경로 확인 |
| mcp.py | - MCP 서버(백그라운드) 기동/종료 - langchain_mcp_adapters를 통한 QA 에이전트 테스트- mcp-server/mcp-client CLI 명령어 구현 |
| policy.py | - FAISS 기반 PDF RAG 체인 테스트 스크립트 - --db-path 옵션 지원, 인터랙티브 Q&A 루프- policy 전용 entry point (mcp-test로 묶어서 실행) |
| preprocess.py | - PDF 파일 → FAISS 벡터 스토어 생성 및 추가 기능 테스트 - `--mode=create |
# 예시: imports.py를 직접 실행해 console_scripts 설치 확인
imports # setup.py에 정의된 console_scripts 중 하나가 정상 동작하는지 테스트
# 예시: 전처리 스크립트 실행
preprocess sample.pdf --mode create
# 예시: MCP 통합 테스트
mcp-test모노레포 환경에서 DB, 전처리·Preprocess, LLM 서비스 영역을 독립 개발하면서도 develop 브랜치에서 전체 통합 테스트를 수행하고, main 브랜치로 배포하는 단순화된 구조입니다.
module/db, module/preprocess, module/service → 영역별 독립 개발
develop → 전체 통합 테스트
main → 실제 프로덕션 배포
| 브랜치명 | 역할 |
|---|---|
main |
프로덕션에 배포된 안정된 코드 |
develop |
다음 배포를 위한 통합 개발 브랜치 |
| Module 브랜치 | 각 영역별 집중 개발 |
├ module/db |
DB 스키마·마이그레이션·Core 패키지 개발 전용 |
├ module/preprocess |
RAG 전처리 파이프라인 개발 전용 |
└ module/service |
LLM 서비스(Price Tracker, QA 등) 개발 전용 |
아래 표를 참고하여, 커밋 메시지 앞에 접두사를 붙여 변경 의도를 명확히 관리할 수 있습니다.
무조건 지켜야하는 것은 아니지만, “무엇을”과 “어떻게” 바꾼 것인지를 기준으로 일관성 있게 커밋들을 관리하는데 도움이 되고자 추가해보았습니다.
| 커밋 종류 | 목적 | 언제 사용할까요? | 예시 커밋 메시지 | 비고 |
|---|---|---|---|---|
[feat] |
새로운 기능(기능 단위) 추가 | - 새로운 API 엔드포인트 추가 - DB 스키마·마이그레이션 추가 - LLM 모델 파이프라인 통합 |
feat(api): 사용자 프로필 조회 엔드포인트 추가feat(llm): streaming 응답 지원 |
기능 단위로 나눠서 작은 단위 커밋 권장 |
[fix] |
일반 버그 수정 | - 잘못된 응답 포맷 처리 - SQL 쿼리 오류 해결 - 예외 처리 로직 보완 |
fix(api): token 검증 실패 시 401 반환하도록 수정fix(db): foreign key cascade 설정 |
개발 브랜치에서 발견된 버그에 사용 |
[hotfix] |
프로덕션 긴급 패치 | - 장애를 유발하는 크래시 - 치명적 보안 취약점 긴급 수정 |
hotfix(api): 로그인 null 포인터 예외 패치 |
main/release 브랜치에 바로 머지 후 배포 |
[refactor] |
코드 구조·가독성·중복 제거 (동작 변경 없음) | - 서비스·모듈 계층 분리 - 반복 로직 함수로 추출 - 네임스페이스·패키지 재배치 |
refactor(api): 유효성 검사 로직을 미들웨어로 추출 |
기능·성능 변화 없이 내부 구조만 개선 |
[perf] |
성능 최적화 | - DB 인덱스 추가로 쿼리 속도 개선 - 캐싱 로직 도입 - 불필요한 연산 제거 |
perf(db): orders 테이블에 composite index 추가perf(api): response 캐싱 적용 |
실제 벤치마크 데이터(속도, 메모리) 개선이 보이는 작업에 사용 |
[docs] |
문서 작성·수정 | - README·설계 문서 업데이트 - API 스펙·Swagger 주석 작성 - 주석 보강 |
docs: LLM 파이프라인 구성 흐름 다이어그램 추가docs: API 인증 가이드 보강 |
코드 변경 없이 문서만 바뀔 때 |
[style] |
코드 포맷팅·세미콜론·공백 등 스타일 수정 | - 린트 오류 수정 - 들여쓰기·라인 길이 맞춤 - 파일 헤더 정리 |
style: ESLint 규칙에 맞춰 들여쓰기 통일 |
로직·빌드·테스트에는 영향 없는 순수 스타일 변경 |
[test] |
테스트 코드 작성·수정 및 커버리지 개선 | - 단위/통합/E2E 테스트 추가 - 테스트 모의(Mock) 설정 - 커버리지 설정 파일 수정 |
test(api): /orders integration 테스트 추가test(llm): embedding mock 도입 |
테스트 관련 폴더·파일만 변경될 때 |
[build] |
빌드·패키징 설정 변경 | - Dockerfile 수정 - 패키징 스크립트 변경 - 버전 태그 자동화 설정 |
build: Dockerfile 베이스 이미지를 python:3.11-alpine 으로 변경 |
배포 아티팩트(파일, 바이너리) 생성 로직에 영향 |
[ci/cd] |
CI/CD 워크플로우·스크립트 설정 수정 | - GitHub Actions·Jenkinsfile 추가/수정 - 배포 스크립트 변경 - 체크리스트 워크플로우 개선 |
ci: PR 린트·테스트 워크플로우 추가ci/cd: 모델 재훈련 잡 스케줄링 설정 |
배포 자동화·검증 파이프라인만 변경될 때 |
[chore] |
그 외 운영·관리 작업 (문서·의존성·도구 설정 등) | - 의존성 업그레이드 - 린트/포매터 설정 - GitHub badge 업데이트 |
chore: requirements.txt 의존성 버전 업그레이드chore: Prettier 설정 추가 |
코드 로직·테스트·빌드·CI에 직접 영향 없는 잡무 |
[revert] |
이전 커밋을 되돌릴 때 사용 | - 잘못된 변경 롤백 - 의도치 않은 병합 복구 |
revert: feat(api): user-auth 엔드포인트 추가 |
되돌릴 커밋 메시지를 뒤에 괄호로 명시 |








