vooster.ai 경험. MCP로 cursor에 연결은 편리하고 좋지만... 그 이상의 가치는?

# 제품 요구 사항 문서 (PRD)

## 1. 요약
“운동 기록 AI agent”는 운동인의 일상 운동 데이터를 손쉽게 기록·확인하고, AI 챗봇과의 대화를 통해 성장 인사이트를 제공하며, 루틴 알림과 경쟁 기능으로 지속적인 동기 부여를 지원하는 웹앱이다. 깔끔한 UI/UX와 일체형 기술 스택(Next.js + Supabase + Vercel)으로 빠른 개발·배포가 가능하며, 사용자는 자신의 운동 여정을 시각화된 대시보드로 직관적으로 파악할 수 있다.

## 2. 문제 정의
- 운동 기록의 불편함: 여러 앱·노트·엑셀 등 분산된 기록 방식  
- 동기 부여 부족: 보이는 성장 지표와 알림·경쟁 기능 부재  
- 개인화 피드백 부족: 전문 코치 없이 루틴 조정·점검 어려움  
- 디자인 일관성 문제: 기존 운동 기록 툴의 복잡·투박 UI

## 3. 목표 및 목적
- 1차 목표: 운동 기록 CRUD 및 대시보드 기능으로 사용자의 지속적 기록 습관 형성  
- 2차 목표: AI 챗봇을 통한 개인별 분석·조언 제공, 루틴 알림으로 리텐션 향상  
- 부가 목표: 경쟁 랭킹 기능으로 커뮤니티형 동기 부여 제공  
성공지표  
- 주간 활성 사용자(WAU) 5,000명 달성  
- 4주차 리텐션 30% 이상  
- 기록 입력 평균 4회/주 이상  
- 챗봇 세션당 만족도 4.5/5

## 4. 대상 사용자
### 주요 사용자
- 20~40대 운동인, 주 2회 이상 운동, 모바일·PC 둘 다 활용
- 니즈: 빠른 기록, 맞춤 피드백, 진행 상황 시각화, 알림
### 부차적 이해관계자
- 트레이너·코치: 회원 관리 및 피드백 자료 활용
- 헬스케어 브랜드: 광고·제휴 기회

## 5. 사용자 스토리
- 운동인으로서, 운동 직후 간단히 세트를 입력해 진행 상황을 기록하고 싶다.  
- 운동인으로서, 대시보드에서 지난달과 이번 달의 중량 증가 추세를 확인하고 싶다.  
- 운동인으로서, 루틴 알림을 받아 운동을 빠뜨리지 않도록 하고 싶다.  
- 운동인으로서, AI 챗봇에게 “하체 루틴 어떻게 조정할까?”를 물어 맞춤 피드백을 받고 싶다.  
- 운동인으로서, 친구와 랭킹을 비교해 동기부여를 얻고 싶다.  

## 6. 기능 요구사항
### 핵심 기능
1. 운동 기록 CRUD  
   - 세트·무게·횟수·시간·메모 입력/수정/삭제  
   - Acceptance: 3초 이내 저장, 누락 필드 검증  
2. 대시보드  
   - 주·월·누적 그래프, PR(personal record) 하이라이트  
   - Acceptance: 2초 내 렌더링, 데이터 범위 필터 제공  
3. 운동 루틴 등록 및 알림  
   - 루틴 명·요일·알림 시각 설정, 이메일·푸시 발송  
   - Acceptance: 알림 클릭 시 기록 화면 Deep-link  
4. AI 챗봇  
   - 자연어 상담, 루틴 추천, 기록 기반 피드백  
   - Acceptance: 90% 이상 의도 파악, 5초 이내 응답  
### 보조 기능
- Google/Apple 소셜 로그인 (Clerk SaaS)  
- CSV 내보내기·가져오기  
- 친구 초대 및 랭킹(나이스투해브)  
- 다크모드

## 7. 비기능 요구사항
- 성능: P95 응답 500ms 이하(챗봇 제외), Lighthouse 90점 이상  
- 보안: Supabase Row Level Security, OAuth 2.0, HTTPS 전면 적용  
- 사용성: 모바일 우선 디자인, WCAG 2.1 AA  
- 확장성: 모듈형 Next.js App Router 구조, 서버리스(Vercel) 자동 스케일  
- 호환성: 최신 Chrome, Safari, Edge, iOS/Android Webview 지원

