아키텍처 재사용성 및 확장성 검증 (cloc 분석)

1. 프로젝트 개요

다양한 도메인의 AI 서비스를 신속하게 구축하고 운영하기 위한 통합 서버 프레임워크를 제작했다. 본 프로젝트는 반복되는 인프라 설정 리소스를 최소화하고, AI 모듈의 재사용성을 극대화하는 것을 목표로 한다.

• 배경: 프로젝트마다 반복되는 DB, MQ, Redis 설정 및 AI 인터페이스 설계 리소스 절감
• 주요 기능:
  • Web API Server: 사용자 요청 처리 및 서비스 로직 실행
  • Middleware Server: 추론 시간이 긴 AI 작업의 비동기 메시징 처리
• 기술 스택: Python 3.11, FastAPI, LangChain, RabbitMQ, Redis, MongoDB, MySQL

참고글: LLM 인터페이스 설계 https://wavicle.tistory.com/21

 

 

2. 아키텍처 설계

AppContext를 중심으로 모든 구성 요소의 생명주기를 통합 관리한다. 설정 파일(cfg.json)에 따라 서버의 역할을 유동적으로 전환할 수 있도록 했다.

📦src
 ┣ 📂core       # 공통 유틸리티 및 응답 규격
 ┣ 📂handler    # 인프라 연결 (DB, RMQ, Redis, WS)
 ┣ 📂service    # 비즈니스 도메인 (AI, Auth, Files, Tag)
 ┃ ┣ 📂ai       # LLM, RAG 로직 및 프롬프트 에셋
 ┃ ┗ 📂conf     # 서버별 JSON 설정 파일
 ┣ 📂sql        # DB 초기화 및 시드 스크립트
 ┗ 📂utils      # 비동기 및 통신 유틸리티

계층 (Layer)역할 및 특징

Core & Handler	인프라(DB, Messaging, WS) 연결 규격 표준화
Service	도메인 로직(AI, Auth)을 모듈화하여 인터페이스 기반으로 구현
Context	구성 요소의 init-process-destroy 생명주기를 강제하여 리소스 효율화

 

3. 정량 평가

초기 아키텍처 모델인 '방토리(Bangtori_AI)'를 기준으로 후속 프로젝트(둥지동지, DOQ)에 AI 서비스 모듈이 어떻게 이식되고 확장되었는지 코드 라인 단위(LOC)로 분석했다.

분석 단계대상 프로젝트동일/수정 LOC추가 LOC주요 성과

Step 1. 이식	둥지동지	85 / 46	141	인터페이스 표준화 확인
Step 2. 고도화	DOQ	68 / 20	1,435	기능적 폭발적 확장성 증명
Step 3. 표준화	통합 서버	68 / 20	1,438	범용 프레임워크로 정립

 

4. 단계별 분석 및 인사이트

[step1] 도메인 변경에도 유지되는 인터페이스 (방토리 → 둥지동지)

cloc --diff "/Bangtori_AI/src/service/ai" "/dungdong-BE/src/service/ai"
       5 text files.
       7 text files.
      18 files ignored.

github.com/AlDanial/cloc v 2.08  T=0.10 s (92.4 files/s, 7805.8 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python
 same                            0              0             13             85
 modified                        3              0             11             46
 added                           4             31            105            141
 removed                         1             59            117            103
JSON
 same                            0              0              0              0
 modified                        0              0              0              0
 added                           0              0              0              0
 removed                         1              0              0             49
-------------------------------------------------------------------------------
SUM:
 same                            0              0             13             85
 modified                        3              0             11             46
 added                           4             31            105            141
 removed                         2             59            117            152
-------------------------------------------------------------------------------

• 분석: 주거 정보 서비스에서 룸메이트 매칭 서비스로 도메인이 변경되었음에도 핵심 로직 수정(46라인) 대비 신규 기능 추가(141라인)가 약 3배 높게 나타났다.
• 인사이트: 초기 설계된 AI 인터페이스가 서로 다른 비즈니스 도메인에서도 큰 구조 변경 없이 즉시 작동할 수 있음을 확인했다.

 

[step2] OCP 원칙 준수 (방토리 → DOQ)

cloc --diff "/Bangtori_AI/src/service/ai" "/doq-server/src/service/ai"
       5 text files.
      11 text files.
       9 files ignored.

github.com/AlDanial/cloc v 2.08  T=0.05 s (266.2 files/s, 56654.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python
 same                            0              0              7             68
 modified                        2              0              7             20
 added                           9            366            685           1435
 removed                         2             70            127            146
JSON
 same                            0              0              0              0
 modified                        0              0              0              0
 added                           0              0              0              0
 removed                         1              0              0             49
-------------------------------------------------------------------------------
SUM:
 same                            0              0              7             68
 modified                        2              0              7             20
 added                           9            366            685           1435
 removed                         3             70            127            195
-------------------------------------------------------------------------------

• 분석: 기존 로직의 수정 사항이 20라인 미만으로 급격히 감소한 반면, 추가된 코드는 1,435라인으로 초기 모델 대비 약 21배 확장되었다.
• 인사이트: 핵심 핸들러(llm_manager 등)를 수정하지 않고도 RAG, 세션 관리 등 복잡한 기능을 유연하게 결합할 수 있는 개방-폐쇄 원칙(OCP)을 준수하도록 했다.

 

[Step 3] 표준화 (방토리 → python-server)

cloc --diff "/Bangtori_AI/src/service/ai" "/python-server/src/service/ai"
       5 text files.
      12 text files.
      11 files ignored.

github.com/AlDanial/cloc v 2.08  T=0.06 s (270.1 files/s, 53990.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python
 same                            0              0              7             68
 modified                        2              0              7             20
 added                          10            369            697           1438
 removed                         2             70            127            146
JSON
 same                            0              0              0              0
 modified                        0              0              0              0
 added                           0              0              0              0
 removed                         1              0              0             49
-------------------------------------------------------------------------------
SUM:
 same                            0              0              7             68
 modified                        2              0              7             20
 added                          10            369            697           1438
 removed                         3             70            127            195
-------------------------------------------------------------------------------

• 분석: DOQ의 고도화된 구조를 그대로 유지하면서 통합 서버 템플릿으로 발전시켰다.
• 인사이트: 특정 프로젝트에 종속되지 않는 범용적인 Unified Server Architecture를 정립했다. 이로 인해 신규 서비스 구축 시 인프라 설계 리소스를 80% 이상 절감할 수 있었다.

 

3. 결론

"기존 로직 수정 20라인 미만, 21배 이상의 기능 확장을 수용하는 견고한 아키텍처"

• 높은 이식성: 도메인이 완전히 다른 3개의 프로젝트를 거치는 동안 핵심 AI 인터페이스의 수정률을 최소화(20 LOC 미만) 하여 유지보수 효율을 극대화했다.
• 복합 확장성: 표준화된 핸들러 생명주기(init-process-destroy) 덕분에 초기 모델 대비 시스템 복잡도가 비약적으로 증가하는 과정에서도 안정적인 제어가 가능했다.
• 비용 절감: 검증된 아키텍처를 통해 신규 AI 서비스 프로토타이핑 시 설계 및 인프라 구축에 소요되는 리소스의 80% 이상을 절감할 수 있음을 데이터를 통해 입증했다.