🎯 아키텍처 접근을 ‘최소한의 단계’로 단순화하면 단 3단계다
✔ 1단계: “나는 무엇이 자주 바뀔까?”부터 찾기
✔ 2단계: “바뀌는 것을 어떻게 분리하지?”를 고민
✔ 3단계: “그걸 분리한 뒤 코드가 어떻게 생기지?”를 보는 것
단 3단계.
여기서 Clean Architecture나 Hexagonal이 자동으로 떠오름.
🔥 1단계: "자주 바뀌는 것"만 찾으면 70% 끝난다
아키텍처의 본질은 1개야:
변하는 것과 변하지 않는 것을 분리하기
실제로 네 MCP Hub 기준으로 보면:
✔ 자주 바뀌는 것
- 모델 제공자(OpenAI, Anthropic, Groq...)
- 툴(MCP Tool들: FS, DB, Web, GPU 등)
- 클라이언트 타입(WebSocket, API)
- DB나 캐시 기술
- 스토리지 경로, 구성
- API 스펙
- 인증 전략
✔ 잘 안 바뀌는 것(핵심 로직)
- 세션 관리
- 메시지 라우팅
- 메시지 이벤트 흐름
- 모델 호출이라는 개념 자체
- Tool 호출이라는 개념
- 스트림 전달 규칙
이걸 찾으면 “아키텍처 선택”이 이미 끝난 거나 다름없어.
왜냐면:
- 외부 의존성이 자주 바뀜 → Hexagonal / Clean
- 내부 규칙 고정 → Domain 중심 설계
- 스트림/이벤트 흐름 존재 → Event-driven 구조 필요
너의 프로젝트는 이 특징을 가짐 → 아키텍처 답이 자동으로 정해지는 것.
🔥 2단계: 바뀌는 것들은 “인터페이스로 추상화” 한다
아키텍처 이름은 어려워도 실제 개념은 한 줄임:
바뀌는 것들은 전부 인터페이스(Port)로 만들고, 실제 구현(Adapter)은 나중에 끼운다.
예시로:
# Port (추상화) class ModelProviderPort: async def stream(self, messages: list): ...
# Adapter (구현체) class OpenAIProvider(ModelProviderPort): async def stream(...): # openai 호출 코드
class GroqProvider(ModelProviderPort): async def stream(...): # groq 호출 코드
이렇게 구조가 자동으로 분리됨.
이게 바로 “헥사고날 아키텍처”고,
Clean Architecture의 핵심 규칙인 “의존성 역전 원칙”이야.
어려운 용어를 몰라도 패턴은 그냥 이렇게 생겨.
🔥 3단계: 실제 폴더 구조에 녹이면 Clean Architecture가 완성됨
단순하게 이렇게 나누면 끝이야:
app/ domain/ # 규칙(바뀌지 않는 것) application/ # 유즈케이스 ports/ # 추상화 인터페이스 adapters/ # 실제 구현 presentation/ # FastAPI 등 I/O
딱 여기까지만 이해하면 Clean Architecture가 90% 끝난 것.
🧘 비유로 한 번 더 설명해줄게 (완전 쉬운 버전)
🍔 햄버거 가게를 만든다고 해보자
바뀌는 것:
- 패티 공급자
- 소스 레시피
- 매장 위치
- POS 장비
바뀌지 않는 것:
- 햄버거 만드는 규칙 (빵→패티→야채→소스)
그럼 어떻게 구조화할까?
- “패티 공급자”는 인터페이스로 만들고 실제 공급업체끼리 교체 가능하게
- “POS 장비”는 인터페이스로 만들고 실제 기기는 어댑터로 구성
- 햄버거 조립 로직은 동일
이게 바로 Clean Architecture의 핵심 원리.
너는 그냥 “바뀌는 것들은 자리를 따로 마련해둔다”라고만 생각하면 돼.
🎯 그래서 너는 어디서 시작하면 되냐?
✔ 1) “내 프로젝트에서 자주 바뀌는 것 5개”만 적어
✔ 2) 그걸 “인터페이스(Port)”로 만들자
✔ 3) 나머지 “고정 규칙”은 domain/application에 둔다
끝.