서비스 아키텍처 모듈화 - 100-hours-a-week/20-real-wiki GitHub Wiki

📐 1.아키텍처 구조

app/
├── main.py                          # FastAPI 앱 진입점, 전체 라우터 및 설정 로딩
├── api/
│   ├── router.py                      # API 전체 엔드포인트 등록용 모듈
│   └── v1/                          # v1 버전: 초기 기능군 (챗봇, 공지요약, Discord 뉴스 요약)
│   │   ├── endpoints/
│   │   │   ├── chat_router.py           # [챗봇 응답] → /api/v1/chatbots
│   │   │   ├── notice_router.py         # [공지 요약] → /api/v1/notices/summarization
│   │   │   └── discordnews_router.py    # [Discord 뉴스 헤드라인/요약] → /api/v1/news
│   │   └── controllers/
│   │       ├── chat_controller.py
│   │       ├── notice_controller.py
│   │       └── discordnews_controller.py
│   └── v2/                          # v2 버전: 위키 기반 뉴스 기능
│       ├── endpoints/
│       │   └── wikinews_router.py       # [위키 기반 뉴스 생성] → /api/v2/news
│       └── controllers/
│           └── wikinews_controller.py
│   └── v3/                          # v3 버전: 퀴즈 생성 기능
│       ├── endpoints/
│       │   └── wikiquiz_router.py       # [위키 기반 퀴즈 생성] → /api/v1/quizzes
│       └── controllers/
│           └── wikiquiz_controller.py
├── core/                            # 공통 유틸리티 및 시스템 설정
│   ├── llm_client.py                # LLM 호출 인터페이스
│   ├── vector_store.py              # FAISS 벡터 스토어 로딩 및 검색
│   ├── config.py                    # 환경 변수, 설정값 관리
│   ├── embedding_model.py           # RAG용 임베딩 모델 로딩
│   ├── logging_config.py            # 요청/응답 로깅 설정 (운영 대비)
│   └── error_handler.py             # 예외 처리 핸들러
├── services/                        # 비즈니스 로직 계층
│   ├── chat_service.py              # 챗봇 응답 생성 처리
│   ├── notice_service.py            # 공지 요약 생성 처리
│   ├── discordnews_service.py       # Discord 기반 뉴스 헤드라인/요약 처리
│   ├── wikinews_service.py          # 위키 문서 기반 뉴스 생성 처리
│   └── wikiquiz_service.py          # 위키 기반 퀴즈 생성 처리
├── schemas/                         # 요청/응답 구조 정의 (Pydantic 모델)
│   ├── chat_schema.py
│   ├── notice_schema.py
│   ├── discordnews_schema.py
│   ├── wikinews_schema.py
│   └── wikiquiz_schema.py
├── model/                           # LLM 추론 모듈
│   ├── qwen2_5_loader.py            # Qwen2.5 모델 로딩 스크립트
│   └── prompt_template.py           # 각 기능별 프롬프트 템플릿
├── scripts/                        
│   ├── create_vectorstore.py        # docs/ 기반 벡터스토어 생성
│   ├── upload_to_gcs.py             # 생성된 인덱스를 gcs로 업로드
└── docs/                            # RAG용 내부 공지 문서
    ├── 공지사항1.md            
    └── 공지사항2.md

🚀 2. 각 모듈의 책임(domain)과 기능에 대한 설명

모듈	책임 (Domain)	주요 기능
`main.py`	앱 진입점	FastAPI 앱 실행, 전체 라우터 등록, 공통 설정 적용
`api/*/endpoints`	라우터 정의	각 기능(API 버전별)의 HTTP 라우팅 경로 정의
`api/*/controllers`	요청 핸들러	실제 API 호출 시 요청 검증, 서비스 호출, 응답 반환
`core`	공통 유틸리티/핵심 설정	모델 클라이언트, 프롬프트 생성기, 캐시, 에러 처리, 설정 관리
`services`	비즈니스 로직 처리 계층	각 기능별 서비스 로직, LLM 추론 호출, 응답 포맷 처리
`schemas`	데이터 구조 정의	요청/응답에 사용하는 Pydantic 기반 데이터 클래스
`model`	모델 서빙 로직	Qwen2.5 모델 로딩, 텍스트 생성 함수, 프롬프트 템플릿 정의

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

flowchart TD
    A[Client Request] --> B["Router: endpoints"]
    B --> C["Controller: controllers"]
    C --> D["Service: services"]
    D --> E["Model: generate.py"]
    D --> F["Core: Prompt Builder & LLM Client"]
    D --> G["Core: Cache, Config"]
    C --> H["Schemas: Pydantic"]

Router ↔ Controller: FastAPI 라우터 경로를 통해 컨트롤러 호출 (APIRouter)
Controller ↔ Service: 요청 데이터를 Pydantic으로 파싱 후, service 로직 호출
Service ↔ Model/Core: 추론이 필요한 경우 core/model 함수 호출 (llm_client.generate_text(...))
Service ↔ Cache: 응답 캐싱이 필요한 경우 core/cache 연동
Service ↔ Prompt Template: 도메인별 템플릿 포맷을 가져와 prompt 구성
모든 계층 ↔ Schemas: 데이터 유효성 검증 및 응답 포맷 통일

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

✅ 확장성 확보: 각 기능은 독립적 모듈로 구성되어, 새로운 기능 추가 시 손쉽게 확장 가능
✅ 유지보수 용이: 각 계층이 분리되어 있어 디버깅, 리팩토링, 테스트가 간편
✅ 재사용성 증가: core, model, schemas 등은 여러 서비스에서 재사용 가능
✅ 병렬 개발 최적화: 팀 단위로 기능을 나눠 동시 개발 가능
✅ 마이크로서비스화 유리: 서비스 경계가 명확하여, 추후 모델 서빙 등을 별도 서비스로 분리하기 용이

☁️ 5. 모듈화된 설계가 팀의 서비스 시나리오에 부합함을 설명하는 근거

현재 팀의 서비스는 다기능 AI 응답 API로, 챗봇·헤드라인·위키뉴스·요약·퀴즈 등 기능별 처리가 명확히 요구됨
각 기능마다 입력 구조, 모델 프롬프트, 응답 포맷이 다르므로 기능 단위의 모듈 분리가 필요
LLM 모델은 고비용 리소스를 사용하는 특수 모듈이므로, 별도 로직(model/, core/)으로 분리하여 재사용 및 효율적 자원 관리를 달성
추후 기능이 늘어나거나 모델 종류가 추가될 경우에도 서비스 단위 확장과 분산 배포(MSA)가 가능하도록 설계되어 있음