본문으로 건너뛰기

Software Architecture Document (SAD)

SleepQ 디지털 치료기기의 소프트웨어 아키텍처 문서입니다.

1. 시스템 개요

1.1 시스템 목적

SleepQ는 불면증 치료를 위한 디지털 치료기기로, 인지행동치료 기반의 개입을 제공합니다.

1.2 시스템 범위

  • 모바일 애플리케이션: iOS/Android 환경에서 동작하는 환자용 앱
  • 백엔드 시스템: 클라우드 기반 서비스 및 데이터 관리
  • 의료진 대시보드: 웹 기반 모니터링 및 관리 도구

1.3 규제 분류

  • 의료기기 분류: SaMD Class I (미국 FDA), Class IIa (EU MDR), 2등급 (한국 K-FDA)
  • 소프트웨어 안전 분류: Class A (IEC 62304 - 비안전 관련)

2. 아키텍처 원칙

2.1 설계 원칙 (Class A 적용)

2.1.1 보안 및 개인정보 보호

  • 데이터 보호 (Data Protection): 환자 개인정보 암호화 및 접근 제어
  • 최소 권한 원칙 (Principle of Least Privilege): 필요한 최소한의 권한만 부여
  • 데이터 무결성 (Data Integrity): 치료 데이터의 정확성과 일관성 보장
  • 감사 추적 (Audit Trail): 모든 중요 작업에 대한 로그 기록

2.1.2 시스템 설계 원칙

  • 단순성 (Simplicity): 복잡성 최소화로 오류 가능성 감소
  • 모듈화 (Modularity): 기능별 독립적 모듈 설계
  • 느슨한 결합 (Loose Coupling): 서비스 간 의존성 최소화
  • 높은 응집도 (High Cohesion): 관련 기능들의 논리적 그룹화

2.1.3 사용자 경험 및 접근성

  • 사용성 우선 (Usability First): 직관적이고 접근하기 쉬운 인터페이스
  • 접근성 (Accessibility): 다양한 사용자 요구 사항 고려
  • 일관성 (Consistency): 플랫폼 간 일관된 사용자 경험
  • 반응성 (Responsiveness): 빠른 응답 시간과 피드백

2.1.4 운영 및 확장성

  • 확장성 (Scalability): 사용자 증가에 대응 가능한 구조
  • 가용성 (Availability): 시스템 다운타임 최소화
  • 관찰 가능성 (Observability): 시스템 상태 모니터링 및 추적
  • 복구 가능성 (Recoverability): 장애 시 빠른 복구 능력

2.1.5 표준 준수 및 호환성

  • 상호운용성 (Interoperability): 표준 기반 데이터 교환 (HL7 FHIR)
  • 표준 준수 (Standards Compliance): 의료기기 및 보안 표준 준수
  • 플랫폼 독립성 (Platform Independence): 다양한 환경에서 동작 가능
  • 하위 호환성 (Backward Compatibility): 기존 데이터 및 API 호환성 유지

2.2 제약사항 (Class A 수준)

  • 기본 규제 준수: 개인정보보호 법규 기본 준수
  • 성능 목표: 일반적인 모바일 앱 수준의 성능
  • Class A 특성: 안전 위험이 없어 엄격한 제약사항 완화

3. 아키텍처 특성과 안전성 설계 연계

3.1 IEC 62304 Class A 안전성 목표와 아키텍처 매핑

본 시스템은 IEC 62304 Class A 소프트웨어로 분류되어 "환자나 운영자에게 부상이나 건강 손상을 야기할 가능성이 없는" 디지털 치료기기입니다. 아키텍처 설계는 다음과 같이 안전성 목표와 연계됩니다:

3.1.1 가용성 (Availability) ↔ 서비스 연속성 보장

아키텍처 특성안전성 연계구현 방법관련된 안전 요구사항(SRS-ID)
무상태 설계서비스 중단 최소화Cloud Run 인스턴스 자동 확장/축소PLT-NFR-001
PLT-NFR-002
로드 밸런싱단일 장애점 제거Global Load Balancer 다중 리전 분산PLT-NFR-003
관리형 서비스인프라 안정성 향상Google Cloud 99.95% SLA 보장PLT-NFR-004