## 8. 기술 고려사항
- 아키텍처: Next.js Full-stack + Supabase(PostgreSQL) + Edge Functions  
- 통합: OpenAI API(gpt-4o) → Vercel AI SDK 미들웨어  
- 데이터: 운동 기록 테이블, 사용자 프로필, 루틴, 친구 테이블  
- 외부 의존성: Vercel 배포, Supabase Storage(이미지 업로드)  
- 테스트: Playwright e2e, Supabase local emulator

## 9. 성공 지표
- 제품: WAU, 일평균 기록 수, 챗봇 사용률  
- 비즈니스: Freemium 전환율 10%, 제휴 광고 CTR 3%  
- 기술: 오류율 <1%, 가동시간 99.9%

## 10. 일정 및 마일스톤
- Phase 1 (4주) MVP: 기록 CRUD, 대시보드 기본, 소셜 로그인, 모바일 UI  
- Phase 2 (3주) 알림 & 챗봇: 루틴/알림, AI 챗봇 베타, 피드백 수집  
- Phase 3 (4주) 경쟁 & 프리미엄: 친구 랭킹, CSV 내보내기, 결제 도입  
- 런치 +6주: KPI 리뷰, 기능 개선 로드맵 확정

## 11. 위험 및 완화
- AI 응답 부정확 → 대화 로그 학습, 프롬프트 업데이트 주기적  
- 법적 보안 이슈 → GDPR·개인정보보호법 준수, Data Processing Addendum  
- 사용자 초기 유입 저조 → 인플루언서 협업, 헬스 커뮤니티 바이럴  
- 서버 비용 증가 → Supabase 요금제 모니터링, Edge cache 최적화

## 12. 향후 고려 사항
- 웨어러블 연동(Apple Watch, Garmin)  
- 영상 기반 자세 분석 AI  
- 기업용 B2B 트레이너 대시보드  
- 다국어 지원(EN/JP)  
- 오프라인 행사(챌린지) 연계

# Technical Requirements Document (TRD)

## 1. Executive Technical Summary
- **프로젝트 개요**  
  “운동 기록 AI Agent”는 Next.js 기반 프런트엔드, Node.js-Python 하이브리드 백엔드, MongoDB NoSQL 데이터베이스, Redis 이벤트버스를 핵심으로 한 모노레포 구조로 구현합니다. 도메인 주도 설계(DDD)와 헥사고날 아키텍처를 통해 비즈니스 로직을 깔끔히 분리하며, 이벤트 드리븐 패턴으로 유연한 확장성을 확보합니다.  
- **핵심 기술 스택**  
Next.js 14, Node.js 18, Python 3.10, MongoDB Atlas, Redis(Upstash), Clerk Auth, Supabase Storage, Vercel 배포, Turborepo 모노레포  
- **주요 기술 목표**  
  • P95 API 응답 시간 500ms 이하(챗봇 제외)  
  • Lighthouse 퍼포먼스 90점 이상  
  • 서비스 가동시간 99.9% 이상  
  • 챗봇 응답 지연 5초 이내, 의도 파악 90% 이상  
- **주요 가정 사항**  
  • MongoDB Atlas 및 Redis(Upstash) 글로벌 가용성  
  • Vercel Edge 네트워크 활용한 낮은 레이턴시  
  • Clerk로 OAuth 2.0 및 SSO 통합 가능  
  • Python 마이크로서비스는 AWS Lambda 또는 Vercel Serverless로 운영  

---

## 2. Tech Stack

