v0.0

온라인 대시보드 백엔드 아키텍처 설계서

1. Executive Summary

본 문서는 D'CENT 엔터프라이즈 콜드월렛 커스터디 솔루션의 온라인 대시보드 백엔드 아키텍처를 설계한다. 대시보드는 3-Zone 보안 아키텍처에서 Zone 1(Online Zone)에 해당하며, 트랜잭션 생성, 정책 엔진, 서명 취합, 블록체인 전파, 감사 로그, 사용자 관리의 중심 허브 역할을 수행한다.

설계 방향: - Event Sourcing + CQRS 패턴으로 감사 추적 요구사항 충족 - 모듈화 아키텍처로 배포 모델(Zero Cloud/Hybrid/SaaS) 대응 - 블록체인 노드 통합 레이어로 멀티체인 확장 지원 - Warm Tier MPC-TSS 서버 통합 지점 정의

---

2. 아키텍처 개요

2.1. 전체 구조 다이어그램

┌─────────────────────────────────────────────────────────────────┐
│                   Online Dashboard Backend                       │
│                                                                  │
│  ┌──────────┐      ┌──────────────────────────────────────────┐ │
│  │          │      │           Service Layer                   │ │
│  │  API     │      │                                           │ │
│  │  Gateway │─────▶│  ┌──────────┐  ┌──────────┐             │ │
│  │          │      │  │ TX       │  │ Approval │             │ │
│  │  ● Auth  │      │  │ Manager  │  │ Manager  │             │ │
│  │  ● Rate  │      │  └──────────┘  └──────────┘             │ │
│  │  ● RBAC  │      │  ┌──────────┐  ┌──────────┐             │ │
│  │  ● Log   │      │  │ Policy   │  │ Wallet   │             │ │
│  │          │      │  │ Engine   │  │ Manager  │             │ │
│  └──────────┘      │  └──────────┘  └──────────┘             │ │
│                     │  ┌──────────┐  ┌──────────┐             │ │
│                     │  │ Whitelist│  │ User     │             │ │
│                     │  │ Manager  │  │ Manager  │             │ │
│                     │  └──────────┘  └──────────┘             │ │
│                     │  ┌──────────┐  ┌──────────┐             │ │
│                     │  │ Audit    │  │ Notif.   │             │ │
│                     │  │ Logger   │  │ Service  │             │ │
│                     │  └──────────┘  └──────────┘             │ │
│                     └──────────────────────────────────────────┘ │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │                    Data Layer                                ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ││
│  │  │ Event    │  │ Read     │  │ Redis    │  │ Blob     │  ││
│  │  │ Store    │  │ DB       │  │ Cache    │  │ Storage  │  ││
│  │  │          │  │          │  │          │  │          │  ││
│  │  │ TX 이벤트│  │ 쿼리 뷰  │  │ 세션     │  │ 감사 로그│  ││
│  │  │ 정책 이벤│  │ 잔액 뷰  │  │ 정책 캐시│  │ 백업     │  ││
│  │  │ 역할 이벤│  │ 승인 뷰  │  │ 토큰 캐시│  │          │  ││
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  ││
│  └──────────────────────────────────────────────────────────────┘│
│                                                                  │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │                  Integration Layer                           ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      ││
│  │  │ Blockchain   │  │ MPC-TSS      │  │ QR/USB-C     │      ││
│  │  │ Connector    │  │ Connector    │  │ Codec        │      ││
│  │  │              │  │              │  │              │      ││
│  │  │ ● BTC Node   │  │ ● 셰어 서버  │  │ ● UR 인코딩  │      ││
│  │  │ ● ETH Node   │  │ ● DKG 관리   │  │ ● CBOR       │      ││
│  │  │ ● EVM L2     │  │ ● 서명 세션  │  │ ● QR 생성    │      ││
│  │  │ ● Mempool    │  │ ● 키 리프레시│  │              │      ││
│  │  └──────────────┘  └──────────────┘  └──────────────┘      ││
│  └──────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

2.2. 배포 모델별 구성 차이

모듈	Model A (Zero Cloud)	Model B (Hybrid)	Model C (SaaS)
API Gateway	기업 서버	클라우드 ALB/NLB	D'CENT 인프라
Service Layer	기업 서버	클라우드 컨테이너	D'CENT 관리
Event Store	온프레미스 PostgreSQL	클라우드 RDS	격리 스키마
Read DB	온프레미스 PostgreSQL	클라우드 RDS	격리 스키마
Redis	온프레미스	클라우드 ElastiCache	공유 (격리 키스페이스)
Blockchain Nodes	셀프호스팅	하이브리드	D'CENT 공유
MPC-TSS	기업 분산 서버	기업 온프레미스	기업 분산 서버

---

3. API 설계

