🤖 3단계 : 서비스 아키텍쳐 모듈화 - 100-hours-a-week/7-team-ddb-wiki GitHub Wiki

dolpin_ai/
├── app/
│   ├── main.py                      # FastAPI 진입점
│   ├── api/                         # 엔드포인트 정의
│   │   ├── deps.py                  # Depends 의존성
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   ├── recommend.py     # 추천 요청 엔드포인트
│   │       │   └── embed.py         # 임베딩 처리용 (장소, 사용자 요청 임베딩)
│   │       └── router.py            # v1 router 통합
│   ├── services/                    # 서비스 로직
│   │   ├── recommender.py           # 추천 알고리즘
│   │   ├── rag_engine.py            # RAG 체인 또는 프롬프트 체인
│   │   ├── prompt_manager.py        # 프롬프트 구성 및 템플릿 처리
│   │   └── vector_store.py          # FAISS/Chroma 등 벡터DB 연동
│   ├── ml/                          # 모델 로딩 및 추론
│   │   ├── model_loader.py          # LLM 또는 embedding 모델 로딩
│   │   └── inference.py             # 추론 엔진 실행 (gemini -> local llm)
│   ├── schemas/                     # Pydantic 모델
│   │   ├── recommend_schema.py      # 입력/출력 스키마
│   │   └── embed_schema.py
│   ├── core/                        # 설정, 보안, CORS 등
│   │   ├── config.py
│   │   └── init_app.py              # 로거, DB 초기화 등 FastAPI 앱 부트스트랩 함수
---------------------------------------v1----------------------------------------
│   ├── utils/                       # 보조 유틸 함수
│   │   ├── logger.py                # loguru 또는 structlog 기반 로거 설정
│   │   ├── text_cleaner.py          # 텍스트 전처리 유틸 (이모지 제거, 정규화 등)
│   │   └── timer.py                 # 추론 시간 측정 데코레이터 함수
├── workers/                         # 메시지 큐/비동기 워커 (선택)
│   ├── embedding_worker.py          # 임베딩 생성 및 DB 저장 등의 비동기 처리 전용 워커 (ex. Celery/RQ)
│   └── celery_app.py                # Celery 인스턴스 정의 및 설정 로딩
├── tests/                           # 테스트
│   ├── unit/                        # 단위 테스트: prompt_manager, recommender, vector_store 등
│   └── integration/                 # 통합 테스트: /recommend API 호출 시 end-to-end 확인
├── config/                          # 환경 설정 파일
│   ├── .env.dev                     # 개발 환경 설정 파일
│   ├── .env.prod                    # 운영 환경 설정 파일
│   └── gunicorn_conf.py            # Gunicorn 프로세스 관리 설정 (Docker 배포 시 사용)
├── Dockerfile                       # FastAPI 서버 + 모델 종속 패키지 포함 컨테이너 설정
├── docker-compose.yml              # API 서버 + 벡터DB + Redis (옵션) 등 여러 컨테이너 정의
├── requirements.txt                # 필수 패키지 리스트 (FastAPI, pydantic, openai, langchain, chromadb 등)
└── README.md                        # 서비스 개요, 설치 방법, API 설명 등 문서

{
  "userQuery": "내일 저녁에 예약 가능한 회식장소 알려줘, 메뉴는 해산물로"
}

{
    "data": [
        {"place_id": 21, "similarity_score": 0.92},
        {"place_id": 36, "similarity_score": 0.86},
        {"place_id": 16, "similarity_score": 0.87},
        {"place_id": 41, "similarity_score": 0.93},
        {"place_id": 12, "similarity_score": 0.91}
    ]
}

def generate_recommendation(input: RecommendationInput) -> RecommendationOutput:
    prompt = build_prompt(input)
    context = retrieve_context(input)
    result = call_llm(prompt, context)
    return parse_response(result)

def build_prompt(input: RecommendationInput) -> str:
    return f"""
    ...
    """