Glossary¶

Umbra 프로젝트에서 사용하는 모든 고유 용어와 약어를 정의합니다. 용어가 헷갈릴 때 가장 먼저 참조하는 문서입니다.

How to use this document¶

• 문서 본문에서 용어를 처음 소개할 때는 정의를 짧게 덧붙이고 이 용어 사전으로 링크합니다.
• 새 용어가 도입될 때는 반드시 이 문서에 추가합니다. 코드에서만 쓰이는 용어도 문서에 노출되면 추가 대상입니다.
• 용어는 영어를 기준으로 하며, 한국어 대응어가 있으면 병기합니다.
• 용어는 알파벳 순으로 정렬합니다.

Domain terms¶

비즈니스 도메인 용어입니다.

Anti-Nuke¶

길드의 비정상적 이벤트(대량 삭제, 권한 급변 등)를 감지하여 자동으로 스냅샷을 생성하고 대응하는 능동적 보호 시스템. Recovery 도메인의 sub-context.

Audit Log¶

길드 내 관리 이벤트의 기록. 두 종류가 있습니다.

• Discord Audit Log — Discord 가 제공하는 길드 이벤트 기록. Anti-Nuke 가 가해자 식별에 사용.
• Umbra Audit Log — Umbra 시스템 내부의 도메인 이벤트 기록. 결제 변경, 권한 변경, 복구 작업 등을 추적.

Billing Key (빌링키)¶

Toss Payments 가 발급하는 정기결제 토큰. 카드 정보 대신 저장하며, 이것으로 Toss API 를 호출하면 등록된 카드로 결제가 이루어집니다. User 에 귀속됩니다.

Bot (봇)¶

이 프로젝트의 Discord Gateway 프로세스. apps/bot/ 에 구현되며 disgo 라이브러리로 Discord 와 통신합니다.

Bounded Context¶

DDD 에서 도메인 모델이 일관된 의미를 갖는 경계. Umbra 에서는 Go 패키지 경계와 1:1 매핑됩니다.

Component V2¶

Discord 가 2025년 3월 도입한 메시지 컴포넌트 시스템. Container, Section, Text Display, Media Gallery, Separator 등 레이아웃 컴포넌트를 지원합니다. IS_COMPONENTS_V2 플래그로 활성화합니다.

Customer Key¶

Toss Payments 에서 고객을 식별하는 키. Umbra 는 user_{uuid} 형태로 생성합니다. User 에 1:1 매핑.

Feature¶

License 로 접근이 통제되는 기능 단위. 예: RECOVERY_RESTORE, ANTINUKE_AUTO_KICK. Plan 이 Feature 의 집합을 정의합니다.

Grace Period¶

결제 실패 후 서비스 혜택이 유지되는 유예 기간. Umbra 는 1차 실패 후 24시간의 Grace Period 를 부여합니다.

Guild (길드)¶

Discord 에서 "서버" 라고 부르는 단위의 공식 명칭. Umbra 의 구독 적용 대상이자 복구 대상의 기본 단위.

Hybrid Model¶

Umbra 의 멀티테넌시 모델. 결제는 User, 권한 적용은 Guild 로 분리된 구조. 한 User 가 여러 길드의 구독을 독립적으로 관리할 수 있습니다.

Idempotency¶

같은 요청이 여러 번 처리되어도 결과가 동일한 성질. Toss 웹훅, Outbox 이벤트 핸들러, Temporal Activity 에서 필수로 강제됩니다.

License¶

특정 길드에 부여된 권한. Plan 을 참조하며 active / suspended / canceled 상태를 가집니다. Licensing 도메인의 주 entity.

Live Sync¶

Discord 길드의 변경 이벤트를 실시간으로 우리 DB 에 미러링하는 메커니즘. Recovery 도메인의 sub-context 이며 asynq 배치로 구현됩니다.

Manage Server Permission¶

Discord 권한 중 하나(MANAGE_GUILD). Umbra 구독을 시작하려면 이 권한이 필요합니다.

Member (멤버)¶

길드에 속한 Discord 사용자. Umbra 의 Member 도메인은 Discord 사용자와 Guild 의 관계를 관리합니다.

Order ID¶

Toss Payments 에서 결제 건을 식별하는 키. Umbra 는 sub_{subscription_id}_{cycle}_r{retry} 형태로 생성합니다.

Outbox Pattern¶

도메인 이벤트를 DB 트랜잭션 안에 outbox 테이블로 기록한 뒤, 별도 polling worker 가 이를 구독자에게 전달하는 패턴. 트랜잭션 일관성과 at-least-once 전달을 보장합니다.

Payer¶

구독의 결제 주체. Subscription 이 생성될 때 Guild 의 Manage Server 권한자여야 합니다.

Plan¶

License 가 부여하는 권한의 정의. Umbra 는 Free / Pro / Enterprise 3개 Plan 을 가집니다.

