아틀리에 도아 정통사주 구조

http://heydoah.com

Architecture

Atelier Doah는 사주명리학 기반의 프리미엄 라이프 디자인 서비스를 제공하는 풀스택 Next.js 애플리케이션입니다.
이 저장소는 퍼블릭 웹 경험, 사주 계산 엔진, Gemini 기반 프리미엄 감명서 생성 파이프라인, Firebase 기반 인증/저장/운영 도구를 하나의 코드베이스로 통합합니다.

System Overview

flowchart LR
    U[사용자] --> W[Next.js 웹앱<br/>Landing / Saju / Result / Order / History / Admin]
    W --> A[Next.js Route Handlers<br/>Auth / Saju / Premium / Gift / Admin]
    A --> E[사주 도메인 엔진<br/>core + engines + decisions]
    A --> G[Gemini 기반 V5 감명서 생성기]
    A --> F[Firebase Auth + Session Cookie]
    A --> D[Firestore<br/>saju_results / saju_library / premium_reports / gift_tickets]
    W --> O[GA4 + Sentry]
    A --> X[ops_events + admin_audit_logs]
    S[Firebase Functions Scheduler] --> A
    S --> D
    M[운영자] --> W

Architecture Style

모듈형 모놀리스 구조입니다.
프론트엔드와 서버 API가 Next.js App Router 안에서 함께 동작합니다.
별도 백엔드 마이크로서비스 대신 Route Handlers + Firebase Admin SDK가 서버 역할을 수행합니다.

Core Layers

1. Presentation Layer

랜딩, 사주 입력, 결과, 주문, 보관함, 관리자 콘솔을 포함한 사용자 인터페이스 계층입니다.

2. Application Layer

인증, 사주 결과 조회, 프리미엄 생성, gift 흐름, 관리자 API 등 서비스 유스케이스를 담당합니다.

3. Domain Engine Layer

사주 원국 계산, 오행 분포, 대운/세운, 신살, 격국, 페르소나 해석 등 명리 로직이 분리되어 있습니다.

4. AI Generation Layer

무료 결과는 결정론적 계산 기반이며, 프리미엄 감명서는 계산 결과를 바탕으로 Gemini가 구조화된 V5 리포트를 생성합니다.

5. Data & Infrastructure Layer

Firebase Authentication, Firestore, Firebase App Hosting, Firebase Functions를 사용합니다.

6. Operations & Observability Layer

GA4, Sentry, Firestore ops_events, Admin Overview를 통해 퍼널, 오류, 운영 이벤트를 분리 관측합니다.

Key Characteristics

• 무료 사주 결과와 프리미엄 감명서가 분리된 이중 파이프라인 구조
• 사주 계산 엔진과 UI가 같은 저장소 안에 공존
• Firestore 중심의 보관함, gift, 공유, 후기, 운영 로그 모델
• 관리자 콘솔을 통한 생성 관제, gift 발급/복구, 후기 검수 지원
• Scheduler를 통한 stuck generation 재시도 및 guest 결과 정리 자동화

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
Infra	Firebase App Hosting, Firebase Cloud Functions
Observability	GA4, Sentry, Firestore ops_events