3.1.2 관찰 가능성 (Observability) ↔ 시스템 상태 투명성

아키텍처 특성안전성 연계구현 방법관련된 안전 요구사항(SRS-ID)
메트릭 수집성능 저하 조기 감지Prometheus/OTel MetricsPLT-NFR-008
중앙 로깅시스템 추적성 확보Cloud Logging → BigQueryPLT-NFR-009
분산 추적요청 흐름 가시성OpenTelemetry + Correlation IDPLT-NFR-010

3.1.3 데이터 무결성 (Data Integrity) ↔ 정보 정확성 보장

아키텍처 특성안전성 연계구현 방법관련된 안전 요구사항(SRS-ID)
트랜잭션 관리데이터 일관성 보장PostgreSQL ACID 속성 활용PLT-NFR-011
백업 전략데이터 손실 방지자동 백업 + Point-in-time 복구PLT-NFR-006
PLT-NFR-005
검증 계층데이터 품질 보장DTO 유효성 검증 + 비즈니스 규칙SLP-CR-014
SLP-CR-015
SLP-CR-016
SLP-CR-017
AUT-FR-BE-012
QST-FR-BE-028
QST-FR-BE-029
QST-FR-BE-030
QST-FR-BE-031

3.1.4 확장성 (Scalability) ↔ 성능 저하 방지

아키텍처 특성안전성 연계구현 방법관련된 안전 요구사항(SRS-ID)
수평 확장부하 분산으로 안정성 향상Cloud Run 자동 스케일링PLT-NFR-001
PLT-NFR-002
캐싱 전략응답 속도 보장Redis 인메모리 캐시PLT-NFR-013
비동기 처리메시지 유실 방지 및 순서 보존Cloud Pub/Sub + DLQ + 멱등성 키PLT-NFR-012

3.2 안전성 메커니즘의 아키텍처 구현

3.2.1 오류 격리 (Error Isolation)

사용자 요청 → Global Load Balancer → 서비스별 독립 처리 → 격리된 장애 영향
  • 마이크로서비스 경계: 한 서비스 장애가 전체 시스템에 전파되지 않음
  • Circuit Breaker 패턴: 장애 서비스 자동 차단
  • Graceful Degradation: 부분 기능 장애 시 핵심 기능 유지

3.2.2 데이터 보호 (Data Protection)

암호화된 전송 → 인증/권한 검증 → 암호화된 저장 → 감사 로그
  • 종단간 암호화: TLS 1.2+ (전송) + AES-256 (저장)
  • 접근 제어: OAuth 2.0 + RBAC
  • 감사 추적: 모든 데이터 접근 기록

3.2.3 복구 메커니즘 (Recovery Mechanisms)

장애 감지 → 자동 복구 → 수동 개입 → 완전 복구 검증
  • Health Check: 서비스 상태 실시간 모니터링
  • Auto Healing: 비정상 인스턴스 자동 교체
  • Disaster Recovery: 다중 리전 백업 전략

3.3 위험 완화 전략과 아키텍처 패턴

3.3.1 성능 위험 완화

위험완화 전략아키텍처 패턴관련된 안전 요구사항(SRS-ID)
응답 지연캐싱 + CDNCache-Aside 패턴PLT-NFR-001
PLT-NFR-003
동시 접속 부하로드 밸런싱Load Balancer + Auto ScalingPLT-NFR-003
데이터베이스 병목가용성/확장성 향상Read Replica 패턴PLT-NFR-004
PLT-NFR-001

3.3.2 보안 위험 완화

위험완화 전략아키텍처 패턴관련된 안전 요구사항(SRS-ID)
무단 접근다단계 인증Global Load Balancer + JWTAUT-FR-BE-008
AUT-FR-BE-018
데이터 유출최소 권한 원칙Zero Trust ArchitectureIAM-FR-BE-062
IAM-NFR-004
주입 공격입력 검증Input Validation LayerIAM-NFR-009

3.3.3 운영 위험 완화

위험완화 전략아키텍처 패턴관련된 안전 요구사항(SRS-ID)
배포 실패점진적 배포Blue-Green DeploymentPLT-NFR-007
설정 오류재현가능성/안정성Configuration as CodePLT-CR-001
의존성 장애장애 전이 차단Bulkhead 패턴PLT-NFR-004

