영어 기술 문서 작성 완전 가이드: RFC·ADR·Design Doc 패턴과 실전 표현

1. Title / RFC Number
2. Status: Draft | In Review | Accepted | Rejected | Superseded
3. Author(s)
4. Date
5. Summary / Abstract
6. Motivation / Problem Statement
7. Detailed Proposal
8. Alternatives Considered
9. Risks and Mitigations
10. Open Questions
11. References

# RFC-042: Migrate to Event-Driven Architecture for Order Processing

**Status:** In Review
**Author:** Jane Kim
**Date:** 2026-03-10
**Reviewers:** Backend Team, Platform Team

## Summary

This RFC proposes migrating the order processing pipeline from a synchronous
REST-based architecture to an event-driven architecture using Apache Kafka.
The goal is to improve system resilience and reduce coupling between services.

## Motivation

The current synchronous order processing pipeline has the following limitations:

- **Single point of failure**: If the payment service is down, the entire
  order flow is blocked.
- **Tight coupling**: Adding a new step (e.g., fraud detection) requires
  modifying multiple services.
- **Scalability bottleneck**: Peak traffic (Black Friday) causes cascading
  timeouts across services.

## Detailed Proposal

We propose introducing Kafka as the central message broker with the following
topology:

- Order Service publishes `OrderCreated` events
- Payment Service subscribes to `OrderCreated` and publishes `PaymentProcessed`
- Inventory Service subscribes to `PaymentProcessed`
- Notification Service subscribes to all terminal events

### Migration Strategy

Phase 1: Dual-write (weeks 1-4) - Both sync and async paths active
Phase 2: Shadow mode (weeks 5-8) - Async primary, sync for validation
Phase 3: Cutover (weeks 9-10) - Async only, sync deprecated

## Alternatives Considered

### Alternative A: gRPC with Circuit Breaker

- Pro: Lower latency for happy path
- Con: Does not address fundamental coupling issue

### Alternative B: AWS Step Functions

- Pro: Managed service, less operational overhead
- Con: Vendor lock-in, limited throughput at scale

## Risks and Mitigations

| Risk                     | Likelihood | Impact | Mitigation                     |
| ------------------------ | ---------- | ------ | ------------------------------ |
| Message ordering issues  | Medium     | High   | Partition key by order ID      |
| Consumer lag during peak | Low        | Medium | Auto-scaling consumer groups   |
| Data consistency         | Medium     | High   | Saga pattern with compensation |

## Open Questions

1. Should we use Kafka Connect for database CDC, or custom producers?
2. What is the acceptable end-to-end latency for order confirmation?

## References

- Internal: Design Doc for Kafka Cluster Setup (link)
- External: "Designing Event-Driven Systems" by Ben Stopford

"This RFC proposes [동사ing]..."
(이 RFC는 ...을 제안합니다.)

"The goal of this proposal is to [동사]..."
(이 제안의 목표는 ...하는 것입니다.)

"We are seeking feedback on [명사/동명사]..."
(우리는 ...에 대한 피드백을 구하고 있습니다.)

"The current approach has the following limitations..."
(현재 방식에는 다음과 같은 한계가 있습니다...)

"This change is motivated by..."
(이 변경은 ...에 의해 동기 부여됩니다.)

"We have observed that..."
(우리는 ...을 관찰했습니다.)

"We considered [N] alternatives before arriving at this proposal."
(이 제안에 도달하기 전에 N개의 대안을 검토했습니다.)

"While [Alternative A] addresses [problem], it falls short in [area]."
([대안 A]가 [문제]를 해결하지만, [영역]에서는 부족합니다.)

"The primary trade-off of this approach is..."
(이 접근 방식의 주요 트레이드오프는...)

# ADR-017: Use PostgreSQL as the Primary Database

## Status

Accepted (2026-03-10)

## Context

We are building a new order management system that requires:

- ACID transactions for financial data integrity
- Complex queries with JOIN operations across multiple tables
- JSON support for flexible product metadata
- Strong ecosystem of ORMs and tooling

The team has experience with both PostgreSQL and MySQL. We also evaluated
NoSQL options (MongoDB, DynamoDB) for their scalability characteristics.

