llm-gateway-sub-backup/docs/ADR-3.md

ADR-003

• 제목: 서비스 간 공통 모듈 연동 방식 결정
• 날짜: 2025-06-12
• 상태: 제안됨 (Proposed)
• 작성자: [김용연 연구원]

---

1. 컨텍스트 (Context)

ADR-002를 통해 멀티레포 아키텍처로 결정되었으며, 이에 따라 각 서비스 간 공통 모듈을 어떤 방식으로 연동할 것인지에 대한 결정을 내려야 한다. 이번 논의는 다음 피드백을 기반으로 진행된다.

1. 공통모듈이 많고 복잡한가?
2. 관리포인트가 늘어날 여지가 많은가?

또한, Git 연동 방식 외에도 Gitea Action 기반 자동 동기화 방식을 함께 검토한다. 고려 요소는 다음과 같다.

• 공통 모듈의 복잡도 및 변경 빈도
• 유지보수 및 형상관리 난이도
• 개발자 사용성
• 자동화 가능성과 CI/CD 연계
• 로컬/원격 환경 간의 충돌 여부

---

2. 결정 (Decision)

현재 고려 중인 연동 방식은 다음과 같다.

방법	장점	단점
git-submodule	참조만으로 관리되어 가볍고 명확한 버전 고정 가능	초기 사용 복잡, 동기화 어려움, 실수 발생 가능성
git-subtree ✅	병합, 업데이트 용이, 독립적인 서비스 유지 가능	충돌 시 수동 병합 필요, 코드 중복 위험
Gitea Action(강제 동기화)	CI로 일관된 코드 유지 가능, 자동화 쉬움	설정 복잡, 브랜치 충돌 발생 가능성 있음

---

✅ 공통모듈

현재 공통적으로 사용되거나 예정된 모듈은 다음과 같다:

영역	모듈 예시	설명
로깅	logger.py	공통 포맷의 로그 기록, Loki 기반 모니터링 대응
요청 로깅 추적	request_logger.py	클라이언트 IP, 요청 시간, API 경로 등을 기록, Loki/Grafana 연동
설정 관리	config_loader.py	환경 변수 및 설정 파일 통합 로딩
응답 구조	response.py	API 응답 형식 표준화
예외 처리	exceptions.py	공통 예외 클래스로 서비스간 처리 로직 통일
Celery 태스크 래퍼	celery_base.py	공통 Task 기반 클래스, 재시도/타임아웃/로깅 통일
작업 상태 추적	redis_job_tracker.py	Redis 기반 작업 상태 추적 기능
모델 어댑터	llm_adapter.py, ocr_adapter.py	다양한 추론 서비스에 대한 공통 인터페이스
라우터 템플릿	base_router.py	FastAPI 기반 라우터 템플릿 및 공통 설정
파일 유틸리티	file_utils.py	확장자 검사, 디렉토리 생성 등 파일 처리 로직

---

3. 고려된 대안

1. git-submodule

• 경량화 및 버전 고정 측면에서 유리
• 그러나 초기 진입장벽이 높고, 실수(예: 서브모듈 커밋 누락 등) 발생 가능

2. git-subtree

• 현재 가장 유력한 방식
• 외부 저장소의 디렉터리를 내부로 복사하여 통합된 이력 관리 가능
• CI/CD 파이프라인 내에서도 동기화 명령 (pull, push, split)이 명확

3. Gitea Action 통한 자동 동기화

• push 이벤트 발생 시 main 브랜치의 common/ 디렉토리를 각 서비스의 utils/로 복사
• 자동화는 강력하나, 충돌이나 병합 충돌 발생 시 수동 대응 필요

---

4. 향후 계획

• 실제 운영 중인 공통 모듈을 기준으로 변경 빈도, 영향 범위 분석
• subtree 및 Gitea Action 기반 연동 테스트 진행
• 두 방식을 병행 테스트하여 장단점 비교

---