3.4 품질 속성과 안전성 연계 측정

3.4.1 정량적 안전성 지표

품질 속성목표 값측정 방법안전성 연계관련된 안전 요구사항(SRS-ID)
가용성99.9%Uptime 모니터링서비스 중단 방지PLT-NFR-004
응답시간< 500msAPI 응답 시간 측정사용자 경험 안전성PLT-NFR-001
PLT-NFR-003
데이터 정확성99.99%데이터 무결성 검사치료 정보 신뢰성IAM-NFR-006
SLP-CR-004
SLP-CR-005
QST-CR-012
복구시간< 1시간MTTR 측정서비스 복구 신속성PLT-NFR-005

3.4.2 정성적 안전성 평가

  • 사용자 인터페이스 직관성: 오작동 위험 최소화
  • 오류 메시지 명확성: 사용자 혼란 방지
  • 데이터 일관성: 치료 연속성 보장
  • 시스템 예측 가능성: 예상치 못한 동작 방지

3.5 구체적 설계 항목과 안전성 연계

3.5.1 사용자 인증 및 액세스 제어 설계

설계 항목구현 방법안전성 연계관련된 안전 요구사항(SRS-ID)
Access Code 인증 설계일회성 액세스 코드 + 이메일 검증 시스템무단 접근 방지ACC-FR-BE-019
ACC-FR-BE-021
ACC-FR-BE-022
다단계 인증 체계OAuth 2.0 + JWT + PIN 코드사용자 신원 확인 강화AUT-FR-BE-004
AUT-FR-BE-007
AUT-FR-BE-008
AUT-FR-BE-013
AUT-FR-BE-018
AUT-FR-BE-019
권한 기반 접근 제어RBAC 기반 세분화된 권한 관리최소 권한 원칙 적용IAM-FR-BE-023
IAM-FR-BE-031
IAM-FR-BE-038
IAM-FR-BE-062
IAM-FR-BE-069
IAM-NFR-002

3.5.2 데이터 처리 및 계산 로직 설계

설계 항목구현 방법안전성 연계관련된 안전 요구사항(SRS-ID)
RTIB 계산 로직실시간 수면 지표 계산 알고리즘정확한 치료 데이터 제공SLP-FR-BE-028
SLP-FR-BE-029
SLP-FR-BE-030
SLP-CR-001
SLP-CR-006
SLP-CR-029
데이터 검증 계층입력 데이터 유효성 검사 및 범위 확인잘못된 데이터 입력 방지SLP-CR-014
SLP-CR-015
SLP-CR-016
SLP-CR-017
AUT-FR-BE-012
QST-FR-BE-028
QST-FR-BE-029
QST-FR-BE-030
QST-FR-BE-031
계산 결과 검증다중 검증 로직을 통한 결과 신뢰성 확보치료 결과의 정확성 보장SLP-CR-004
SLP-CR-005
SLP-CR-006

3.5.3 사용자 경험 및 프로세스 안전성 설계

설계 항목구현 방법안전성 연계관련된 안전 요구사항(SRS-ID)
초기 설문 응답 누락 방지필수 단계 체크 + 진행률 표시 + 알림 시스템치료 시작 전 필수 정보 수집QST-FR-BE-011
QST-FR-BE-013
QST-FR-BE-019
QST-FR-BE-020
QST-FR-BE-021
강제 업데이트 대응 설계버전 호환성 체크 + 단계적 업데이트 유도시스템 안정성 유지MOB-FR-BE-001
사용자 이탈 방지 메커니즘자동 저장 + 세션 복구 + 진행상황 안내치료 연속성 보장QST-FR-BE-013
QST-FR-BE-020
AUT-FR-BE-020
AUT-FR-BE-023

3.5.4 데이터 저장 및 관리 설계

설계 항목구현 방법안전성 연계관련된 안전 요구사항(SRS-ID)
데이터 저장 구조계층화된 데이터베이스 설계 (PostgreSQL + Firestore)데이터 무결성 및 가용성 확보PLT-NFR-004
PLT-NFR-006
PLT-CR-001
PLT-CR-002
백업 및 복구 체계자동 백업 + 실시간 복제 + Point-in-time 복구데이터 손실 방지PLT-NFR-006
PLT-NFR-005
감사 로그 관리모든 데이터 변경 추적 + BigQuery 분석투명성 및 추적성 확보AUD-FR-019
AUD-FR-020
AUD-NFR-012

