Pier_v1/.hmcmkit/knowledge/templates/design-enterprise.template.md

template, version, description, variables, level

template	version	description	variables	level
design-enterprise	1.0	Detailed design document for Enterprise level projects	feature Feature name date Creation date (YYYY-MM-DD) author Author version Document version reviewers Reviewers list	Enterprise

{feature} Detailed Design Document

Version: {version} Created: {date} Author: {author} Status: Draft Reviewers: {reviewers} Planning Doc: {feature}.plan.md

---

1. Executive Summary

1.1 Purpose

{High-level purpose of this feature}

1.2 Scope

{What is included and excluded from this design}

1.3 Goals

• {Goal 1}
• {Goal 2}
• {Goal 3}

---

2. Non-Functional Requirements

2.1 Performance

Metric	Target	Rationale
Response time (P95)	< 200ms	User experience
Throughput	> 1000 RPS	Peak load
Database query time	< 50ms	Backend performance

2.2 Scalability

• Horizontal scaling capability
• Expected growth: {X}% per month
• Auto-scaling thresholds

2.3 Availability

• Target SLA: 99.9%
• Recovery Time Objective (RTO): < 1 hour
• Recovery Point Objective (RPO): < 5 minutes

---

3. System Architecture

3.1 High-Level Architecture

┌──────────────────────────────────────────────────────────────┐
│                     Load Balancer (ALB)                       │
└──────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Service A     │ │   Service B     │ │   Service C     │
│   (API)         │ │   (Worker)      │ │   (Gateway)     │
└─────────────────┘ └─────────────────┘ └─────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
┌──────────────────────────────────────────────────────────────┐
│                    Data Layer                                 │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │PostgreSQL│  │  Redis  │  │   S3    │  │ ElasticSearch│   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘         │
└──────────────────────────────────────────────────────────────┘

3.2 Microservices Structure

Service	Responsibility	Stack	Replicas
{service-a}	{role}	{tech}	3
{service-b}	{role}	{tech}	2

3.3 Clean Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│                 (Controllers, DTOs, Mappers)                 │
├─────────────────────────────────────────────────────────────┤
│                    Application Layer                         │
│               (Use Cases, Services, Handlers)                │
├─────────────────────────────────────────────────────────────┤
│                      Domain Layer                            │
│            (Entities, Value Objects, Interfaces)             │
├─────────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                       │
│        (Repositories, External APIs, Database)               │
└─────────────────────────────────────────────────────────────┘

3.4 Inter-Service Communication

From	To	Protocol	Pattern
API Gateway	Service A	gRPC	Request/Response
Service A	Service B	Message Queue	Event-driven

---

4. Data Model

4.1 Entity Definitions

// {Entity}
interface {Entity} {
  id: string;
  version: number;          // Optimistic locking
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
  // Fields...
}

4.2 Database Schema

CREATE TABLE {table} (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  version INTEGER NOT NULL DEFAULT 1,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  created_by UUID REFERENCES users(id),
  -- Fields...
);

CREATE INDEX idx_{table}_created_at ON {table}(created_at);

4.3 Event Schema (Event-driven)

interface {Feature}Event {
  eventId: string;
  eventType: '{feature}.created' | '{feature}.updated';
  timestamp: string;
  payload: {
    // Event data
  };
}

---

5. API Specification

5.1 Endpoint List

Method	Path	Description	Rate Limit
GET	/api/v1/{resource}	List	100/min
POST	/api/v1/{resource}	Create	10/min
PUT	/api/v1/{resource}/:id	Update	30/min
DELETE	/api/v1/{resource}/:id	Delete	5/min

5.2 Response Format (Standard)

// Success
{
  "data": { ... },
  "meta": {
    "requestId": "req_xxx",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User-friendly message",
    "details": [ ... ]
  }
}

