youlbot/docs/01-plan/features/ioc-base-structure.plan.md

template, version, feature, date, author, project, status

template	version	feature	date	author	project	status
plan	1.3	ioc-base-structure	2026-04-24	sal	youlbot	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