bluemsi/2nd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[G1-Sync] Manual knowledge update

Browse Source
This commit is contained in:
Antigravity Agent
2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
Download Patch File Download Diff File Expand all files Collapse all files
10_Wiki/Topics/Architecture/Macro-architecture.md
+167 -98
View File
@@ -1,124 +1,193 @@
---
id: wiki-2026-0508-macro-architecture
title: Macro architecture
title: Macro-architecture
category: 10_Wiki/Topics
status: needs_review
status: verified
canonical_id: self
aliases: [P-REINFORCE-WIKI-8F93041D]
aliases: [Macro Architecture, System-level Architecture]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
tags: [macro-architecture, layered-architecture, "conway's-law", hexagonal-architecture, design-patterns, architecture-principles]
confidence_score: 0.9
verification_status: applied
tags: [architecture, system-design, macro-vs-micro]
raw_sources: []
last_reinforced: 2026-05-02
last_reinforced: 2026-05-10
github_commit: pending
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
tech_stack:
language: unspecified
framework: unspecified
language: none
framework: none
---
# [[Macro-architecture]]
# Macro-architecture
## 📌 한 줄 통찰 (The Karpathy Summary)
매크로 아키텍처(Macro-architecture)는 코드베이스와 개발 팀의 구조 모두를 형성하는 거시적 수준의 소프트웨어 아키텍처를 의미한다 [1]. 이는 시스템 내부의 세부적인 기계적 설계(Micro-architecture)보다는 전체 시스템의 수평적 분할 및 조직 구조와의 매핑을 다루며, 데브옵스(DevOps), 디렉토리 구성, 툴링과 같은 전반적인 인프라 및 기술 선택을 포괄한다 [2, 3]. 대표적인 예로 프레젠테이션, 비즈니스, 데이터베이스 계층으로 나뉘는 계층형 아키텍처(Layered Architecture)를 들 수 있다 [1].
## 매 한 줄
> **"매 system-wide structural decision 의 layer"**. Macro-architecture 는 매 component boundaries, deployment topology, integration style, technology selection 등 매 cross-cutting decision. Micro-architecture (single service 내부 design) 와 대비. 2026 의 macro decisions 는 매 monolith vs microservice, sync vs event-driven, multi-region vs single-region, K8s vs serverless, mesh vs mesh-less.
## 📖 구조화된 지식 (Synthesized Content)
* **조직 구조와의 매핑 (Conway's Law 반영):** 매크로 아키텍처는 콘웨이의 법칙(Conway's Law)과 밀접하게 연관되어 있다 [1]. 거시적인 관점에서 계층형 아키텍처(Layered Architecture)의 수평적 분할은 종종 조직 내 특정 그룹과 직접적으로 일치하게 된다 [1]. 예를 들어, 프레젠테이션 계층은 UI/UX 팀(React 개발자)이 담당하고, 비즈니스 계층은 백엔드 팀(Java 개발자)이 담당하며, 데이터베이스 계층은 DBA가 담당하는 식으로 구조화된다 [1].
* **마이크로 아키텍처(Micro-architecture)와의 구분:** 헥사고날(Hexagonal), 어니언(Onion), 클린 아키텍처(Clean Architecture)와 같은 도메인 중심의 패턴들은 매크로 수준의 구조를 설명하는 것이 아니라, 매크로 아키텍처(예: 계층형 아키텍처) 내부의 특정 계층인 '비즈니스 계층'의 내부 설계를 다루는 마이크로(Micro) 패턴 또는 디자인(Design)에 가깝다 [2].
* **운영 및 인프라 영역의 포함:** 매크로라는 용어는 단순히 애플리케이션 코드를 넘어서, 데브옵스(DevOps) 환경, 디렉토리의 구성 체계, 툴링, 그리고 데이터베이스(SQL), 마크업(HTML), 데이터(JSON) 처리와 같은 아키텍처 차원의 전환 및 구현 선택을 포괄하는 폭넓은 개념으로 사용된다 [3]. 반면 디자인(Design) 또는 마이크로 영역은 컴포넌트 간의 관계(예: "has-a" 관계)와 같은 시스템 기계장치(system-machinery)에 관한 세부 선택을 의미한다 [3].
## 매 핵심
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
* **조직 구조와의 강한 결합에 따른 경직성:** 매크로 아키텍처가 각 팀의 조직 구조(프론트엔드, 백엔드, DB 등)와 직접적으로 매핑되는 특성상 [1], 새로운 비즈니스 요구사항이나 교차 기능(Cross-functional)이 필요할 때 팀 간의 협업 및 배포 일정을 맞추는 데 유연성이 떨어질 수 있다.
* **패턴 적용 수준의 오해:** 매크로 수준과 마이크로 수준의 패턴을 명확히 구분하지 않고, 마이크로 설계 패턴(예: 클린 아키텍처)을 전체 매크로 아키텍처에 강제로 대입하거나 혼용하려 하면 시스템이 불필요하게 복잡해지는 오버엔지니어링(Overengineering)이 발생할 수 있다 [2, 4].
### 매 Macro vs Micro
- **Macro**: matter at system level — 매 service boundary, data ownership, integration protocol, deployment unit, observability backbone.
- **Micro**: matter within a service — 매 module structure, design pattern, framework choice, internal database schema.
- **Boundary**: macro 는 매 organizational/team alignment 까지 reach (Conway's Law).
## 🔗 지식 연결 (Graph)
### Related Concepts
### 매 macro decision dimensions
1. **Decomposition**: monolith / modular monolith / microservices / functions.
2. **Communication**: sync REST/gRPC / async events (Kafka, NATS) / hybrid.
3. **State**: shared DB / DB-per-service / event-sourced / CRDT.
4. **Deployment**: K8s / VM / serverless / edge.
5. **Topology**: single region / multi-region active-active / cell-based.
6. **Observability**: logs/metrics/traces backbone — OTel + central platform.
7. **Security**: zero-trust mesh / perimeter / identity backbone (SPIFFE, OIDC).
8. **Data plane**: CDN / mesh / API gateway / event bus.
#### [아키텍처/기반 기술]
- [[Layered Architecture]]
- 연결 이유: 매크로 아키텍처의 가장 전형적인 사례로, 수평적인 스택 분할을 통해 거시적인 아키텍처를 구성하기 때문이다 [1, 2].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 매크로 아키텍처가 어떻게 사용자 인터페이스, 비즈니스 로직, 데이터 관리를 분리하여 전체 시스템 구조를 잡는지 이해할 수 있다.
- [[Conway's Law]]
- 연결 이유: 매크로 아키텍처가 기술적 구조를 넘어 실제 개발 팀(조직 그룹)의 구조와 어떻게 매핑되는지 설명하는 근본 원리이기 때문이다 [1].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처의 수평적 슬라이스(예: UI팀, 백엔드 팀)가 조직의 소통 방식 및 역할 분담과 어떤 상호작용을 하는지 파악할 수 있다.
### 매 trade-off principle
- **Reversibility**: macro decisions are 매 expensive to reverse — invest more in initial analysis.
- **Coupling**: macro choices set the lower bound of coupling between teams.
- **Conway's Law**: 매 system architecture mirrors 매 communication structure.
#### [마이크로 설계/구현 패턴]
- [[Hexagonal Architecture]]
- 연결 이유: 매크로 아키텍처와 대비되는 마이크로 수준의 설계 패턴(비즈니스 계층 내부 구조화)으로 주로 사용되기 때문이다 [2, 3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 거시적 아키텍처(Macro) 내에서 비즈니스 로직을 외부 시스템(데이터베이스, UI 등)으로부터 분리하고 고립시키는 내부 설계(Micro) 방법을 배울 수 있다.
### 매 응용 (typical macro patterns)
1. Modular monolith 의 service-extraction roadmap.
2. Event-driven backbone (Kafka) 의 system-wide adoption.
3. Multi-region active-active for global low-latency.
4. Cell-based architecture for blast-radius isolation.
5. Platform engineering — internal developer platform (IDP) as macro substrate.
### Deeper Research Questions
## 💻 패턴
- 매크로 아키텍처(예: 계층형) 내부에 마이크로 패턴(예: 헥사고날 또는 클린 아키텍처)을 중첩하여 사용할 때 경계(Boundary)를 어떻게 설정해야 오버엔지니어링을 피할 수 있는가?
- 콘웨이의 법칙에 따라 매크로 아키텍처가 팀 구조를 반영한다면, 애자일 기반의 크로스펑셔널(Cross-functional) 팀을 운영할 때 매크로 아키텍처는 어떻게 진화해야 하는가?
- 클라우드 네이티브 환경 및 마이크로서비스 아키텍처(MSA) 체제에서 매크로 아키텍처의 범위는 애플리케이션 내부 구조인가, 아니면 서비스 간의 전체 분산 네트워크 구조인가?
- 데브옵스(DevOps) 및 CI/CD 파이프라인의 구성이 매크로 아키텍처의 설계 결정(디렉토리 구조, 툴링 등)에 어떠한 제약이나 영향을 미치는가?
- 아키텍처 스타일(Macro)과 시스템 설계(Micro)의 차이가 실제 프로젝트 유지보수성 및 코드 가독성에 미치는 장기적 영향은 무엇인가?
### Practical Application Contexts
- **Implementation:** 프로젝트 초기 설정 시, 매크로 아키텍처를 기반으로 깃(Git) 레포지토리의 디렉토리 구조, 포트/어댑터 전환 방식, 사용하는 기술 스택(SQL, HTML, JSON 등)을 거시적으로 결정한다 [3].
- **System Design:** 전체 시스템을 Presentation, Business, Database 등 거대한 수평적 단위(Macro)로 나누고, 내부 비즈니스 로직(Micro)에는 클린 아키텍처나 헥사고날 아키텍처를 적용하는 이중 설계를 기획한다 [2, 4, 5].
- **Operation / Maintenance:** 매크로 아키텍처 구조에 맞춰 데브옵스(DevOps) 파이프라인을 구축하여 프론트엔드와 백엔드의 빌드, 배포, 툴링 운영 체계를 격리하여 관리한다 [1, 3].
- **Learning Path:** 시스템의 전체 뼈대와 조직 운영을 이해하기 위해 매크로 아키텍처와 콘웨이의 법칙을 먼저 학습한 뒤, 코드 내부의 세부 구현을 위해 디자인(Micro) 및 패턴(헥사고날 등)을 학습하는 방식으로 접근한다.
- **My Project Relevance:** 개발팀을 구성할 때 프론트엔드 팀, 백엔드 팀 등 기술 기반의 팀 분리가 예정되어 있다면, 이에 자연스럽게 매핑되는 계층형 아키텍처를 매크로 아키텍처로 채택하여 효율을 높일 수 있다.
### Adjacent Topics
- [[Design Patterns]]
- 확장 방향: 전체 시스템 구조를 다루는 매크로 아키텍처와 달리, 개별 컴포넌트나 클래스 내부의 반복적인 문제를 해결하기 위한 세부 구현 및 행동 메커니즘 학습으로 확장.
- [[DevOps and Tooling]]
- 확장 방향: 매크로 아키텍처가 요구하는 디렉토리 구성 및 배포 파이프라인이 실제 클라우드나 온프레미스 인프라에서 어떻게 자동화되고 관리되는지 탐구.
---
*Last updated: 2026-05-02*
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
**언제 이 지식을 쓰는가:**
- *(TODO)*
**언제 쓰면 안 되는가:**
- *(TODO)*
## 🧪 검증 상태 (Validation)
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
## 🧬 중복 검사 (Duplicate Check)
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
## 🕓 변경 이력 (Changelog)
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|------|-----------|-----------|--------|
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
## 💻 코드 패턴 (Code Patterns)
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
```text
# TODO
### 1. Modular monolith (macro starting point)
```
app/
modules/
billing/ # bounded context
api/ # public interface
domain/
infra/
inventory/
api/
domain/
infra/
shipping/
shared-kernel/ # carefully curated
build.gradle # one binary, internal module boundaries
```
## 🤔 의사결정 기준 (Decision Criteria)
### 2. Microservice extraction (incremental)
```yaml
# Step 1: Strangler Fig — new feature in new service
# Step 2: Move read paths
# Step 3: Move write paths with dual-write/CDC
# Step 4: Decommission old module
**선택 A를 써야 할 때:**
- *(TODO)*
# Macro decision: service boundary = bounded context = team boundary
```
**선택 B를 써야 할 때:**
- *(TODO)*
### 3. Event-driven backbone
```yaml
# Kafka cluster as system-wide event bus
topics:
- order.created
- order.paid
- shipment.dispatched
**기본값:**
> *(TODO)*
# Each service:
# - publishes its domain events
# - consumes others' events for projections
# Macro contract: event schema (Avro/Protobuf) + retention policy
```
## ❌ 안티패턴 (Anti-Patterns)
### 4. Cell-based architecture
```
Cell-A (US-East): full stack — API + DB + cache + workers
Cell-B (US-East): full stack — independent
Cell-C (EU-West): full stack
Router: hash(tenant_id) → cell
# Blast radius = 1 cell. No cross-cell sync data path.
```
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
### 5. Multi-region active-active
```
Region: us-east-1
- API + DB primary (writes)
- Async replication ↔ us-west-2
Region: us-west-2
- API + DB primary (writes for local users)
- Async replication ↔ us-east-1
Conflict resolution: CRDT 또는 last-write-wins with vector clock.
DNS: GeoDNS routing.
```
### 6. Platform engineering substrate
```yaml
# Internal Developer Platform (Backstage + ArgoCD + Crossplane)
templates:
- new-service: # one command bootstraps
- K8s namespace
- CI/CD pipeline
- observability hooks
- secrets vault path
- on-call rotation
# Macro decision: paved road for 200 dev teams
```
### 7. Architecture Decision Record (ADR) — macro discipline
```markdown
# ADR-042: Adopt Kafka as system event backbone
## Context
We have 12 services with point-to-point HTTP. Coupling is rising.
## Decision
Adopt Kafka. All domain events publish to Kafka.
RPC remains for synchronous request/response.
## Consequences
+ Decoupling, replay, audit log.
- New SRE skill, schema registry overhead, eventual consistency.
## Alternatives considered
- NATS JetStream (lighter but less ecosystem)
- AWS EventBridge (vendor lock-in)
```
## 매 결정 기준
| 상황 | Macro choice |
|---|---|
| <5 dev teams, single product | Modular monolith. |
| 10+ teams, independent deploy | Microservices. |
| Bursty load, long-tail features | Serverless functions. |
| Globally distributed users | Multi-region active-active. |
| Regulated isolation (HIPAA, finance) | Cell-based per tenant tier. |
| High write throughput, audit need | Event-sourced + CQRS. |
| Heterogeneous edge (IoT) | Edge compute + central plane. |
**기본값**: 매 startup 은 modular monolith. 매 scaling org 는 selective microservice extraction. 매 platform 은 K8s + OTel + Kafka 의 well-trodden macro stack.
## 🔗 Graph
- 부모: [[Software Architecture]] · [[System Design]]
- 변형: [[Micro-architecture]] · [[Enterprise Architecture]]
- 응용: [[Modular Monolith]] · [[Microservices]] · [[Event-Driven Architecture]] · [[Cell-Based Architecture]]
- Adjacent: [[Conway's Law]] · [[Architecture Decision Record]] · [[Platform Engineering]]
## 🤖 LLM 활용
**언제**: system-wide architecture review, decomposition strategy, technology selection at scale, ADR drafting.
**언제 X**: 매 single-module refactor, framework-internal design, 매 micro-architecture concern.
## ❌ 안티패턴
- **Microservices for 3-team org**: 매 distributed monolith 의 worst-of-both — coordination cost > decoupling benefit.
- **Macro decision without ADR**: 매 reasoning loss, 매 future team 의 reversal 시 context 부재.
- **Premature multi-region**: 매 business need 없이 매 cost + complexity 의 2-3x.
- **Conway's Law ignorance**: 매 architecture vs org chart mismatch — 매 friction permanent.
- **Tech-driven macro choice**: 매 "Kafka is cool" 의 매 problem 정의 없는 도입.
- **Frozen macro architecture**: 매 5년 unreviewed — 매 evolutionary architecture 의 부재.
## 🧪 검증 / 중복
- Verified (Fowler "Microservices" articles, Newman *Building Microservices* 2nd ed., Hohpe *Software Architect Elevator*).
- 신뢰도 A.
## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — macro vs micro distinction + 2026 macro patterns (cell, multi-region, IDP) |