CCP Coin

A stock prediction game where users bet virtual coins on AI-generated stock forecasts. Users sign up, receive a daily AI prediction for a stock (up/down), place a virtual coin bet, and earn or lose coins based on whether the prediction was correct. A leaderboard tracks top performers.

---

Tech Stack

Layer	Technology
Frontend	Next.js 14, React 18, TypeScript, Tailwind CSS
Backend	FastAPI (Python), Uvicorn
Database	Supabase (PostgreSQL)
Auth	Supabase Auth + JWT middleware
AI/ML	AWS SageMaker (daily predictions), yfinance
Storage	AWS S3 (prediction results)
Monitoring	AWS CloudWatch
Testing	pytest (backend), Vitest + Playwright (frontend)

---

Project Structure

• frontend/ — Next.js app
• backend/ — FastAPI backend, serves all API endpoints
• supabase/migrations/ — SQL migration files for database schema

---

Prerequisites

• Python 3.10+
• Node.js 18+
• pip
• A Supabase account and project
• (Optional) AWS account for SageMaker/S3/CloudWatch

---

Installation

Backend

cd backend
pip install -r requirements.txt

Frontend

cd frontend
npm install

---

Environment Variables

backend/.env

SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
SUPABASE_JWT_SECRET=your_jwt_secret

AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
AWS_REGION=us-east-1

frontend/.env.local

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Get Supabase credentials from: Dashboard → Settings → Database / API.

---

Running the App

# Backend (from backend/)
uvicorn main:app --reload

# Frontend (from frontend/, separate terminal)
npm run dev

• Backend: http://localhost:8000
• Frontend: http://localhost:3000
• API docs: http://localhost:8000/docs

---

API Endpoints

Most endpoints require a Authorization: Bearer <token> header (set by Supabase Auth). Public endpoints are marked.

Method	Endpoint	Auth	Description
GET	/	Public	Health check
GET	/prediction/today	Public	Most recent AI prediction for a stock
GET	/prediction/history	Public	Past AI predictions for a stock
GET	/stock/price	Public	Current price for a single ticker
GET	/stocks/market-data	Public	Batch price + sparkline for multiple tickers
GET	/leaderboard	Public	Top users by dubcoin balance
GET	/me	Required	Current user from JWT
GET	/auth/me	Required	Current user id and email from middleware
GET	/user/profile	Required	Authenticated user's full profile
POST	/bets/place	Required	Place a bet on a stock direction
GET	/bets/history	Required	Authenticated user's betting history
GET	/bets/resolve	Required	Resolve all pending bets for the user

Query parameters:

• stock — ticker symbol (default: AAPL) — used by prediction endpoints
• ticker — ticker symbol — used by /stock/price
• tickers — comma-separated symbols (default: AAPL,TSLA,MSFT,NVDA,AMZN,META) — used by /stocks/market-data
• limit — number of records to return (default varies per endpoint)

---

Database Tables

Table	Description
users	User profiles — balance, streak, rank, accuracy, xp, level
bets	Bet records — ticker, direction, stake, status, entry price
ai_predictions	AI prediction history — stock, prediction, confidence, actual, correct, date

---

MVP Features

• User registration and login (Supabase Auth)
• Daily AI stock prediction (up/down + confidence score)
• Virtual coin betting on predictions
• Bet resolution with automatic payout and balance updates
• Prediction history and accuracy tracking
• Leaderboard of top coin earners
• AWS CloudWatch monitoring of API latency and errors

---

Contributing

1. Fork the repo and create a branch from main
2. Make your changes in the branch
3. Run tests before opening a PR:

   # Backend tests
   cd backend && pytest
   
   # Frontend tests
   cd frontend && npm test

4. Open a pull request with base: main and describe your changes