3.1. API 엔드포인트 목록

Transactions

Method	Path	설명	권한
POST	/api/v1/transactions	TX 생성	Initiator
GET	/api/v1/transactions	TX 목록 조회	All
GET	/api/v1/transactions/:id	TX 상세 조회	All
POST	/api/v1/transactions/:id/approve	TX 승인	Approver
POST	/api/v1/transactions/:id/reject	TX 거부	Approver
POST	/api/v1/transactions/:id/sign	부분 서명 제출	Approver
GET	/api/v1/transactions/:id/qr	서명 요청 QR 생성	Approver
POST	/api/v1/transactions/:id/broadcast	TX 전파	System/Initiator
GET	/api/v1/transactions/:id/status	TX 상태 조회	All

Wallets

Method	Path	설명	권한
GET	/api/v1/wallets	월렛 목록	All
GET	/api/v1/wallets/:id	월렛 상세 + 잔액	All
GET	/api/v1/wallets/:id/utxos	UTXO 목록 (BTC)	Admin
GET	/api/v1/wallets/:id/addresses	주소 목록	Admin
POST	/api/v1/wallets/:id/rebalance	리밸런싱 요청	Admin

Policies

Method	Path	설명	권한
GET	/api/v1/policies	정책 목록	Admin
POST	/api/v1/policies	정책 생성	Admin (쿼럼)
PUT	/api/v1/policies/:id	정책 수정	Admin (쿼럼)
POST	/api/v1/policies/hw-sync	HW 정책 동기화 QR 생성	Admin
GET	/api/v1/policies/simulation	정책 변경 시뮬레이션	Admin

Whitelist

Method	Path	설명	권한
GET	/api/v1/whitelist	화이트리스트 조회	All
POST	/api/v1/whitelist	주소 추가	Admin (쿼럼)
DELETE	/api/v1/whitelist/:address	주소 삭제	Admin (쿼럼)
GET	/api/v1/whitelist/merkle	Merkle Root + Tree 조회	Admin

Audit

Method	Path	설명	권한
GET	/api/v1/audit/events	감사 이벤트 조회	Admin/Viewer
GET	/api/v1/audit/reports	컴플라이언스 보고서 생성	Admin
GET	/api/v1/audit/chain-integrity	해시 체이닝 무결성 검증	Admin

Users

Method	Path	설명	권한
GET	/api/v1/users	사용자 목록	Admin
POST	/api/v1/users	사용자 생성	Super Admin
PUT	/api/v1/users/:id/role	역할 변경	Admin (쿼럼)
POST	/api/v1/users/:id/devices	디바이스 등록	Admin
DELETE	/api/v1/users/:id/devices/:did	디바이스 해제	Admin

3.2. 인증/인가

인증 흐름:
    1. 로그인: 이메일/비밀번호 → 1차 인증
    2. MFA: TOTP (Google Authenticator 등) → 2차 인증
    3. 하드웨어 키: FIDO2/WebAuthn (선택적 3차 인증)
    4. JWT 토큰 발행 (Access: 15분, Refresh: 7일)

RBAC 미들웨어:
    Request → JWT 검증 → 역할 추출 → 권한 확인 → 허용/거부

세션 관리:
    - Redis에 세션 저장 (고가용)
    - Admin 세션: 최대 4시간 (AC-AC-06)
    - 비활동 30분 시 세션 만료
    - 동시 세션: 역할별 제한 (Admin: 1, Approver: 3)

3.3. API 버저닝

경로 기반 버저닝: /api/v1/, /api/v2/
    - v1: 현재 안정 버전
    - v2: 차기 버전 (추가 시)
    - 이전 버전: 최소 12개월 지원 후 deprecation
    - 응답 헤더: X-API-Version, X-API-Deprecated-At

---

4. 이벤트 스토어 아키텍처

4.1. Event Sourcing 적용 범위

Aggregate	이벤트 유형	설명
Transaction	tx.created, tx.approved, tx.rejected, tx.signed, tx.broadcast, tx.confirmed, tx.failed, tx.expired	TX 전체 라이프사이클
Policy	policy.created, policy.updated, policy.deleted, policy.overridden, policy.hw_synced	정책 변경 이력
Whitelist	whitelist.added, whitelist.removed, whitelist.merkle_updated	화이트리스트 변경
User	user.created, user.role_changed, user.device_added, user.deactivated	사용자 관리
Signer	signer.added, signer.removed, signer.threshold_changed, signer.backup_activated	서명자 관리

4.2. 이벤트 구조