## Decision

We will use PostgreSQL 16 as the primary database for the order management
system.

Key factors in this decision:

- Native JSONB support eliminates the need for a separate document store
- Row-level security aligns with our multi-tenant architecture
- pg_partitioning handles our anticipated data growth (100M+ rows/year)
- The team has 3 engineers with deep PostgreSQL expertise

## Consequences

### Positive

- Unified data layer reduces operational complexity
- Strong consistency guarantees simplify application logic
- Rich extension ecosystem (PostGIS, pg_trgm) enables future features

### Negative

- Horizontal scaling requires careful planning (read replicas, partitioning)
- Higher memory requirements compared to MySQL for equivalent workloads
- Team must invest in PostgreSQL-specific performance tuning knowledge

# Use React Server Components for the Dashboard

## Context and Problem Statement

The dashboard currently uses client-side rendering (CSR) with React SPA.
Initial load times exceed 4 seconds on mobile devices, and SEO is not
possible for public-facing dashboard pages. We need to decide on a rendering
strategy that improves performance while maintaining interactivity.

## Decision Drivers

- Page load time must be under 2 seconds on 3G networks
- SEO required for public dashboard pages
- Developer experience should not significantly degrade
- Must be compatible with our existing component library

## Considered Options

1. React Server Components (RSC) with Next.js App Router
2. Static Site Generation (SSG) with Incremental Static Regeneration
3. Server-Side Rendering (SSR) with streaming

## Decision Outcome

Chosen option: "React Server Components with Next.js App Router" because
it provides the best balance of performance, SEO, and developer experience.

### Positive Consequences

- 60-70% reduction in client-side JavaScript bundle
- Automatic code splitting at the component level
- Server-side data fetching eliminates client-side waterfalls

### Negative Consequences

- Learning curve for the team (estimated 2-week ramp-up)
- Some third-party libraries are not yet RSC-compatible
- Debugging server/client boundary issues can be challenging

"In the context of [situation], facing [concern]..."
([상황]의 맥락에서, [우려 사항]에 직면하여...)

"We decided for [option] and against [other options]..."
(우리는 [옵션]을 선택하고 [다른 옵션들]을 배제하기로 결정했습니다...)

"We accept that [consequence] because [rationale]."
(우리는 [결과]를 수용합니다. 왜냐하면 [근거]이기 때문입니다.)

"This decision was driven by [factor]."
(이 결정은 [요인]에 의해 주도되었습니다.)

"The decision is [accepted/deprecated/superseded by ADR-XXX]."
(이 결정은 [수락됨/폐기됨/ADR-XXX로 대체됨]입니다.)

1. Title and Metadata (authors, reviewers, status, last updated)
2. Overview / TL;DR (1 paragraph summary)
3. Context / Background
4. Goals and Non-Goals
5. Detailed Design
   - System Architecture
   - API Design
   - Data Model
   - Error Handling
6. Alternatives Considered
7. Cross-Cutting Concerns (security, privacy, monitoring)
8. Migration / Rollout Plan
9. Open Questions
10. Appendix

# Design Doc: Real-Time Notification Service

**Authors:** Jane Kim, Alex Park
**Reviewers:** Backend Lead, SRE Team, Security Team
**Status:** In Review
**Last Updated:** 2026-03-10

## Overview

This document describes the design for a real-time notification service
that delivers push notifications, in-app messages, and email digests to
users. The service will handle up to 10 million notifications per day
with a p99 delivery latency of under 500ms for push notifications.

## Context

Currently, notifications are sent inline within each microservice. This
leads to duplicated notification logic across 12 services, inconsistent
delivery behavior, and no centralized tracking of notification state.
User complaints about duplicate or missing notifications have increased
by 40% in Q4 2025.

## Goals

- Provide a unified notification API for all backend services
- Support push, in-app, and email channels with extensible architecture
- Achieve p99 delivery latency under 500ms for push notifications
- Enable user-level notification preferences and quiet hours

## Non-Goals

- Real-time chat or messaging features (separate project)
- SMS notifications (planned for Phase 2, not in this scope)
- Notification content personalization using ML (future enhancement)

## Detailed Design

### System Architecture

