# ZELLYY Core 아키텍처

## 시스템 구조

```
+---------------------+
|     Frontend Apps   |
| +-------+ +-------+ |
| |적자탈출| |  구독  | |
| |가계부  | |매니저  | |
| +-------+ +-------+ |
+----------+----------+
           |
+----------v----------+
|   ZELLYY Core API   |
|                     |
| - 사용자 인증/관리   |
| - SSO 서비스        |
| - 공통 데이터 관리   |
+----------+----------+
           |
+----------v----------+
|     Supabase        |
| +-------+ +-------+ |
| |  Auth | |Database| |
| +-------+ +-------+ |
+---------------------+
```

## 데이터 모델

### 사용자 (Users)
- id: UUID (Supabase Auth와 연동)
- email: String
- name: String
- created_at: Timestamp
- last_login: Timestamp
- services: Array<String> (사용 중인 서비스 목록)
- auth_provider: String (google, apple, email 등 인증 제공자)
- auth_provider_id: String (제공자 측 사용자 ID)
- avatar_url: String (프로필 이미지 URL)

### 서비스 접근 권한 (Service_Access)
- user_id: UUID (FK: Users)
- service_id: UUID (FK: Services)
- access_level: String
- granted_at: Timestamp

### 서비스 (Services)
- id: UUID
- name: String
- description: String
- api_endpoint: String

## 인증 흐름

1. 사용자가 어느 서비스에서든 로그인 (이메일/비밀번호, 구글 또는 애플 계정 사용)
2. ZELLYY Core에서 인증 처리
   - 소셜 로그인의 경우 해당 제공자의 OAuth 흐름을 통해 인증
   - 최초 로그인 시 사용자 정보 생성 및 연결
3. JWT 토큰 발급 및 사용자 서비스 접근 권한 확인
4. 해당 서비스로 리다이렉트 및 SSO 세션 유지

## 소셜 로그인 통합 흐름

```
+-------------+     +--------------+     +---------------+
|  사용자     |---->| ZELLYY Front |---->| 구글/애플 OAuth |
+-------------+     +--------------+     +---------------+
       ^                   ^                    |
       |                   |                    v
       |                   |            +---------------+
       |                   +------------| ZELLYY Core   |
       |                                | Auth Handler  |
       |                                +---------------+
       |                                       |
       |                                       v
       |                               +---------------+
       +-------------------------------|  Supabase     |
                                       |  Auth & DB    |
                                       +---------------+
```

## 확장성을 위한 아키텍처 설계

### 1. 서비스 계층 분리

```
+-------------------+
|    클라이언트     |
+--------+----------+
         |
+--------v----------+
|   API Gateway     |  <-- 트래픽 제어, 로드 밸런싱
+--------+----------+
         |
+--------v----------+     +----------------+
|  Core Services    +---->+  Cache Layer   |  <-- Redis 클러스터
+--------+----------+     +----------------+
         |
+--------v----------+
|  Database Layer   |  <-- 읽기 복제본, 샤딩
+-------------------+
```

### 2. 분산 시스템 패턴

- **Circuit Breaker**: 장애 전파 방지 및 빠른 실패 처리
- **Bulkhead**: 서비스 간 영향 격리
- **Throttling**: API 사용량 제한 및 서비스 보호
- **Saga**: 분산 트랜잭션 처리
- **CQRS**: 읽기/쓰기 작업 분리로 성능 최적화

### 3. 성능 확장 전략

#### 캐싱 계층
- **분산 캐시**: Redis 클러스터를 활용한 세션, 토큰, 자주 사용되는 데이터 캐싱
- **엣지 캐싱**: CDN을 통한 정적 자원 및 API 응답 캐싱
- **멀티 레벨 캐싱**: 클라이언트 → 엣지 → 서버 단계별 캐싱

#### 데이터베이스 확장
- **수직적 확장**: 리소스 증가를 통한 초기 성능 개선
- **수평적 확장**: 샤딩을 통한 데이터 분산
- **읽기/쓰기 분리**: 마스터-슬레이브 구조로 읽기 부하 분산

### 4. 인증 시스템 확장

- **토큰 관리**: 중앙화된 JWT 발급 및 검증
- **세션 저장소**: Redis를 활용한 분산 세션 관리
- **토큰 갱신**: 효율적인 리프레시 토큰 처리
- **세션 동기화**: 멀티 인스턴스 간 세션 정보 동기화

### 5. 모니터링 및 탄력성

- **상태 모니터링**: 서비스 상태 실시간 추적
- **자동 스케일링**: 트래픽에 따른 자동 확장 구성
- **장애 감지**: 이상 징후 조기 발견
- **자동 복구**: 장애 발생 시 자동 대응 체계

### 6. API 버전 관리

- **하위 호환성**: 이전 버전 API 지원
- **점진적 도입**: 새로운 기능의 단계적 출시
- **API 문서 자동화**: OpenAPI 스펙을 통한 문서 관리