3.5.5 시스템 안정성 및 오류 처리 설계

설계 항목구현 방법안전성 연계관련된 안전 요구사항(SRS-ID)
오류 처리 및 복구Graceful Degradation + Circuit Breaker 패턴부분 장애 시 핵심 기능 유지PLT-NFR-004
실시간 모니터링Prometheus + Cloud Monitoring + 알람문제 조기 감지 및 대응PLT-NFR-008
자동 복구 메커니즘Health Check + Auto Healing + Load Balancing시스템 자가 치유 능력PLT-NFR-004

4. 시스템 아키텍처

4.1 시스템 아키텍처 구조

SleepQ 시스템은 Google Cloud 기반의 서버리스 마이크로 서비스 구조로 설계되었으며, 사용자 프론트엔드(iOS/Android 앱)와 의료진 웹 대시보드, 클라우드 API, 데이터 계층이 연동되는 구조입니다.

아키텍처 특징

  • 서버리스 컴퓨팅: Google Cloud Functions, Cloud Run 활용
  • 마이크로서비스 패턴: 기능별 독립적 서비스 분리
  • 이벤트 기반 통신: Pub/Sub을 통한 비동기 메시징
  • 관리형 데이터베이스: Cloud SQL, Firestore 활용

3.2 시스템 아키텍처 다이어그램

3.3 주요 구성 요소 (Google Cloud 기반)

3.3.1 사용자 계층 (User Layer)

  • iOS 앱: Swift Native 기반 네이티브 앱
  • Android 앱: Kotlin Native 기반 네이티브 앱
  • 의료진 웹 대시보드: Next.js 기반 웹 애플리케이션

3.3.2 로드 밸런싱 계층 (Load Balancing Layer)

  • Global Load Balancer: HTTPS Proxy 기반 글로벌 로드 밸런싱 및 트래픽 분산
  • Certificate Manager: Google 관리형 SSL 인증서 자동 갱신
  • VPC Firewall Rules: 네트워크 수준 보안 규칙 및 접근 제어

3.3.3 서버리스 마이크로서비스 계층 (Serverless Microservices)

  • 메인 API 서비스 (dta-wide-api): NestJS 기반 통합 API, 모든 도메인 로직 처리
  • MCP 서버 (dta-wide-mcp): Model Context Protocol 서버, AI 에이전트 통신

3.3.4 데이터 계층 (Data Layer)

  • Cloud SQL (PostgreSQL): 사용자 정보, 치료 데이터, 트랜잭션 데이터
  • Firestore: NoSQL 문서 데이터베이스, 반구조화된 데이터 저장
  • Cloud Storage: 미디어 파일, 백업 파일, 정적 리소스
  • Memorystore (Redis): 세션 캐시, 임시 데이터, 성능 최적화
  • BigQuery: 데이터 웨어하우스, Audit Log, Event Log, 분석 데이터 저장

3.3.5 이벤트 및 모니터링 계층

  • Cloud Pub/Sub: 서비스 간 비동기 메시징 및 이벤트 처리
  • Cloud Scheduler: 작업 스케줄링 및 배치 처리
  • Prometheus + Cloud Monitoring: Prometheus 메트릭 형식 수집, Google Cloud 기반 모니터링 및 알람
  • Cloud Logging: 중앙집중식 로그 수집 및 분석

3.3.6 인프라 지원 계층 (Infrastructure Support)

  • VPC Network: 격리된 가상 네트워크 환경
  • Secret Manager: API 키, 인증서 등 민감 정보 암호화 저장
  • Artifact Registry: Docker 컨테이너 이미지 저장 및 관리

3.3.7 외부 연동 서비스

  • Firebase Cloud Messaging: 모바일 푸시 알림
  • SendGrid: 이메일 전송 서비스 (알림, 보고서, 계정 관리)

3.4 아키텍처 연동 흐름

3.4.1 연동 흐름 다이어그램