| Category            | Technology / Library           | Reasoning (선택 이유)                                                                                          |
| ------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Frontend Framework  | Next.js 14                     | React 기반 SSR/SSG 지원, App Router 모듈형 구조, Vercel 최적화                                              |
| Backend Runtime     | Node.js 18                     | Vercel Edge Functions와 호환, 풍부한 생태계, RESTful API 구현 용이                                           |
| AI Microservice     | Python 3.10                    | OpenAI SDK 활용, 머신러닝·NLP 라이브러리 지원, 독립 배포 가능                                                 |
| Monorepo Tooling    | Turborepo                      | 코드 재사용 및 빌드 성능 최적화, 앱·패키지 일관된 관리                                                         |
| Database            | MongoDB Atlas                  | 스키마 유연성, 수평 확장성, NoSQL 요구사항 충족                                                               |
| Cache & Event Bus   | Redis (Upstash)                | 퍼포먼스 캐싱, Pub/Sub 기반 이벤트 드리븐 통신 지원                                                            |
| Authentication      | Clerk SaaS                    | SaaS 기반 이메일·소셜 로그인(OAuth 2.0, Google, Apple), SSO 지원, 사용자 관리 간소화                           |
| Storage             | Supabase Storage               | 이미지 업로드·호스팅, Vercel과 연동 쉬움                                                                      |
| API Pattern         | RESTful (Next.js API Routes)   | 명확하고 확장성 있는 리소스 기반 설계                                                                          |
| Messaging Pattern   | Redis Pub/Sub                  | 내부 도메인 이벤트 처리, 알림·랭킹 실시간 업데이트                                                             |
| Deployment          | Vercel                         | Serverless, Edge Functions, 자동 스케일, CI/CD 통합 용이                                                      |
| CI/CD               | GitHub Actions                 | 모노레포 빌드·테스트·배포 워크플로우 자동화                                                                    |
| Observability       | Sentry, Vercel Analytics       | 에러 추적, 성능 모니터링, 사용성 데이터 시각화                                                                 |
| Security            | AES-256 (민감 데이터 암호화)   | 개인정보보호법·GDPR 대응, 사용자 비밀 필드 안전 보관                                                           |

---

## 3. System Architecture Design

### Top-Level Building Blocks
- 웹 프런트엔드 (Next.js App)  
  • SSR/SSG, CSR 혼합 적용, 모듈형 App Router  
- API 게이트웨이 (Next.js Serverless Functions)  
  • RESTful 엔드포인트, 인증 미들웨어, 로깅/모니터링  
- 도메인 서비스 (Node.js 헥사고날)  
  • 어댑터 레이어, 유스케이스, 엔티티, 인프라 구현체 분리  
- AI 챗봇 서비스 (Python Serverless)  
  • OpenAI 호출, 자연어 처리, 프롬프트 관리  
- 데이터 저장소 (MongoDB Atlas)  
  • 운동 기록, 사용자 프로필, 루틴·친구 컬렉션  
- 캐시 및 이벤트 버스 (Redis Pub/Sub)  
  • 대시보드 캐싱, 알림·랭킹 이벤트 전파  
- 인증 (Clerk SaaS)  
  • Auth 서비스, 이미지 업로드 저장  
- 배포 플랫폼 (Vercel)  
  • 자동 스케일, Edge 최적화, 글로벌 CDN  

### Top-Level Component Interaction Diagram
```mermaid
graph TD
  Web[웹 프런트엔드] -->|REST API| API[API 게이트웨이]
  API --> DB[MongoDB Atlas]
  API --> Cache[Redis Cache]
  API -->|Pub/Sub| EventBus[Redis Pub/Sub]
  API --> Auth[Clerk]
  API --> AI[AI 챗봇 서비스]
  Web -->|Storage| Storage[Supabase Storage]
```

- 웹 → API: 사용자 요청(CRUD, 대시보드, 알림) 호출  
- API → MongoDB: 다양한 도메인별 데이터 저장·조회  
- API → Redis Cache: 자주 조회되는 대시보드 데이터 캐싱  
- API ↔ Redis Pub/Sub: 알림, 랭킹 업데이트 등 이벤트 전파  
- API → Clerk SaaS: OAuth2 인증·인가 처리 및 사용자 관리  
- API → AI 서비스: 챗봇 응답 생성  
- 웹 → Supabase Storage: 이미지 업로드/호출  

### Code Organization & Convention

**도메인 주도 설계(DDD) & 헥사고날 아키텍처**  
- **도메인 분리**: user, record, routine, chatbot, ranking 등 컨텍스트별 폴더  
- **레이어 분리**:  
  presentation(API routes), application(use-cases), domain(entities, value-objects), infrastructure(adapters)  
- **공통 모듈**: types, utils, config, middleware  

