---
id: pattern-architecture-separation
title: "Architecture Separation Pattern"
category: "Pattern_CrossCutting"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["layering", "아키텍처 분리", "관심사 분리", "separation of concerns", "layered architecture", "ports and adapters"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.88
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "cross-cutting", "architecture", "layering", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src 구조 (적용 예)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[Architecture Separation Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
아키텍처 분리는 "**관심사를 계층/모듈로 나누고, 의존은 한 방향(안정적인 쪽으로)으로만 흐르게**" 하는 것으로, 플랫폼이 달라도 UI/도메인/인프라를 섞지 않는 것이 유지보수의 토대다.

## 🧠 핵심 개념 (Core concepts)
1. **계층:** 인프라(core) → 역량(lib/도메인 서비스) → 기능(features) → 조립(entry). 위가 아래에 의존.
2. **관심사 분리:** UI / 도메인 로직 / I/O 를 섞지 않는다.
3. **의존성 역전:** 도메인이 인프라 *인터페이스* 에 의존, 구현은 주입.
4. **경계(ports & adapters):** 외부(DB/API/UI)는 어댑터로, 핵심은 순수.
5. **단일 책임:** 한 모듈은 한 가지 변경 이유.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 코드가 커지며 UI/로직/I/O 가 엉켜 변경이 두려울 때.
- **사용 조건:** 책임 경계를 식별 가능; 인터페이스로 추상화 가능.
- **장점:** 변경 격리, 테스트성(핵심 순수), 교체 용이(어댑터), 병렬 작업.
- **단점:** 초기 보일러플레이트, 과한 계층은 오버헤드("얇은 래퍼 지옥").
- **대안:** 모놀리식 단순 구조(소규모), 수직 슬라이스(기능별 풀스택), 모듈러 모놀리스.
- **실패 사례:** UI 에 비즈니스 로직 혼입; 도메인이 DB/프레임워크에 직접 의존(교체 불가); 순환 의존; 계층 우회(아래가 위 호출).

## 💻 코드 패턴 (Code patterns)
```text
features/ -> lib/도메인서비스 -> core/인프라     # 단방향 의존
domain depends on interface (IRepo, IAIService)  # 의존성 역전
adapter implements interface (FileRepo, AIService)
entrypoint wires them (composition root)         # 조립은 한 곳
```
적용 예: AstraAI 계층(core/lib/memory/retrieval/intelligence/features) + 인터페이스 서비스([[AstraAI 아키텍처 개요]], [[의존성 주입과 서비스 인터페이스]], [[모듈 시스템과 프로젝트 구성]]).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
계층이 많을수록 격리는 좋아지나 단순 변경도 여러 파일을 거친다 — 규모에 맞춰라. 흐름 가독성을 위해 *골격은 한 곳에* 남기는 절충도 유효([[ADR-0010 오케스트레이터 골격 모듈추출]]).

## 🛠️ 적용 사례 (Applied in summary)
AstraAI 전체 폴더 계층 + DI.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Repository Pattern]], [[Plugin Architecture Pattern]], [[Data Flow Pattern]], [[프로젝트 독립 설계 원칙]]
- **참조 맥락:** 작은 모델이 새 프로젝트의 폴더/계층 구조를 잡을 때 1차 원리.

## 📚 출처 (Sources)
- [S1] 일반 계층화/관심사 분리 지식(Clean/Hexagonal)
- [S2] AstraAI/src 구조 — 적용 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
