ahnyongjooandClaude Sonnet 5.5
964a841de1
- Code\rebar_pipeline, review_pipeline, pier-program을 정션에서 실제 폴더로 전환 - Code\rhino_mcp 및 CLAUDE_rhino배경.md 추가, .mcp.json은 PYTHONPATH로 새 위치 사용 - pier-program 내부 .git 제거(이력은 backup\pier-program_20261028.bundle에 보관) - worktree 가이드 반영(CLAUDE.local.md, HANDOFF.md) - D:\Rhino-MCP 경로 참조를 새 위치로 치환 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
450 lines
13 KiB
Markdown
450 lines
13 KiB
Markdown
---
|
|
template: design-enterprise
|
|
version: 1.0
|
|
description: Detailed design document for Enterprise level projects
|
|
variables:
|
|
- feature: Feature name
|
|
- date: Creation date (YYYY-MM-DD)
|
|
- author: Author
|
|
- version: Document version
|
|
- reviewers: Reviewers list
|
|
level: Enterprise
|
|
---
|
|
|
|
# {feature} Detailed Design Document
|
|
|
|
> **Version**: {version}
|
|
> **Created**: {date}
|
|
> **Author**: {author}
|
|
> **Status**: Draft
|
|
> **Reviewers**: {reviewers}
|
|
> **Planning Doc**: [{feature}.plan.md](../01-plan/features/{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
|
|
|
|
```typescript
|
|
// {Entity}
|
|
interface {Entity} {
|
|
id: string;
|
|
version: number; // Optimistic locking
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
createdBy: string;
|
|
// Fields...
|
|
}
|
|
```
|
|
|
|
### 4.2 Database Schema
|
|
|
|
```sql
|
|
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)
|
|
|
|
```typescript
|
|
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)
|
|
|
|
```json
|
|
// 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
|
|
|
|
```yaml
|
|
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
|
|
3. 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} | - |
|