Port / Adapter¶

Hexagonal Architecture 의 핵심 개념. Port 는 도메인이 외부와 통신하는 인터페이스, Adapter 는 Port 의 실제 구현입니다.

• Inbound Port (driving) — 외부가 도메인을 호출하는 인터페이스. 예: SubscriptionService.
• Outbound Port (driven) — 도메인이 외부에 요구하는 인터페이스. 예: SubscriptionRepository, TossClient.

Restore¶

스냅샷을 기준으로 길드 상태를 되돌리는 작업. Temporal 워크플로우로 실행됩니다.

Restore Mode¶

복구 시 기존 데이터 처리 방식.

• Sync (default) — Git reset 스타일. 스냅샷에 없는 요소 삭제, 있는 요소 생성/업데이트.

Restore Point¶

복구의 기준점이 되는 스냅샷. 사용자가 명시적으로 생성하거나 스케줄로 자동 생성됩니다.

Snapshot¶

특정 시점의 길드 상태 전체를 저장한 기록. PostgreSQL JSONB 컬럼으로 저장됩니다.

Subscription¶

특정 User 가 특정 Guild 를 대상으로 진행 중인 결제 관계. License 와 분리된 엔티티로, 서로 다른 lifecycle 을 가집니다. Billing 도메인의 주 entity.

User (사용자)¶

Umbra 의 사용자 계정. Discord 사용자와 1:1 매핑되며, BillingKey 를 소유하고 여러 Subscription 의 Payer 가 될 수 있습니다.

Web Join¶

join.umbra.ink/{slug} 를 통해 멤버가 OAuth2 로 길드에 가입하는 흐름. Member 도메인의 sub-feature.

Technical terms¶

기술 스택 및 인프라 용어입니다.

Activity (Temporal)¶

Temporal Workflow 에서 외부 시스템과 통신하는 단위. 비결정적 작업(IO, 랜덤, 시간)은 모두 Activity 로 격리됩니다.

asynq¶

Redis 기반 Go 작업 큐 라이브러리. Umbra 는 짧은 비동기 작업(결제 cron, Live Sync 배치, 알림 발송)에 사용합니다.

Atlas¶

선언형 DB schema 관리 도구. Umbra 는 db/schema/ 에 정의된 스키마를 source of truth 로 삼고 Atlas 가 마이그레이션을 자동 생성합니다.

disgo¶

Go 의 Discord 봇 라이브러리. Components V2 를 정식 지원하며 Umbra 의 Bot 프로세스에 사용됩니다.

Echo¶

Go 의 HTTP 웹 프레임워크. Umbra 의 API 프로세스에 사용됩니다.

Hexagonal Architecture (Ports & Adapters)¶

도메인 코어를 외부 의존성에서 격리하는 아키텍처 패턴. Umbra 는 Core 컨텍스트(Recovery, Licensing, Billing)에 풀세트로 적용하고 Supporting 컨텍스트는 단순 구조로 실용적 적용합니다.

Neon¶

Serverless PostgreSQL 호스팅 서비스. Branching 기능과 pooler endpoint 를 제공합니다.

pgx¶

Go 의 PostgreSQL 드라이버. pgxpool 은 pgx 의 커넥션 풀.

sqlc¶

SQL 쿼리에서 타입 안전한 Go 코드를 생성하는 도구. Umbra 는 도메인별로 sqlc 패키지를 분리합니다.

Temporal¶

분산 워크플로우 엔진. Umbra 는 Recovery 도메인(Restore, AntiNuke)에만 사용하며 나머지 비동기 작업은 asynq 로 처리합니다.

Toss Payments¶

한국의 결제 서비스. Umbra 는 Toss Billing(정기결제) API 를 사용합니다.

TOSS Billing Key¶

Billing Key 와 동일. Toss 에서 공식적으로 쓰이는 표기.

ULID / UUID v7¶

시간 정렬 가능한 식별자. Umbra 는 UUID v7 (RFC 9562) 을 채택합니다. ULID 는 채택하지 않습니다.

Process names¶

Fly.io 에 배포되는 프로세스 단위입니다.

umbra-api¶

HTTP API 를 제공하는 Echo 프로세스. 인증, 대시보드 API, 웹훅 수신을 담당합니다.

umbra-bot¶

Discord Gateway 에 연결된 disgo 프로세스. 슬래시 커맨드 처리, Discord 이벤트 수신을 담당합니다.

umbra-worker¶

백그라운드 작업 프로세스. asynq 워커, Temporal 워커, Outbox poller 를 고루틴으로 함께 실행합니다.

Abbreviations¶

Related docs¶

• overview/what-is-umbra.md — 프로젝트 정체성
• overview/value-proposition.md — 핵심 가치 제안
• docs/README.md — 전체 문서 네비게이션