Event {
    event_id: UUID               // 이벤트 고유 ID
    aggregate_id: UUID           // Aggregate 식별자 (TX ID, 정책 ID 등)
    aggregate_type: string       // "Transaction", "Policy", ...
    event_type: string           // "tx.created", "policy.updated", ...
    version: uint                // Aggregate 내 이벤트 순서
    payload: JSON                // 이벤트 데이터
    metadata: {
        actor_id: UUID           // 행위자 ID
        actor_role: string       // 행위자 역할
        ip_address: string       // 접근 IP
        user_agent: string
        session_id: UUID
    }
    timestamp: ISO8601           // 이벤트 발생 시각
    prev_hash: bytes(32)         // 이전 이벤트 SHA-256 해시 (체이닝)
    event_hash: bytes(32)        // 현재 이벤트 해시 (무결성)
}

4.3. SHA-256 해시 체이닝 (AC-AU-01)

이벤트 해시 체이닝:
    event_hash_N = SHA-256(
        event_id_N ||
        aggregate_id_N ||
        event_type_N ||
        payload_N ||
        timestamp_N ||
        event_hash_(N-1)         // 이전 이벤트 해시
    )

무결성 검증:
    1. 최초 이벤트부터 순차적으로 해시 재계산
    2. 저장된 해시와 비교
    3. 불일치 시 → 변조 감지 알림

4.4. CQRS 패턴

Command Side (쓰기):
    API Request → Command Handler → Event 생성 → Event Store 저장
                                                    │
                                                    ▼
                                              Event Publisher
                                                    │
Query Side (읽기):                                  │
    API Request → Query Handler → Read DB 조회      │
                                     ▲              │
                                     │              │
                              Projection Handler ◀──┘
                              (Event → Read Model 변환)

Read Model 예시: - transaction_view: TX 상태, 승인 현황, 서명 현황 - balance_view: 월렛별/체인별 잔액 (실시간 업데이트) - approval_view: 대기 중 승인 목록 (승인자별) - audit_view: 감사 이벤트 검색/필터 뷰

4.5. 이벤트 보존 정책

항목	정책
보존 기간	최소 5년 (AC-AU-03, ISMS-P 6.2, 특금법)
삭제	불가 (append-only)
아카이빙	1년 초과 이벤트 → Cold Storage 이동 (S3/NAS)
백업	일일 풀 백업 + 시간별 증분 백업
무결성	월 1회 해시 체이닝 전체 검증

---

5. 블록체인 노드 통합

5.1. 노드 풀 관리

ChainNodePool {
    nodes: [{
        chain: string
        url: string
        type: "primary" | "fallback"
        health: "healthy" | "degraded" | "down"
        latency_ms: uint
        last_checked: timestamp
    }]

    // 헬스체크 (30초 간격)
    healthCheck(): void

    // 노드 선택 (Primary → Fallback 자동 전환)
    getNode(chain: string): NodeConnection

    // Failover
    onNodeDown(node): void  // 자동으로 다음 노드로 전환
}

체인별 최소 노드 구성:

체인	Primary	Fallback	합계	프로토콜
Bitcoin	1	2	3	JSON-RPC (bitcoind)
Ethereum	1	2	3	JSON-RPC (geth/erigon)
EVM L2 (각)	1	1	2	JSON-RPC

5.2. 셀프호스팅 vs 외부 서비스

항목	셀프호스팅	외부 (Alchemy/Infura)
데이터 주권	완전	제한 (3자 의존)
가용성	자체 관리	SLA 보장 (99.9%)
비용	서버 비용 (고정)	API 호출 비용 (변동)
적합 모델	Model A (Zero Cloud)	Model B/C
권장	Model A 필수	Model B/C 허용

5.3. UTXO 관리 (Bitcoin)

UTXOManager {
    // UTXO 세트 추적
    syncUTXOs(wallet: Wallet): void
    getUTXOSet(wallet: Wallet): [UTXO]

    // Coin Selection
    selectCoins(amount: BigInt, strategy: UTXOStrategy): [UTXO]

    // UTXO 락 (다중 TX 동시 생성 시 이중 사용 방지)
    lockUTXOs(utxos: [UTXO], txId: UUID, ttl: uint): void
    unlockUTXOs(txId: UUID): void
}

5.4. 잔액 동기화

실시간 잔액 업데이트:
    1. 블록 모니터링: 새 블록 → 관련 주소 확인 → 잔액 업데이트
    2. 멤풀 모니터링: 미확인 TX 감지 → pending 잔액 반영
    3. 폴링 주기: BTC 60초 / EVM 15초 (블록 시간 기반)
    4. WebSocket: 가용 시 실시간 구독 (eth_subscribe)

---

6. Warm Tier MPC-TSS 통합

6.1. MPC-TSS 백엔드 통합 지점

