## LLM Gateway 아키텍처

**문서 번호:** **ADR-002**

- 제목: **LLM Gateway 비동기 아키텍처 채택**
- 날짜: **2025-06-02**
- 상태: **제안됨 (Proposed)**
- 작성자: **\[김용연 연구원]**

---

### 1. 컨텍스트 (Context)

**본 문서는 현재 운영 중인 OCR, LLM Service, STT 3개 AI 서비스의 통합 운영을 위해 선택한 멀티레포(Multi-Repository) 아키텍처를 정의함. 주요 요구사항은 다음과 같음**

- **서비스별 독립 개발 및 배포**: OCR, LLM, STT 각각의 서비스는 별도 개발자에 의해 독립적으로 개발/운영되며, 서비스별 라이프사이클 관리가 필요함
- **모놀리식 구조 지양**: 모든 서비스를 하나의 코드베이스로 통합하는 모노레포 방식은 코드 충돌, 배포 및 관리 복잡성 등의 단점을 내포함
- **비동기 처리 및 작업 분산 지원**: Redis 및 Celery를 활용하여 STT, OCR 등 장시간 소요되는 비동기 작업을 효율적으로 처리하고, 사용자 요청에 대한 응답성을 유지함
- **서비스간 라우팅 및 통합 API 게이트웨이**: 각 서비스는 독립적인 엔드포인트를 가지되, 공통적으로 요청을 분산 처리하는 라우터 계층 및 통합 API를 통해 외부 서비스와의 연동을 단순화함

---

### 2. 결정 (Decision)

**OCR, LLM Service, STT 서비스를 멀티레포(Multi-Repository) 구조로 분리 관리함**
공통 기능 및 설정은 common-utils에 모듈화하여 서비스 간 연계 및 확장을 지원함

```bash
llm_gateway/
├── ocr-service/          # OCR 서비스 (독립 레포)
├── stt-service/          # STT 서비스 (독립 레포)
└── common-utils/         # 공통 유틸 및 설정 (독립 레포)
    ├── logging/          # 공통 로깅 설정
    └── config/           # 환경설정 및 공통 설정 모듈
```

---

### 3. 고려된 대안 (Alternatives Considered)

| 아키텍처                          | 장점                                              | 단점                                                        |
| --------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| **모노레포**(Monorepo)            | 코드 관리와 통합 배포가 쉬움, 개발 환경 통일 가능 | 빌드 및 테스트 속도 저하, 서비스별 권한 및 배포 분리 어려움 |
| **멀티레포**(Multirepo) ✅ 선택됨 | 서비스별 독립 개발/배포 용이, 작업 충돌 최소화    | 공통 코드 관리 복잡, 서비스 간 연동 이슈 처리 필요          |

---

### 4. 결과 (Consequences)

- **장점:**

  - 서비스별로 독립적인 관리 체계를 유지하여 각 서비스의 개발, 배포 주기를 유연하게 설정 가능
  - Redis, Celery를 통한 비동기 처리 및 요청 분산으로 응답성과 효율성 확보
  - 공통 Router 계층을 통해 서비스 간 통합 요청 처리 가능, 아키텍처 확장 용이

- **단점:**

  - 공통 코드(`common-utils`)의 관리와 배포 자동화 필요, 버전 충돌 가능성 존재
  - 서비스 간 연계 로직 및 의존성 관리 복잡, 유지보수 시 추가 개발 필요
  - 레포 수 증가에 따른 중앙 관리 및 모니터링 시스템 필요, 통합 이슈 관리와 배포 체계 도입 필요

---

### 5. 추가 노트 (Optional)

- **공통 코드 배포 방식:** `common-utils`는 git 서브모듈 또는 사설 PyPI 패키지로 배포 관리 예정. 버전 관리 체계 마련 필요
- **서비스 확장 고려:** 새로운 AI 서비스 추가 시 현재 아키텍처의 확장성이 유리함