---
id: pattern-data-flow
title: "Data Flow Pattern"
category: "Pattern_CrossCutting"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["data flow", "데이터 흐름", "pipeline", "transform", "boundary normalization"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.86
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "cross-cutting", "data-flow", "pipeline", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/retrieval/*, src/features/providers/* (적용 예)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[Data Flow Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
데이터 흐름 설계의 핵심은 "**경계에서 정규화하고(입력 검증·형식 통일), 내부는 단일 형태로 다루며, 변환을 작은 순수 단계의 파이프라인으로**" 만드는 것이다 — 그러면 어디서 무엇이 변하는지 추적된다.

## 🧠 핵심 개념 (Core concepts)
1. **경계 정규화:** 외부 입력(API/파일/사용자)을 들어오자마자 내부 표준 형태로 변환·검증.
2. **단일 내부 모델:** 내부는 하나의 형태만 — 분기/특수처리를 가장자리로.
3. **파이프라인:** 변환을 작은 순수 단계로 연결(test 가능).
4. **출력 정규화:** 다양한 백엔드를 같은 출력 형식으로(예: SSE).
5. **불변 전달:** 단계 간 데이터를 변형 대신 새 값 생성.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 이질적 소스/싱크가 많고 변환 단계가 여러 개일 때.
- **사용 조건:** 표준 내부 모델 정의 가능; 단계 분해 가능.
- **장점:** 추적성, 테스트성(순수 단계), 소스/싱크 추가 용이, 버그 격리.
- **단점:** 변환 레이어 비용, 과한 추상화는 오버헤드.
- **대안:** 직접 결합(소규모), 스트림 처리(대용량), 이벤트 버스(느슨 결합).
- **실패 사례:** 경계 검증 누락으로 내부에 오염 전파; 내부에 외부 형식 누수(공급자별 분기 산재); 가변 전달로 단계 간 부작용.

## 💻 코드 패턴 (Code patterns)
```text
internal = normalizeAtBoundary(externalInput)      # 들어올 때 1회 정규화 + 검증
result   = stage3(stage2(stage1(internal)))        # 작은 순수 단계 파이프라인
output   = toStandardFormat(result)                # 나갈 때 형식 통일 (예: SSE)
```
적용 예: [[LLM 프로바이더 추상화]](공급자별 입력 정규화→공통 SSE 출력), [[RAG 검색 파이프라인]](tokenize→score→fuse→budget).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
경계 정규화는 비용이지만, 생략하면 특수처리가 코드 전체로 번진다 — "차이는 가장자리에서 흡수" 원칙([[AITRAIN 프로바이더 추상화]]).

## 🛠️ 적용 사례 (Applied in summary)
AstraAI provider 어댑터, retrieval 파이프라인.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[State Management Pattern]], [[Repository Pattern]], [[API Client Pattern]], [[Architecture Separation Pattern]]
- **참조 맥락:** 작은 모델이 입출력 변환이 많은 코드를 설계할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 데이터 흐름/파이프라인 지식
- [S2] AstraAI/src/retrieval/*, features/providers/* — 적용 예

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