---
template: plan
version: 1.3
feature: ioc-base-structure
date: 2026-04-24
author: sal
project: youlbot
status: Draft
---

# ioc-base-structure Planning Document

> **Summary**: 절차형 chat.py를 IoC 컨테이너 기반 클래스 구조로 리팩토링하여 재사용성과 확장성을 확보한다.
>
> **Project**: youlbot
> **Author**: sal
> **Date**: 2026-04-24
> **Status**: Draft

---

## Executive Summary

| Perspective | Content |
|-------------|---------|
| **Problem** | 단일 파일 절차형 스크립트로 서비스 교체·테스트·확장이 어렵다 |
| **Solution** | dependency-injector 기반 IoC 컨테이너로 서비스 분리 및 DI 적용 |
| **Function/UX Effect** | LLM 백엔드 교체(MLX↔OpenAI↔Ollama) 및 DB 연동이 코드 변경 없이 가능 |
| **Core Value** | 재사용 가능한 서비스 계층 + 디자인 패턴 적용으로 장기 유지보수성 확보 |

---

## Context Anchor

| Key | Value |
|-----|-------|
| **WHY** | 절차형 코드의 결합도를 낮춰 기능 추가·교체를 안전하게 하기 위함 |
| **WHO** | 개발자 (sal) — 단독 개발, 추후 팀 확장 가능성 있음 |
| **RISK** | MLX 모델 로딩이 무거워 Singleton 관리 실수 시 메모리 이슈 |
| **SUCCESS** | 각 서비스가 독립적으로 교체/테스트 가능하고 Container 설정만으로 행동 변경 |
| **SCOPE** | Phase 1: 기본 구조 + MLX 서비스 / Phase 2: DB(MySQL) 연동 |

---

## 1. Overview

### 1.1 Purpose
현재 `chat.py`는 모델 로딩, 히스토리 관리, 스트림 생성, CLI 루프가 한 파일에 혼재한다.
IoC 컨테이너와 디자인 패턴을 적용해 각 책임을 분리하고, 의존성을 주입으로 연결한다.

### 1.2 Background
- 육아·금융 상담 챗봇 '율봇'의 초기 구조 정립
- LLM 백엔드를 MLX로 시작하되 OpenAI / Ollama 전환이 설정 변경만으로 가능해야 함
- MySQL DB 연동이 예정되어 있어 DB 서비스 레이어 선제 설계 필요

---

## 2. Scope

### 2.1 In Scope
- [ ] IoC Container 설정 (`app/container.py`)
- [ ] Strategy 패턴으로 LLM 백엔드 추상화 (`AbstractModelService` + `MlxModelService`)
- [ ] `ChatService` — 대화 오케스트레이션
- [ ] `HistoryService` — 히스토리 관리 (trim 포함)
- [ ] `DatabaseService` — MySQL 연결 (mysqlclient)
- [ ] Observer/EventBus — 스트림 토큰 이벤트 발행
- [ ] `CliUiService` — CLI 입출력
- [ ] `main.py` — 컨테이너 부트스트랩 진입점
- [ ] `config.py` — 환경변수 기반 설정

### 2.2 Out of Scope
- 웹 API (FastAPI 등) 레이어
- 인증/세션 관리
- 테스트 코드 (별도 Phase)

---

## 3. Requirements

### 3.1 Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-01 | IoC Container에서 모든 서비스를 Singleton/Factory로 등록·해석 | High |
| FR-02 | LLM 백엔드를 Strategy 인터페이스로 추상화, 구현체 교체 가능 | High |
| FR-03 | ChatService가 HistoryService·ModelService·EventBus를 주입받아 동작 | High |
| FR-04 | 스트림 토큰 출력을 Observer 패턴으로 처리 (핸들러 교체 가능) | Medium |
| FR-05 | DatabaseService가 MySQL 연결을 캡슐화, 다른 서비스에서 주입받아 사용 | Medium |
| FR-06 | 설정은 환경변수 + config.py에서 중앙 관리 | High |

### 3.2 Non-Functional Requirements

| Category | Criteria |
|----------|----------|
| 확장성 | 새 LLM 백엔드 추가 시 AbstractModelService 구현만으로 완성 |
| 결합도 | 서비스 간 직접 import 없이 Container 통해서만 의존 |
| 메모리 | MLX 모델은 Singleton으로 1회만 로딩 |

---

## 4. Success Criteria

- [ ] `python -m app.main` 실행 시 기존 chat.py와 동일하게 동작
- [ ] `MlxModelService`를 `MockModelService`로 교체해도 나머지 코드 변경 없음
- [ ] `Container` 설정만 바꿔서 CLI → 다른 UI로 전환 가능한 구조

---

## 5. Risks

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| MLX Singleton 초기화 시간 (~수초) | Medium | High | 로딩 중 진행 표시 유지 |
| dependency-injector 버전 충돌 | Low | Low | requirements.txt 버전 고정 |
| MySQL 연결 설정 누락 | Medium | Medium | 미설정 시 graceful skip |

---

## 6. Architecture Decisions

| Decision | Selected | Rationale |
|----------|----------|-----------|
| IoC 라이브러리 | dependency-injector | DeclarativeContainer, Singleton/Factory 지원 |
| LLM 추상화 | Strategy 패턴 | 백엔드 교체 시 코드 변경 최소화 |
| 스트림 처리 | Observer/EventBus | 출력 핸들러(CLI, 파일, WebSocket)를 분리 |
| DB | MySQL (mysqlclient) | 단순 Service로 캡슐화, 추후 ORM 추가 가능 |

---

## 7. Directory Structure

```
youlbot/
├── app/
│   ├── __init__.py
│   ├── config.py              # 환경변수 기반 설정
│   ├── container.py           # IoC DeclarativeContainer
│   ├── main.py                # 부트스트랩 진입점
│   └── services/
│       ├── model/
│       │   ├── base.py        # AbstractModelService (Strategy 인터페이스)
│       │   └── mlx_model.py   # MlxModelService (Strategy 구현체)
│       ├── chat/
│       │   ├── chat_service.py
│       │   └── history_service.py
│       ├── db/
│       │   └── mysql_service.py
│       ├── ui/
│       │   └── cli_service.py
│       └── events/
│           ├── event_bus.py   # Observer EventBus
│           └── handlers.py    # StreamTokenHandler 등
├── chat.py                    # 기존 파일 (보존)
└── requirements.txt
```