MPCTSSConnector {
    // 키 생성 (DKG)
    initDKG(t: uint, n: uint, participants: [ServerId]): DKGSession
    completeDKG(session: DKGSession): PublicKey

    // 서명 세션
    initSign(message: bytes, signers: [ServerId]): SignSession
    collectPartialSigs(session: SignSession): Signature

    // 키 리프레시
    initKeyRefresh(participants: [ServerId]): RefreshSession
    completeRefresh(session: RefreshSession): void

    // 셰어 서버 관리
    getServerStatus(serverId: ServerId): ServerStatus
    addServer(config: ServerConfig): void
    removeServer(serverId: ServerId, newT: uint): void
}

6.2. Warm Tier 자동 리밸런싱 엔진

RebalanceEngine {
    // 잔액 모니터링
    checkBalance(tier: "warm"): BalanceStatus

    // 리밸런싱 판단
    evaluateRebalance(): RebalanceAction?
        // Warm < 하한선(3%) → 충전 요청 (Cold → Warm, 에어갭 필요)
        // Warm > 상한선(15%) → 자동 환수 (Warm → Cold, MPC-TSS 서명)

    // 자동 환수 실행
    executeAutoSweep(amount: BigInt): TxHash

    // 충전 요청 생성
    createRefillRequest(amount: BigInt): Transaction
        // Cold Tier 출금이므로 에어갭 다중 서명 필요

    // Kill Switch
    emergencySweep(): void
        // Warm 전체 잔액 → 사전 지정 Cold 주소
        // 모든 Warm 서명 즉시 중단
}

---

7. 비기능 요구사항

7.1. 가용성

항목	요구사항
가용성 목표	99.9% (연간 다운타임 < 8.76시간)
구성	Active-Standby (Model A) / Active-Active (Model B/C)
DB Failover	PostgreSQL Streaming Replication + 자동 Failover
API 무중단	Rolling Deploy (Blue-Green 또는 Canary)

7.2. 확장성

항목	방향
API 서버	Stateless → 수평 확장 (로드밸런서 뒤)
Event Store	PostgreSQL 파티셔닝 (월별)
Read DB	Read Replica 추가로 쿼리 부하 분산
블록체인 노드	체인별 독립 노드 풀

7.3. 백업/복구

항목	전략
DB 백업	일일 풀 백업 (PostgreSQL pg_dump) + WAL 아카이빙
Event Store 복구	WAL 리플레이로 특정 시점 복구 (PITR)
설정 백업	정책/화이트리스트 설정 일일 스냅샷
복구 목표	RPO < 1시간, RTO < 4시간

---

8. 기술 스택 권장사항

특정 기술을 강제하지 않되, 엔터프라이즈 보안 요구사항에 적합한 방향을 제시한다.

영역	권장	근거
데이터베이스	PostgreSQL 15+	ACID 보장, 감사 로그 무결성, JSONB (이벤트 페이로드), 파티셔닝
캐시	Redis 7+	세션 관리, 정책 캐시, UTXO 락 (TTL 지원)
이벤트 스토어	PostgreSQL + Outbox 패턴	EventStoreDB 대안 가능. PostgreSQL 단일 DB로 운영 단순화
API 런타임	Go / Rust / Node.js(TypeScript)	Go: 성능+동시성. Rust: 최고 보안. Node: 빠른 개발
메시지 큐	Redis Streams / RabbitMQ	이벤트 발행, 알림, 비동기 처리
모니터링	Prometheus + Grafana	메트릭 수집, 대시보드, 알림
로깅	구조화 로그 (JSON) + ELK/Loki	감사 로그 검색, 보안 이벤트 분석
컨테이너	Docker + Kubernetes (Model B/C)	배포 자동화, 스케일링

---

본 문서는 Phase 5 System Architecture Design의 일부로, Phase 3 정책 엔진(policy-engine.md), 감사 추적(audit-trail.md), RBAC(rbac-role-model.md)의 1차 계층 구현 아키텍처를 설계한다. Phase 4 on-premise-zero-cloud.md의 3가지 배포 모델에 대응하는 모듈화 구조를 정의한다. Phase 4 mpc-tss-warm-wallet.md의 Warm Tier 통합 지점을 백엔드 수준에서 명세한다.

---

관련 문서

• 에어갭 통신 프로토콜 설계서 -- 시스템 아키텍처
• 체인 추상화 레이어 인터페이스 정의서 -- 시스템 아키텍처
• 컴포넌트 간 데이터 흐름 및 인터페이스 명세 -- 시스템 아키텍처
• D'CENT X 펌웨어 서명 인터페이스 설계서 -- 시스템 아키텍처
• 오프라인 서명 앱 아키텍처 설계서 -- 시스템 아키텍처
• STRIDE 기반 보안 위협 모델 -- 시스템 아키텍처
• 3-Zone 보안 아키텍처 설계서 -- 시스템 아키텍처