Obsidian/ZELLYY/zellyy core/architecture.md

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 (사용 중인 서비스 목록)
• 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 스펙을 통한 문서 관리