The notification service consists of four main components:

- **Ingestion Layer**: gRPC API that accepts notification requests,
  validates payloads, and publishes to Kafka
- **Router**: Consumes events, resolves user preferences, and routes
  to the appropriate channel handler
- **Channel Handlers**: Dedicated workers for push (FCM/APNs),
  in-app (WebSocket), and email (SendGrid)
- **State Store**: PostgreSQL for notification metadata and delivery
  status tracking

### API Design

The primary endpoint accepts notification requests:

POST /v1/notifications

Required fields: recipient_id, channel, template_id, parameters
Optional fields: priority, scheduled_at, idempotency_key

Response: notification_id, status (queued/delivered/failed)

### Data Model

Notifications table stores the core notification data:

- id (UUID, primary key)
- recipient_id (UUID, indexed)
- channel (enum: push, in_app, email)
- template_id (string)
- status (enum: queued, processing, delivered, failed)
- created_at, delivered_at (timestamps)

### Error Handling

- Transient failures: Exponential backoff with jitter, max 3 retries
- Permanent failures: Dead letter queue with alerting
- Duplicate prevention: Idempotency key with 24-hour TTL in Redis

## Alternatives Considered

### Alternative 1: Use a managed service (AWS SNS + SES)

- Pro: No operational overhead, built-in scalability
- Con: Limited customization for in-app notifications, cost at scale
  (estimated 3x our infrastructure cost at 10M notifications/day)
- Decision: Rejected due to cost and limited in-app support

### Alternative 2: Extend existing per-service notification logic

- Pro: No new infrastructure, incremental improvement
- Con: Does not address the root cause of duplication and inconsistency
- Decision: Rejected as it perpetuates technical debt

## Cross-Cutting Concerns

### Security

- All notification payloads encrypted at rest (AES-256)
- PII fields (email, device tokens) stored in a separate encrypted store
- API authentication via service-to-service mTLS

### Monitoring

- Dashboard: delivery rate, latency percentiles, failure rate by channel
- Alerts: delivery rate drops below 99%, p99 latency exceeds 1s

## Rollout Plan

- Week 1-2: Deploy service in staging, integration tests
- Week 3: Shadow mode (dual-write to old and new system)
- Week 4: Canary rollout to 5% of traffic
- Week 5-6: Gradual ramp to 100%, deprecate old notification code

## Open Questions

1. Should we support batch notification API for marketing campaigns?
2. How do we handle notification delivery when user is offline for
   extended periods (> 7 days)?

# 좋은 Non-Goals 예시
"SMS notifications (planned for Phase 2, not in this scope)"
"Real-time chat or messaging features (separate project)"
"Notification content personalization using ML (future enhancement)"

# 나쁜 Non-Goals 예시 (너무 당연한 것)
"The system should not crash" (당연한 요구사항)
"We will not rewrite the entire codebase" (비현실적 대안)

"We believe this approach will scale to 10M requests/day,
 but this needs to be validated through load testing."
(이 접근 방식이 1천만 요청/일까지 확장될 것으로 예상하지만,
 부하 테스트를 통해 검증이 필요합니다.)

"The estimated latency improvement is 30-50%, pending benchmarks."
(예상 지연시간 개선은 30~50%이며, 벤치마크 결과에 따라 달라질 수 있습니다.)

"This is our current best understanding; we will revisit after
 the proof of concept."
(이것은 현재 시점의 최선의 이해이며, PoC 이후 재검토할 예정입니다.)

# 제안형 (부드러운 톤)
"Consider extracting this into a helper function for reusability."
(재사용성을 위해 이 부분을 헬퍼 함수로 추출하는 것을 고려해 보세요.)

# 질문형 (이해를 구하는 톤)
"What is the rationale for using a map here instead of a slice?"
(여기서 slice 대신 map을 사용한 근거가 무엇인가요?)

# 블로킹 이슈 (반드시 수정 필요)
"This must be addressed before merging: the error is silently swallowed,
 which could mask production issues."
(머지 전에 반드시 수정해야 합니다: 에러가 조용히 무시되어 프로덕션 이슈를
 숨길 수 있습니다.)

