콘텐츠로 이동

Umbra Documentation

Umbra 프로젝트의 모든 설계 결정과 도메인 지식이 이곳에 정리됩니다. 코드는 무엇을 하는지만 보여주고, 문서는 왜 그렇게 했는지를 설명합니다.

Who this is for

이 문서는 세 가지 독자를 가정합니다.

  • Engineer — 시스템을 설계하고 아키텍처 결정을 이해해야 하는 독자. architecture/, adr/, domain/ 을 주로 참조합니다.
  • Developer — 코드를 작성하고 기능을 구현하는 독자. guides/, flows/, data/ 를 주로 참조합니다.
  • All — 프로젝트의 정체성과 방향성을 알아야 하는 독자. overview/, roadmap/ 을 주로 참조합니다.

문서마다 front-matter 의 audience 필드에 대상 독자가 명시됩니다.

For first-time readers

처음 접하시는 분은 이 순서로 읽는 것을 권장합니다.

  1. overview/what-is-umbra.md — Umbra가 무엇을 푸는 SaaS 인가
  2. overview/value-proposition.md — 핵심 가치 제안
  3. overview/glossary.md — 용어 사전
  4. architecture/overview.md — 전체 시스템 구성
  5. architecture/tech-stack.md — 기술 스택과 선택 이유

By category

Category Purpose Primary audience
overview/ 프로젝트 정체성 입문 All
architecture/ 시스템 아키텍처와 구조 Engineer
domain/ 각 도메인의 모델과 규칙 Engineer, Developer
flows/ End-to-end 시나리오와 흐름 Developer
data/ DB 스키마와 데이터 모델 Developer
guides/ 실무 코딩 가이드 Developer
adr/ 아키텍처 결정 기록 Engineer, future self
roadmap/ 미래 계획과 방향성 All

Documentation conventions

모든 문서는 아래 규칙을 따릅니다.

Language policy

Element Language
Filenames / directories English (kebab-case)
Markdown headers English
Body paragraphs Korean
Code blocks and comments English
Mermaid diagram labels English
Table headers English
Table cell contents Korean 허용
Front-matter values English (enum)

고유명사와 기술 용어는 영어를 그대로 사용합니다. Subscription, Webhook, Idempotency 같은 용어는 번역하지 않습니다. 용어 매핑은 overview/glossary.md 에서 관리합니다.

Front-matter

모든 문서는 YAML front-matter 로 시작합니다.

---
title: "Document Title"
status: Draft | Review | Approved | Deprecated | Superseded
owner: github-username
audience: engineer | developer | both | all
last_updated: YYYY-MM-DD
reviewers: [username1, username2]
tags: [tag1, tag2]
---

status 값 정의:

  • Draft — 작성 중, 아직 검토 받지 않음
  • Review — 작성 완료, 리뷰 대기
  • Approved — 검토 완료, 유효한 문서
  • Deprecated — 더 이상 유효하지 않음, 참고용으로만 보존
  • Superseded — 다른 문서로 대체됨, 대체 문서 링크 필수

Writing style

Google 개발자 / 엔지니어 가이드라인을 따릅니다.

  • Why-first — 각 문서는 "왜 이것이 존재하는가" 섹션으로 시작합니다. 결정의 맥락 없이 결론만 쓰지 않습니다.
  • Concise — 한 문서는 5분 내에 읽을 수 있어야 합니다. 대략 1500 ~ 2500 단어 분량입니다. 이 한도를 넘으면 주제를 쪼개야 할 신호입니다.
  • Audience-split — 같은 주제라도 독자가 다르면 문서를 분리합니다. domain/billing.md 는 엔지니어 관점의 설계, guides/api-conventions.md 는 개발자 관점의 구현 가이드입니다.
  • Reference-style — 처음부터 끝까지 순서대로 읽는 서사가 아닙니다. 필요할 때 찾아보는 레퍼런스입니다. 제목과 섹션 구조로 탐색 가능해야 합니다.

Diagrams

다이어그램은 Mermaid 를 인라인으로 사용합니다. 별도 이미지 파일로 관리하지 않습니다.

\`\`\`mermaid
stateDiagram-v2
    [*] --> Active
    Active --> Suspended: BotKicked
\`\`\`

다이어그램 노드명과 라벨은 영어로 작성합니다.

File naming

  • kebab-case 를 사용합니다. 예: billing-subscription.md
  • ADR 은 4자리 번호 prefix 를 붙입니다. 예: 0001-language-go.md
  • 한 주제가 여러 문서로 분할되면 공통 prefix 를 사용합니다. 예: recovery-snapshot.md, recovery-restore.md

Using templates

새 문서를 작성할 때는 .templates/ 에서 적절한 템플릿을 복사하여 사용합니다.

cp docs/.templates/domain.template.md docs/domain/new-domain.md

템플릿별 용도와 사용법은 .templates/README.md 를 참조하세요.

  • overview/what-is-umbra.md — 프로젝트 정체성
  • .templates/README.md — 템플릿 사용 가이드
  • adr/README.md — ADR 인덱스와 작성 가이드