**모노레포 파일 구조 (Turborepo 활용)**
```
/
├── apps
│   ├── web/                   # Next.js 프런트엔드
│   ├── api/                   # Node.js 헥사고날 API
│   └── ai-service/            # Python 챗봇 서비스
├── packages
│   ├── ui/                    # 공통 React 컴포넌트
│   ├── utils/                 # 유틸리티 함수
│   ├── types/                 # TypeScript 타입 정의
│   └── config/                # 환경설정 관리
├── infra
│   ├── terraform/             # 인프라 코드 (선택적)
│   └── deployments/           # 배포 스크립트
├── scripts/                   # 빌드·배포·관리 스크립트
├── tests/
│   ├── e2e/                   # Playwright 테스트
│   └── unit/                  # 단위 테스트
└── .github/
    └── workflows/             # CI/CD 파이프라인
```

### Data Flow & Communication Patterns
- **Client-Server 통신**: RESTful JSON API, JWT 토큰 기반 인증  
- **Database 상호작용**: Mongoose ODM 활용, 커넥션 풀 관리  
- **외부 서비스 통합**: Clerk SaaS Auth SDK, Supabase Storage SDK, OpenAI API 호출 멀티스레딩  
- **실시간 통신**: Redis Pub/Sub로 알림, 랭킹 이벤트 전파  
- **데이터 동기화**: 캐시 일관성(TTL), 이벤트 기반 업데이트  

---

## 4. Performance & Optimization Strategy
- 응답 시간 500ms 목표: API 쿼리 옵티마이제이션, 인덱싱 전략 수립  
- 캐싱 활용: Redis에 대시보드, 랭킹 등 빈번 조회 데이터 캐시  
- 서버리스 핫 스타트 최소화: 프론트엔드 SSR 캐시, Edge Functions Warm-up  
- 이미지 최적화: Supabase Storage 및 Vercel 이미지 최적화 플러그인  

---

## 5. Implementation Roadmap & Milestones

### Phase 1: Foundation (MVP 구현, 4주)
- Core Infrastructure: Turborepo 설정, Vercel 배포 파이프라인  
- Essential Features: 운동 기록 CRUD, 대시보드 기본, Google/Apple 소셜 로그인  
- Basic Security: HTTPS, Supabase RLS, AES-256 민감 데이터 암호화  
- Development Setup: GitHub Actions, Playwright 기본 E2E  
- Timeline: 4주  

### Phase 2: Feature Enhancement (3주)
- Advanced Features: 루틴 등록·알림, CSV import/export, 다크모드  
- AI 챗봇 베타: Python 서비스 연결, 기본 피드백 로직  
- Performance Optimization: DB 인덱스·캐시 정책 조정  
- Enhanced Security: SSO, OAuth2 확장  
- Monitoring Implementation: Sentry, Vercel Analytics  
- Timeline: 3주  

### Phase 3: Scaling & Optimization (4주)
- Scalability: 몽고샤드, Redis 클러스터 확장  
- Advanced Integrations: 결제 시스템, B2B 트레이너 대시보드  
- Enterprise Features: 랭킹·커뮤니티 모듈 강화, GDPR 컴플라이언스  
- Compliance & Auditing: 개인정보 보호 로깅, DPA 대응  
- Timeline: 4주  

---

## 6. Risk Assessment & Mitigation Strategies

### Technical Risk Analysis
- **기술 복잡도**: 헥사고날+이벤트 드리븐 설계 초기 진입장벽 → 모듈별 PoC, 단계적 적용  
- **성능 병목**: 비동기 AI 호출 지연 → 캐싱, 타임아웃·리트라이 정책  
- **보안 취약점**: 민감 데이터 노출 → AES-256 암호화, RLS 엄격 적용  
- **통합 불안정**: Clerk SaaS Auth/Supabase Storage/OpenAI 의존성 → 로컬 에뮬레이터, 장애 격리  

### Project Delivery Risks
- **일정 지연**: 주요 기능 병목 발생 → 스코프 조정, 병렬 개발  
- **리소스 부족**: Python·Node.js 전문성 중복 → 크로스 트레이닝, 문서화  
- **품질 저하**: 테스트 커버리지 부족 → CI 게이트, 코드 리뷰 강화  
- **배포 문제**: 무중단 배포 실패 → Canary 배포, 롤백 전략  
- **비상 대응**: 기술 스택 변경, 외부 서비스 장애 시 AWS 대체 경로 마련  

---