본문으로 건너뛰기

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 인증 제공자 연동​

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

5.3.2 외부 서비스 연동​

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

6. 보안 아키텍처​

6.1 인증 및 권한​

  • OAuth 2.0: 표준 기반 인증 (Eid는 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최초 작성