Architecture
Atelier Doah는 사주명리학 기반의 프리미엄 라이프 디자인 서비스를 제공하는 풀스택 Next.js 애플리케이션입니다.
이 저장소는 퍼블릭 웹 경험, 사주 계산 엔진, Gemini 기반 프리미엄 감명서 생성 파이프라인, Firebase 기반 인증/저장/운영 도구를 하나의 코드베이스로 통합합니다.
특히 최근 구조에서는 프리미엄 감명서 생성을 브라우저 요청 수명에서 분리하여, 웹 런타임과 백그라운드 생성 런타임을 명확히 나눈 비동기 워커 아키텍처를 채택했습니다.
System Overview
flowchart LR
U[사용자] --> W[Next.js 웹앱<br/>Landing / Saju / Result / Order / History / Admin]
M[운영자] --> W
W --> A[Next.js Route Handlers<br/>Auth / Saju / Premium / Gift / Admin]
W --> O[GA4 + Sentry]
A --> E[사주 도메인 엔진<br/>core + engines + decisions]
A --> F[Firebase Auth + Session Cookie]
A --> D[Firestore<br/>saju_results / saju_library / premium_reports / gift_tickets / premium_generation_jobs]
A --> X[ops_events + admin_audit_logs]
A --> Q[Cloud Tasks enqueue]
Q --> P[Firebase Functions Gen2 Worker<br/>premiumGenerationWorker]
P --> G[Gemini 기반 V5 감명서 생성기]
P --> D
P --> S[Secret Manager + IAM]
C[Firebase Functions Scheduler / Watchdog] --> Q
C --> DArchitecture Style
기본 구조는 모듈형 모놀리스(modular monolith) 입니다.
프론트엔드와 서버 API는 Next.js App Router 안에서 함께 동작하며, 도메인 로직과 운영 도구도 동일 저장소에서 관리됩니다.
다만 프리미엄 감명서 생성은 일반 요청 처리와 분리된 비동기 작업 아키텍처를 따릅니다.
- 웹 요청과 일반 API 응답은 Firebase App Hosting에서 처리합니다.
- 프리미엄 감명서 생성은 Cloud Tasks에 enqueue 됩니다.
- 실제 장시간 생성 작업은 Firebase Functions 2세대 worker가 수행합니다.
- 작업 상태는 Firestore의
premium_generation_jobs가 canonical source로 관리합니다.
즉, 전체적으로는 모놀리식 코드베이스이지만, 실행면은 Web Runtime과 Background Worker Runtime으로 분리된 형태입니다.
Core Layers
1. Presentation Layer
랜딩, 사주 입력, 결과, 주문, 보관함, 프리미엄 리더, 관리자 콘솔을 포함한 사용자 인터페이스 계층입니다.
2. Application Layer
인증, 사주 결과 조회, 프리미엄 생성 요청, gift 흐름, 관리자 API, 후기 시스템 등 주요 서비스 유스케이스를 담당합니다.
3. Domain Engine Layer
사주 원국 계산, 오행 분포, 대운/세운, 신살, 격국, 페르소나 해석 등 명리 로직이 분리되어 있습니다.
무료 결과는 이 계층의 결정론적 계산 결과를 직접 사용합니다.
4. AI Generation Layer
프리미엄 감명서는 계산 결과를 기반으로 Gemini가 구조화된 V5 리포트를 생성합니다.
이 과정은 theme design -> act generation -> enrichment -> finalize 단계로 이루어지며, draft checkpoint와 retry-safe worker 실행을 지원합니다.
5. Queue & Worker Layer
프리미엄 생성 요청은 premium_generation_jobs 문서로 기록된 뒤 Cloud Tasks에 enqueue 됩니다.premiumGenerationWorker가 lease 획득, heartbeat 갱신, 생성 실행, 완료/실패 마킹, 재시도 상태 전환을 담당합니다.
6. Data & Infrastructure Layer
Firebase Authentication, Firestore, Firebase Admin SDK, Firebase App Hosting, Firebase Functions Gen2, Cloud Tasks, Secret Manager, IAM을 사용합니다.
7. Operations & Observability Layer
GA4, Sentry, Cloud Logging, Firestore ops_events, admin_audit_logs, Admin Overview를 통해 퍼널, 오류, 운영 이벤트, 생성 상태를 분리 관측합니다.
Key Characteristics
- 무료 사주 결과와 프리미엄 감명서가 분리된 이중 파이프라인 구조
- 사주 계산 엔진과 UI가 같은 저장소 안에 공존하는 모듈형 모놀리스
- 프리미엄 생성은
enqueue -> worker execute -> watchdog recover구조의 비동기 작업 실행 - Firestore 중심의 보관함, gift, 공유, 후기, 운영 로그, job 상태 모델
premium_generation_jobs를 기준으로 source 문서(gift_tickets,saju_library)에 상태를 미러링하는 구조- 관리자 콘솔을 통한 생성 관제, gift 발급/복구, 후기 검수 지원
- draft checkpoint, heartbeat, idempotent finalize, retry orchestration을 통한 장시간 생성 안정성 확보
- App Hosting과 Functions가 같은 코드베이스를 공유하되, 실행 책임은 웹 요청 처리와 백그라운드 작업으로 분리
- Secret Manager와 IAM을 통한 런타임 시크릿 및 권한 관리
Tech Stack
| Area | Stack |
|---|---|
| Frontend | Next.js 14, React 18, TypeScript, Tailwind CSS, Framer Motion, Three.js |
| Backend App | Next.js Route Handlers, server-only modules |
| Domain Logic | custom saju engine, lunar-javascript |
| AI | Google Gemini, @ai-sdk/google, ai, @google/genai |
| Auth / Data | Firebase Authentication, Firestore, Firebase Admin SDK |
| Web Runtime | Firebase App Hosting |
| Background Runtime | Firebase Functions Gen2 |
| Queue / Recovery | Google Cloud Tasks, Scheduler watchdog |
| Secrets / Access | Google Cloud Secret Manager, IAM |
| Observability | GA4, Sentry, Cloud Logging, Firestore ops_events |