// Pagination
{
  "data": [ ... ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

---

6. Infrastructure

6.1 Kubernetes Resources

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {service}
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: {service}
          resources:
            requests:
              cpu: "100m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

6.2 Environment Variables

Variable	Description	Scope
DB_HOST	Database host	Server
REDIS_URL	Redis connection	Server
NEXT_PUBLIC_API_URL	API base URL	Client

---

7. Security

7.1 Authentication & Authorization

• Authentication: JWT with refresh tokens
• Authorization: RBAC with permissions
• Token expiry: Access 15min, Refresh 7days

7.2 Security Checklist

• Input validation (all endpoints)
• SQL injection prevention (parameterized queries)
• XSS prevention (output encoding)
• CSRF protection (tokens)
• Rate limiting (per endpoint)
• Audit logging (sensitive operations)
• Secrets management (no hardcoded secrets)

---

8. Monitoring & Observability

8.1 Monitoring Stack

Component	Tool	Role
Error Tracking	Sentry	Error grouping, regression detection, session replay
Metrics	Prometheus	Counter/Gauge/Histogram, 15s scrape interval
Dashboards	Grafana	Unified view (Prometheus + Loki + Tempo + Sentry)
Logs	Loki + Promtail	JSON structured log aggregation, 30d retention
Tracing	Tempo + OpenTelemetry	Distributed tracing, 10% sampling (prod)
Alerting	Alertmanager	Route: Critical→PagerDuty, Warning→Slack

8.2 Metrics & SLOs

Metric	Type	SLO/Threshold	Alert
request_latency_seconds	Histogram	P95 < 200ms, P99 < 500ms	Warning > 500ms, Critical > 1s
error_rate	Counter	< 0.1% (SLO 99.9%)	Warning > 1%, Critical > 5%
cpu_usage	Gauge	< 70% (HPA target)	Warning > 80%, Critical > 95%
memory_usage	Gauge	< 80% (HPA target)	Warning > 85%, Critical > 95%
sentry_unresolved_issues	Gauge	< 5 critical	Warning > 5, Critical > 10

8.3 Logging

• Format: JSON structured
• Required fields: timestamp, level, service, request_id, trace_id, user_id, message
• Retention: 30 days
• Error logs: Sentry SDK가 자동 캡처 (breadcrumbs 포함)

8.4 Error Tracking (Sentry)

Frontend (Next.js):
- @sentry/nextjs SDK
- Error Boundary 자동 연동
- Session Replay (에러 시 100%)
- Performance Monitoring (10% sampling)

Backend (FastAPI):
- sentry-sdk[fastapi]
- ASGI middleware 자동 캡처
- SQLAlchemy integration (slow query 추적)
- Custom context: user_id, request_id, service_name

8.5 Alerts & Escalation

Alert	Condition	Severity	Action
High Error Rate	> 5% for 5min	Critical	PagerDuty page + Auto-Rollback
High Latency	P95 > 1s for 10min	Warning	Slack #error-alerts
Sentry New Issue	New unhandled exception	Warning	Self-Healing Agent trigger
Sentry Regression	Resolved issue re-opened	Critical	Self-Healing + PagerDuty
Sentry Spike	Error frequency > 10x baseline	Critical	Auto-Rollback + PagerDuty

---

9. Error Handling & Self-Healing Pipeline

9.1 Error Flow

Exception 발생
  ↓
Sentry SDK 자동 캡처 (breadcrumbs + user + release)
  ↓
Sentry Alert Rule (new/regression/spike)
  ↓
Self-Healing Agent (Living Context 4-Layer)
  ↓
Auto-fix (max 5 iter) → 4중 검증 → Auto PR
  ↓
Canary Deploy (10%→25%→50%→100%)
  ↓
Post-deploy 검증 (Sentry issue resolved? error_rate 정상?)
  ↓
실패 시 → Auto-Rollback + Incident Memory 기록

9.2 Circuit Breaker

State	Condition	Action
CLOSED	failures < 3	Normal operation
OPEN	failures >= 3	Block all transitions, 30s cooldown
HALF_OPEN	cooldown expired	1 trial attempt → success=CLOSED, fail=OPEN

---

10. Deployment

10.1 Load Balancer

Internet → CloudFront (CDN + WAF) → ALB → NGINX Ingress Controller → Services
                                                ↑
                                     CORS 처리 (annotation)
                                     Path-based routing
                                     TLS termination (ACM)

• ALB + NGINX Ingress (기본): L7, CORS annotation, path routing, WAF 연동
• NLB (특수): L4, gRPC/WebSocket 전용, CORS는 앱단 처리

10.2 CI/CD Pipeline

PR → Lint/Test(≥80%) → Security Scan(Semgrep+Trivy) → Build → Push ECR
  → Deploy Staging(ArgoCD) → E2E Test → Approval Gate → Canary Deploy Prod

10.3 Canary Strategy (Argo Rollouts)

10% traffic (2min) → metric check → 25% (2min) → 50% (5min) → 100%
                      ↓ fail
                   Auto-Rollback + Sentry alert

10.4 Rollback Strategy

1. Auto-Rollback: Canary metrics fail (error_rate > 1% or P95 > 200ms)
2. Self-Healing Rollback: 5회 fix 실패 시 자동 롤백
3. Manual Rollback: ArgoCD UI one-click revert
4. Database migration rollback scripts ready

---

10. Test Plan

10.1 Test Pyramid

Type	Coverage Target	Tools
Unit	> 80%	Jest
Integration	Key paths	Supertest
E2E	Critical flows	Playwright
Load	Performance	k6

10.2 Key Test Scenarios

• Happy path: {description}
• Error handling: {description}
• Edge cases: {description}
• Concurrency: {description}
• Failover: {description}

---

11. Implementation Plan

11.1 Phases

Phase	Scope	Duration
1	Core infrastructure	2 days
2	API implementation	3 days
3	UI integration	2 days
4	Testing & QA	2 days

11.2 Success Criteria

• All endpoints implemented
• Test coverage > 80%
• Zero Script QA passed
• Security scan passed
• Performance benchmarks met
• Documentation complete

---

Document History

Version	Date	Changes	Author	Reviewer
0.1	{date}	Initial draft	{author}	-