Architecture Decision Records¶

ADR 은 Umbra 의 중요한 기술 결정을 기록하는 문서입니다. "왜 이 선택을 했는가" 를 미래의 자신과 신규 팀원이 이해할 수 있게 보존하는 것이 목적입니다.

Why ADRs exist¶

기술 결정은 시간이 지나면 "왜 그랬는지" 가 흐려집니다. 결정 당시의 맥락, 제약 조건, 고려한 대안이 코드에 남지 않으면 6개월 후 같은 결정을 다시 논의하거나, 더 나쁜 경우 근거 없이 결정을 뒤집는 일이 생깁니다.

ADR 은 세 가지 가치를 제공합니다.

첫째, 결정의 맥락 보존 입니다. 당시 어떤 제약과 선택지가 있었는지 기록하여 미래에 같은 논의를 반복하지 않습니다.

둘째, 신규 팀원 온보딩 입니다. 코드만 보면 "왜 이렇게 되어 있지" 가 보이지 않습니다. ADR 은 아키텍처의 의도를 전달합니다.

셋째, 재검토 기준 제공 입니다. 각 ADR 은 "재검토가 필요한 신호(Revisit triggers)" 를 포함합니다. 조건이 충족되면 새 ADR 로 재평가합니다.

Format¶

Umbra 의 ADR 은 Michael Nygard 의 표준 형식을 따릅니다. 템플릿은 .templates/adr.template.md 를 참조하세요.

Required sections¶

Status — 결정의 현재 상태 (Proposed / Accepted / Deprecated / Superseded)
Context — 결정이 필요한 배경
Decision — 내린 결정
Consequences — 결정의 결과 (Positive / Negative / Neutral)
Alternatives considered — 거부한 대안과 이유

Optional sections¶

Compliance — 결정 준수를 어떻게 확인하는가
Revisit triggers — 재검토가 필요한 조건
References — 외부 자료
Related ADRs — 연관 결정들

Lifecycle¶

Proposed → Accepted → Deprecated
                   ↘
                     Superseded by ADR-XXXX

Proposed — 제안 단계, 논의 중
Accepted — 승인되어 유효한 결정
Deprecated — 더 이상 유효하지 않지만 참고용으로 보존
Superseded — 다른 ADR 로 완전히 대체됨. Front-matter 에 superseded_by 필수

Numbering¶

ADR 은 4자리 일련번호 로 관리됩니다. 번호는 순차 증가하며 재사용하지 않습니다.

최신 번호 확인: ls docs/adr/*.md | sort | tail
번호 건너뛰기 금지, 빈 번호는 결정이 Proposed 단계에서 폐기되었음을 의미

When to write an ADR¶

모든 결정을 ADR 로 남기지는 않습니다. 다음 기준에 해당하면 ADR 대상입니다.

ADR 대상¶

되돌리기 어려운 결정 — 데이터베이스 선택, 언어 선택, 주요 아키텍처 패턴
팀 간 합의가 필요한 결정 — 코딩 컨벤션, 브랜치 전략
비용 또는 위험이 큰 결정 — 외부 서비스 선택, 보안 관련 결정
반복적으로 질문받는 결정 — "왜 X 대신 Y 를 썼나요?" 가 반복되는 결정

ADR 대상 아님¶

코드 수준 결정 — 함수 이름, 단일 구현 세부사항
명백한 결정 — 업계 표준을 따르는 것
일시적 결정 — 곧 바뀔 임시 선택

Index¶

전체 ADR 목록입니다. 주제별로 묶어 표시합니다.

Language & Framework¶

#	Title	Status
0001	Language: Go	Accepted
0002	Discord Library: disgo	Accepted
0003	HTTP Framework: Echo	Accepted
0008	Frontend: Bun + Vite + React	Accepted
0028	Frontend Routing & Data: TanStack	Accepted

Data & Infrastructure¶

#	Title	Status
0004	Database: Neon Serverless PostgreSQL	Accepted
0005	DB Layer: sqlc	Accepted
0006	Migration: Atlas	Accepted
0007	Cache & Queue: Redis	Accepted
0009	Monorepo: Bun workspace (single go.mod)	Accepted
0010	Deploy: Fly.io + Vercel	Accepted
0020	PostgreSQL Schema per Domain	Accepted
0021	PK Type: UUID v7	Accepted

Business Model¶

#	Title	Status
0011	Hybrid License Model	Accepted
0012	License and Subscription Separation	Accepted
0013	Payment: Toss Billing	Accepted
0022	Payment Time Jitter	Accepted
0027	Message Content Exclusion	Accepted

Workflow & Events¶

#	Title	Status
0014	Recovery via Temporal Workflow	Accepted
0015	asynq vs Temporal Split	Accepted
0016	Outbox Pattern for Cross-Domain Events	Accepted
0017	Process Separation: Bot / API / Worker	Accepted
0018	Domain Code Sharing over RPC	Accepted

Architecture & Recovery Design¶

#	Title	Status
0019	Pragmatic Hexagonal Architecture	Accepted
0023	Live Sync Batch Processing	Accepted
0024	Restore Mode: Sync (Git Reset Style)	Accepted
0025	Snapshot JSONB Storage	Accepted
0026	Anti-Nuke MVP Inclusion	Accepted

Frontend UI & Future¶

#	Title	Status
0029	UI Library: shadcn/ui	Accepted
0030	OpenAPI Type Synchronization	Accepted
0031	Future Rust Rewrite on Nabi Runtime	Proposed
0032	Frontend Linter & Formatter: Biome	Accepted

How to create a new ADR¶

새 ADR 을 작성하는 절차입니다.

# 1. 최신 번호 확인
ls docs/adr/*.md | sort | tail -1

# 2. 템플릿 복사
cp docs/.templates/adr.template.md docs/adr/NNNN-your-decision-name.md

# 3. Front-matter 와 본문 작성
#    - title 은 "ADR-NNNN: {Decision Title}" 형식
#    - status 는 Proposed 로 시작

# 4. 이 README 의 Index 에 새 항목 추가

# 5. PR 생성, 팀 리뷰

# 6. 승인 후 status: Accepted 로 변경

How to supersede an ADR¶

기존 ADR 을 새 결정으로 대체하는 절차입니다.

# 1. 새 ADR 작성 (위 절차)
# 2. 기존 ADR 의 status 를 Superseded 로 변경
# 3. 기존 ADR front-matter 에 superseded_by 추가
# 4. 기존 ADR 본문 상단에 "Superseded by ADR-XXXX" 명시
# 5. 새 ADR 의 Related ADRs 섹션에 기존 ADR 링크

기존 ADR 을 삭제하지 않습니다. 역사적 맥락 보존이 중요합니다.