🔮 AI Tarot Master: 운명의 속삭임

Gemini AI를 활용하여 사용자의 고민을 깊이 있게 해석해주는 웹 타로 서비스입니다. 전통적인 타로 해석에 최신 AI 기술을 접목하여 개인화된 경험을 제공합니다.

---

✨ 주요 기능 (Key Features)

• AI 타로 해석: Google Gemini 3.1 flash-lite 모델을 활용한 정교한 카드 리딩
• 실시간 로딩 애니메이션: Framer Motion을 활용한 몰입감 있는 사용자 경험
• 개인 히스토리: 과거에 본 타로 내역을 다시 확인할 수 있는 저장 기능
• 결과 공유: 해석 결과를 텍스트로 복사하여 간편하게 공유

🚀 배포 주소 (Deployment)

https://tarot-mauve.vercel.app

• 배포 아키텍처:
  • Front-end: Vercel (Auto Deployment)
  • Back-end: Render (NestJS 서버 호스팅)
  • Database: Supabase

📸 서비스 화면 (Screenshots)

🔮 메인 및 타로 리딩

메인 페이지	카드 선택	해석 결과

📜 결과 확인 이후 및 히스토리

결과 후 액션	나의 히스토리 (목록)	지난 기록 다시보기

🛠 기술 스택 (Tech Stack)

Frontend

• Framework: React (TypeScript)
• Routing: React Router
• Build Tool: Vite
• Data Fetching: Axios
• Styling: Tailwind CSS
• Animation: Framer Motion
• UI Feedback: React Hot Toast
• State Management: Zustand

Backend

• Framework: NestJS (Node.js)
• Language: TypeScript
• Database: PostgreSQL (Supabase)
• ORM: Prisma
• Communication: Axios
• Auth/Storage: Supabase
• ** Hosting**: Render
• AI Integration: Google Gemini 3.1 Flash-Lite-preview (@google/genai SDK)

---

📂 프로젝트 구조 (Structure)

• frontend/: React 기반 웹 클라이언트
• backend/: NestJS 기반 API 서버

🎮 사용 방법 (How to Use)

1. 질문 입력: 오늘 하루의 운세나 고민 중인 질문을 입력창에 적어주세요.
2. 카드 선택: 화면에 놓인 타로 카드 중 마음이 끌리는 카드를 선택합니다.
3. AI 해석 대기: Gemini AI가 당신의 질문과 카드를 분석하여 해석을 준비하는 동안 잠시 기다려주세요.
4. 결과 확인 및 저장: 정교한 타로 해석 결과를 읽고, 마음에 든다면 텍스트로 복사하거나 로그인하여 히스토리에 저장하세요!

---

서비스 아키텍처 (Service Architecture)

• Client: React + Vite (SPA)
• Server: NestJS (REST API)
• AI: Google Gemini API (Stream/JSON Mode)
• DB/Auth: Supabase (PostgreSQL)

핵심 구현 포인트 (Core Implementation)

1. Gemini 3.1 flash-lite-preview 기반 AI 타로 리딩

• 프롬프트 엔지니어링: 타로 마스터의 페르소나를 정밀하게 설정하여 일관성 있고 신뢰감 있는 해석 제공
• 구조화된 데이터 응답: AI의 응답을 JSON 포맷으로 강제하여 프론트엔드에서 즉시 UI 요소(카드 의미, 조언, 총평 등)로 활용 가능하도록 설계

2. 하이브리드 세션 관리 (로그인 & 비로그인)

• 사용자 경험 최적화: 비로그인 상태에서도 타로 해석을 즉시 볼 수 있도록 isSessionLoaded 상태 로직 구현
• 데이터 자동 동기화: 로그인 사용자일 경우 해석 결과를 Supabase DB에 실시간 저장하여 마이페이지(History)에서 확인 가능하도록 구현

3. 몰입감 있는 UI/UX 설계

• 애니메이션: Framer Motion을 활용하여 실제 타로 카드를 뽑는 듯한 생동감 있는 인터랙션 구현
• 비동기 상태 처리: Axios 인터셉터와 React Hot Toast를 연동하여 AI 응답 대기 및 에러 상황을 사용자에게 친절하게 안내

---

🔌 핵심 API 명세 (Core API)

AI Interpretation

Method	Endpoint	Description
POST	/tarot/interpretation	질문과 선택한 카드를 전달하여 Gemini AI의 해석 결과 생성
GET	/tarot/history	로그인한 사용자의 과거 타로 저장 내역 조회
GET	/tarot/history/:id	특정 타로 해석 결과 상세 조회

🧠 AI 연동 로직 (AI Integration)

• Service Layer: NestJS의 Service에서 GoogleGenerativeAI 라이브러리를 통해 Gemini 3.1 Flash-lite 모델과 통신
• System Instructions: AI가 일관된 타로 마스터의 톤앤매너를 유지하도록 시스템 프롬프트를 정교화
• Schema Enforcement:
  • AI가 반드시 정해진 JSON 구조로 응답하도록 Response Schema 설정
  • 이를 통해 프론트엔드에서 파싱 에러 없이 즉시 데이터를 렌더링할 수 있는 안정성 확보

---

⚖️ License & Credits

• Tarot Design Standard: 전 세계 표준인 라이더 웨이트(Rider-Waite) 타로의 상징 체계와 규격을 바탕으로 설계되었습니다.
• Tarot Card Images: 본 프로젝트에 사용된 타로 카드 실물 이미지(PNG)는 **나노바나나(Nanobanana)**의 에셋을 활용하여 제작되었습니다.
• Author: yunsuper (Full-stack Development)
• License: MIT License - 본 프로젝트는 MIT 라이선스를 따르며, 자유로운 이용과 수정이 가능합니다.
• AI Disclaimer: 본 프로젝트의 타로 해석 결과는 Google Gemini 3.1 Flash-lite 모델에 의해 생성되었습니다. AI의 해석은 참고용일 뿐이며, 법적·의학적·전문적 조언을 대신할 수 없습니다.

🤖 AI Aided Development

• 본 프로젝트의 코드 설계 및 최적화 과정에서 AI 기술(Gemini)을 보조 도구로 활용하여 코드 품질을 향상시켰습니다.