# 칭찬 (좋은 코드에 대한 인정)
"Nice approach! Using the builder pattern here makes the API much more
 readable."
(좋은 접근입니다! 여기서 빌더 패턴을 사용한 것이 API 가독성을 크게 높입니다.)

# NIT (사소하지만 개선 가능)
"nit: This variable name could be more descriptive. Maybe
 'userNotificationPreferences' instead of 'prefs'?"
(nit: 변수명이 좀 더 설명적이면 좋겠습니다. 'prefs' 대신
 'userNotificationPreferences'는 어떨까요?)

# Bad
"We should use Kafka for message processing."

# Good
"The current synchronous pipeline fails under peak load, causing
cascading timeouts. We propose using Kafka to decouple services
and improve resilience."

# Bad
"We considered MongoDB but decided not to use it."

# Good
"We considered MongoDB for its flexible schema support. However,
our workload is primarily relational with complex JOIN queries across
5+ tables. MongoDB would require application-level joins, increasing
code complexity and latency. Therefore, PostgreSQL better fits our
query patterns."

# Bad (수동태 과다)
"It was decided that the service would be migrated."

# Good (능동태)
"We decided to migrate the service to the new cluster."

# Bad
"The system should be fast and handle lots of requests."

# Good
"The system must achieve a p99 latency of under 200ms and sustain
50,000 requests per second during peak hours."

# Non-Goals 섹션 작성 예시
"Non-Goals:
- This design does not cover the migration of historical data.
  That will be addressed in a separate design doc.
- Real-time analytics on notification delivery is out of scope
  for this phase."

# RFC: Adopt Structured Logging Across All Services

**Author:** Alex Park | **Date:** 2026-03-10 | **Status:** Draft

## Problem

Our current logging is inconsistent: some services use plain text,
others use JSON. This makes log aggregation and alerting unreliable.
On average, engineers spend 2 hours per incident parsing logs manually.

## Proposal

Adopt structured JSON logging with a standardized schema across all
services. Use the following mandatory fields:

- timestamp (ISO 8601)
- level (DEBUG, INFO, WARN, ERROR)
- service_name
- trace_id
- message

## Impact

- Estimated 40% reduction in mean-time-to-detect (MTTD)
- Enables automated anomaly detection via log pattern analysis
- Requires updating 23 services (estimated 2 sprints)

## Decision Requested

Please review and comment by 2026-03-24. If no blocking concerns
are raised, we will proceed with implementation.

# ADR-023: Switch from REST to gRPC for Internal Service Communication

## Status

Superseded by ADR-031 (2026-02-15)

## Context

In 2025, internal service-to-service calls used REST with JSON payloads.
As the number of microservices grew from 8 to 35, serialization overhead
and lack of type safety became significant pain points.

## Decision

We adopted gRPC with Protocol Buffers for all new internal service
communication. Existing REST endpoints were maintained for external
API consumers.

## Consequences

- 30% reduction in inter-service latency due to binary serialization
- Strongly typed contracts reduced integration bugs by 25%
- Increased complexity in debugging (binary payloads not human-readable)
- Required investment in gRPC tooling and team training

## Superseded By

ADR-031 introduced gRPC-Web for browser clients, extending this
decision to cover frontend-to-backend communication as well.

## Migration Plan

### Phase 1: Foundation (Weeks 1-3)

- Deploy the new notification service to staging environment
- Set up monitoring dashboards and alerting rules
- Complete integration tests with all upstream services

### Phase 2: Shadow Mode (Weeks 4-6)

- Enable dual-write: existing system + new service
- Compare delivery rates and latency between old and new systems
- Acceptance criteria: new system delivers 99.9%+ of notifications
  within p99 latency target

### Phase 3: Gradual Rollout (Weeks 7-10)

- Week 7: Route 5% of traffic to new service (canary)
- Week 8: Increase to 25% if metrics are healthy
- Week 9: Increase to 75%
- Week 10: 100% cutover, begin decommissioning old code

### Rollback Plan

- Feature flag to instantly revert to the old notification path
- Data reconciliation job to sync any missed notifications
- Rollback decision criteria: error rate exceeds 1% or p99 latency
  exceeds 2 seconds for more than 5 minutes