ARCHITECTURE.md

BeMore Backend Architecture - Ultrathink Engineering

🧠 Ultrathink Engineering 철학 적용

설계 원칙

1. 첫 원리 사고: "왜 이 방식인가?"를 반복 질문하며 근본적 재구성
2. 3가지 대안 비교: 모든 구조는 최소 3가지 설계 대안을 비교 분석
3. AI cognitive expansion: 깊은 설계 검증과 충돌 실험을 통한 최적화
4. 심층적 아키텍처: 단순 구현이 아닌 확장 가능한 구조 지향

---

🏗️ 아키텍처 개요

선택된 아키텍처: Domain-Driven Design (DDD) + Clean Architecture

선택 이유:

• 감정 분석 도메인의 복잡성: VAD, CBT, AI 상담 등 복잡한 비즈니스 로직
• 확장성 요구사항: 새로운 AI 모델, 분석 방식 추가 용이
• 테스트 주도 개발: 도메인 로직과 인프라 분리로 테스트 용이
• 미래 마이크로서비스 전환: 서비스 분리 시 독립적 배포 가능

---

📐 레이어 구조

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   User      │ │  Emotion    │ │    Chat     │           │
│  │ Controller  │ │ Controller  │ │ Controller  │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   User      │ │  Emotion    │ │    Chat     │           │
│  │   Service   │ │   Service   │ │   Service   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                     Domain Layer                            │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   User      │ │  Emotion    │ │    Chat     │           │
│  │   Domain    │ │   Domain    │ │   Domain    │           │
│  │   Service   │ │   Service   │ │   Service   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  Infrastructure Layer                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   Prisma    │ │   External  │ │   File      │           │
│  │ Repository  │ │    APIs     │ │   Storage   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────────────────────────────────────────────┘

---

🔄 의존성 방향

Dependency Inversion Principle 적용

• 고수준 모듈 (Domain, Application)은 저수준 모듈 (Infrastructure)에 의존하지 않음
• 인터페이스를 통한 의존성 역전
• 의존성 주입을 통한 런타임 결합

// 인터페이스 정의
interface IUserRepository {
  create(data: CreateUserData): Promise<User>;
  findByEmail(email: string): Promise<User | null>;
}

// 구현체
class PrismaUserRepository implements IUserRepository {
  // Prisma 구현
}

// 도메인 서비스
class UserDomainService {
  constructor(private userRepository: IUserRepository) {}
}

---

📦 모듈 구조

1. Common Module

src/common/
├── dto/                    # Data Transfer Objects
├── guards/                 # Authentication Guards
├── strategies/             # JWT Strategy
├── services/               # Shared Services (Prisma)
├── interfaces/             # Repository & Service Interfaces
└── constants/              # Provider Tokens

2. Domain Module

src/domain/
└── services/               # Domain Business Logic
    ├── user-domain.service.ts
    ├── emotion-analysis-domain.service.ts
    ├── chat-domain.service.ts
    └── history-domain.service.ts

3. Infrastructure Module

src/infrastructure/
└── repositories/           # Data Access Layer
    ├── prisma-user.repository.ts
    ├── prisma-emotion-analysis.repository.ts
    └── prisma-chat.repository.ts

4. Feature Modules

src/
├── user/                   # User Management
├── emotion/                # Emotion Analysis
├── chat/                   # AI Chat
└── history/                # Session History

---

🔧 핵심 컴포넌트

Repository Pattern

• 인터페이스: IUserRepository, IEmotionAnalysisRepository, IChatRepository
• 구현체: PrismaUserRepository, PrismaEmotionAnalysisRepository, PrismaChatRepository
• 목적: 데이터 접근 로직 캡슐화, 테스트 용이성

Domain Services

• UserDomainService: 사용자 생성, 인증, 프로필 관리
• EmotionAnalysisDomainService: 감정 분석, CBT 피드백 생성
• ChatDomainService: Gemini AI 대화, 메시지 관리
• HistoryDomainService: 세션 저장, 히스토리 조회

External Service Integration

• Python Analysis Server: TensorFlow, Whisper 기반 감정 분석
• Google Gemini API: AI 대화 서비스
• File Storage: 이미지, 오디오, PDF 저장

---

🧪 테스트 전략

테스트 피라미드

        ┌─────────────┐
        │   E2E       │  (10%)
        └─────────────┘
    ┌─────────────────────┐
    │   Integration      │  (20%)
    └─────────────────────┘
┌─────────────────────────────┐
│         Unit               │  (70%)
└─────────────────────────────┘

테스트 구조

test/
├── unit/                     # 도메인 로직 단위 테스트
├── integration/              # Repository 통합 테스트
└── e2e/                      # API 엔드포인트 테스트

---

🚀 확장성 고려사항

마이크로서비스 전환 준비

• 서비스 경계: User, Emotion, Chat, History 독립적 분리 가능
• API Gateway: 통합 엔드포인트 관리
• Event-Driven: 서비스 간 비동기 통신

성능 최적화

• Caching: Redis 기반 세션, 분석 결과 캐싱
• Database: 읽기/쓰기 분리, 인덱스 최적화
• Async Processing: 대용량 파일 처리, PDF 생성

---

🔒 보안 아키텍처

인증 & 인가

• JWT: Stateless 인증, 토큰 기반 권한 관리
• Rate Limiting: API 호출 제한
• Input Validation: DTO 기반 입력 검증

데이터 보호

• Encryption: 민감 데이터 암호화
• GDPR Compliance: 개인정보 보호법 준수
• Audit Logging: 사용자 활동 추적

---

📊 모니터링 & 로깅

Observability

• Structured Logging: JSON 형태 로그
• Metrics: 성능 지표 수집
• Tracing: 분산 추적 (OpenTelemetry)

Health Checks

• Database: 연결 상태 확인
• External APIs: Gemini, Python 서버 상태
• File Storage: 저장소 접근성 확인

---

🔄 배포 아키텍처

CI/CD Pipeline

Code → Test → Build → Deploy → Monitor

Environment Strategy

• Development: 로컬 개발 환경
• Staging: 통합 테스트 환경
• Production: 운영 환경

---

📈 성능 지표

KPI (Key Performance Indicators)

• Response Time: API 응답 시간 < 500ms
• Throughput: 초당 요청 처리량
• Error Rate: 에러율 < 1%
• Availability: 가용성 > 99.9%

---

🎯 결론

Ultrathink Engineering 철학을 적용한 BeMore 백엔드는:

1. 확장 가능한 구조: DDD + Clean Architecture
2. 테스트 용이성: 인터페이스 기반 의존성 분리
3. 유지보수성: 명확한 레이어 분리
4. 성능 최적화: 캐싱, 비동기 처리 준비
5. 보안 강화: JWT, 입력 검증, 암호화

이 구조는 현재 요구사항을 충족하면서도 미래의 확장과 마이크로서비스 전환을 고려한 심층적 설계입니다.