3.4.2 상세 연동 흐름

  1. 사용자 요청: iOS/Android 앱 또는 웹 대시보드에서 HTTPS API 요청
  2. 로드 밸런싱: Global Load Balancer가 글로벌 트래픽 분산 및 SSL 종료
  3. 보안 검증: VPC Firewall Rules에서 네트워크 수준 보안 검증
  4. 서비스 라우팅: Load Balancer에서 URL 패턴에 따라 메인 API 서비스 또는 MCP 서버로 라우팅
  5. 서비스 처리: 메인 API 서비스에서 비즈니스 로직 처리 (대부분의 요청)
  6. 데이터 액세스: 필요에 따라 Cloud SQL (관계형), Firestore (NoSQL), Redis Cache 접근
  7. 이벤트 발행: 필요시 Cloud Pub/Sub으로 비동기 이벤트 발행
  8. 스케줄링: Cloud Scheduler를 통한 정기 작업 실행
  9. 로그 저장: Audit Log, Event Log를 BigQuery에 저장 (Cloud Logging 경유)
  10. 푸시 알림: 필요시 Firebase Cloud Messaging을 통한 모바일 알림
  11. 이메일 전송: 필요시 SendGrid를 통한 이메일 알림 및 보고서 전송
  12. 응답 반환: 처리 결과를 클라이언트로 반환

5. 소프트웨어 구성요소 간 인터페이스

SleepQ 시스템은 안전성 등급 A에 해당하는 소프트웨어 의료기기이므로, 모듈 간 인터페이스 문서화가 의무사항은 아니나, 설계 품질관리를 위해 주요 항목의 인터페이스에 대해서는 문서화를 진행한다.

5.1 클라이언트 ↔ 백엔드 API

5.1.1 통신 아키텍처

  • 프로토콜: RESTful API over HTTPS (TLS 1.2+)
  • 인증 방식: OAuth 2.0 + JWT 토큰 기반 인증
  • 데이터 형식: JSON (요청/응답)
  • API 버전 관리: URL 경로 기반 버전 관리
  • 에러 처리: 표준 HTTP 상태 코드 + 구조화된 에러 응답

5.1.2 주요 도메인 인터페이스

프레젠테이션 계층비즈니스 계층데이터 계층
Mobile Apps
- iOS/Android

Web Dashboard
Auth Domain
User Domain
Sleep Domain
Questionnaire
Learning Domain
Relaxation Domain
IAM Domain
Agent Domains
Cloud SQL
Firestore
Redis Cache
BigQuery

5.1.3 인터페이스 안전성 원칙

  • 인증 보안: 모든 API 요청에 JWT 토큰 검증 필수
  • 데이터 검증: 클라이언트/서버 양쪽에서 입력 데이터 유효성 검증
  • 에러 안전: 민감 정보 노출 방지 및 적절한 에러 메시지 제공
  • 속도 제한: API 남용 방지를 위한 Rate Limiting 적용
  • 추적성: 모든 API 호출에 대한 감사 로그 기록

5.2 서비스 간 통신

5.2.1 동기 통신

  • 내부 API: 서비스 간 HTTP/REST 통신
  • 로드 밸런싱: Global Load Balancer를 통한 트래픽 분산
  • 서비스 디스커버리: DNS 기반 서비스 발견

5.2.2 비동기 통신

  • 이벤트 스트리밍: Google Cloud Pub/Sub
  • 메시지 보장: At-least-once 전달 보장
  • 이벤트 순서: 도메인별 이벤트 순서 보장

5.3 외부 시스템 연동

5.3.1 인증 제공자 연동

  • GesundheitsID: OpenID Connect 프로토콜
  • 소셜 로그인: OAuth 2.0 표준 프로토콜

5.3.2 외부 서비스 연동

  • Firebase Cloud Messaging: 푸시 알림 전송
  • SendGrid: 이메일 전송 서비스
  • Google Analytics: 사용자 행동 분석 (匿名화)

6. 보안 아키텍처

6.1 인증 및 권한

  • OAuth 2.0: 표준 기반 인증 (GesundheitsID는 OpenID Connect 지원)
  • JWT 토큰: 상태 비저장 세션 관리
  • RBAC: 역할 기반 접근 제어

6.2 데이터 암호화

  • 전송 중 암호화: TLS 1.2 이상
  • 저장 중 암호화: AES-256
  • 키 관리: Google Cloud Secret Manager

6.3 감사 및 로깅

  • 접근 로그: 모든 API 호출 기록
  • 변경 로그: 데이터 수정 추적
  • 보안 이벤트: 의심스러운 활동 모니터링

7. 데이터 흐름

7.1 일반적인 데이터 흐름

데이터 흐름 단계:

  1. 사용자 -> 모바일 앱 -> Global Load Balancer
  2. Global Load Balancer -> 메인 API 서비스
  3. 메인 API 서비스 -> 인증 및 권한 검증 (JWT 토큰)
  4. 메인 API 서비스 -> 데이터베이스 (Cloud SQL, Firestore, Redis)
  5. 응답 역순으로 전달

7.2 실시간 데이터 처리

  • 이벤트 스트리밍: Google Cloud Pub/Sub
  • 실시간 분석: 수면 패턴 실시간 모니터링
  • 알림 트리거: 조건 기반 자동 알림

8. 배포 아키텍처

8.1 클라우드 인프라

  • 컨테이너화: Docker + CloudRun
  • CI/CD: GitHub Actions
  • 모니터링: Prometheus + Google Cloud Monitoring

8.2 환경 분리

  • 개발 환경: 개발자 테스트용
  • 스테이징 환경: 통합 테스트 및 QA
  • 프로덕션 환경: 실제 서비스 운영

9. 성능 및 확장성

9.1 성능 목표

  • 응답 시간: API 호출 < 500ms
  • 처리량: 초당 1000 요청 처리
  • 동시 사용자: 10,000명 지원

9.2 확장성 전략

  • 수평 확장: 마이크로서비스별 독립 확장
  • 데이터베이스 샤딩: 사용자 ID 기반 분산
  • CDN 활용: 정적 콘텐츠 전 세계 배포

10. 재해 복구 및 백업

10.1 백업 전략

  • 데이터베이스: 일일 전체 백업, 실시간 증분 백업
  • 파일 스토리지: 지역 간 복제
  • 설정 관리: Infrastructure as Code

10.2 재해 복구

  • RTO (Recovery Time Objective): 4시간
  • RPO (Recovery Point Objective): 1시간
  • 다중 가용 영역: 자동 장애 조치

11. 규제 준수 매핑

11.1 IEC 62304 Class A 준수

  • 소프트웨어 개발 계획: 간소화된 개발 프로세스 정의
  • 소프트웨어 요구사항 분석: 기본적인 기능 요구사항 명세
  • 위험 관리: 기본 위험 분석 (소프트웨어 자체의 안전 위험 없음)
  • 형상 관리: 기본적인 버전 제어 및 변경 관리

11.2 사이버보안 준수 (Class A 수준)

  • IEC 81001-5-1: 기본 네트워크 보안 요구사항
  • 기본 보안 제어: 데이터 암호화, 접근 제어, 감사 로그
  • 개인정보보호: GDPR, HIPAA, 개인정보보호법 기본 준수

12. 검증 및 확인 (V&V) - Class A 적용

12.1 간소화된 아키텍처 검증

  • 아키텍처 리뷰: 기본적인 설계 검토
  • 기능 테스트: 주요 기능 동작 확인
  • 기본 보안 검증: 필수 보안 기능 확인

12.2 Class A 추적성 요구사항

  • 기본 요구사항 추적: 주요 기능 요구사항 연결성
  • 간소화된 테스트 추적: 핵심 기능 테스트 커버리지
  • 변경 기록: 주요 아키텍처 변경 이력 관리

12.3 Class A 프로세스 특징

Class A 소프트웨어는 환자나 다른 사람에게 직접적인 해를 끼칠 가능성이 없어:

  • 간소화된 문서화: 최소한의 필수 문서만 작성
  • 유연한 개발 프로세스: 엄격한 수명주기 프로세스 불필요
  • 선택적 표준 적용: 핵심 안전 요구사항에만 집중

변경 이력

버전날짜작성자변경 내용
0.1.02025-08-07bok@weltcorp.com최초 작성