Skip to content
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
21ff151
feat: add Cloudflare Workers backend (D1 + Nitro + Drizzle) replacing…
Swastikdan Aug 15, 2026
99403d9
feat(backend): implement Cloudflare Workers backend with D1 and Nitro
Swastikdan Aug 15, 2026
8fe646f
refactor(schema): replace Zod with Valibot across all server schemas …
Swastikdan Aug 15, 2026
ada5a9d
ci: configure Cloudflare deploy workflow for cloudflare and feature b…
Swastikdan Aug 15, 2026
d5136d6
chore: update pnpm-lock.yaml after removing zod
Swastikdan Aug 15, 2026
daaa8c5
ci: specify pnpm version for GitHub Actions workflow
Swastikdan Aug 15, 2026
b67efdf
ci: rely on packageManager field in package.json for pnpm version
Swastikdan Aug 15, 2026
a917bf8
fix(import): sanitize reaction, progress, and rating inputs to satisf…
Swastikdan Aug 15, 2026
8a93a62
perf: remove Upstash Redis in favor of direct D1 edge queries and opt…
Swastikdan Aug 15, 2026
4619230
chore: update pnpm-lock.yaml after dependency removals
Swastikdan Aug 15, 2026
75b4d4c
fix(auth): handle expired/malformed Clerk tokens gracefully without l…
Swastikdan Aug 15, 2026
a811412
chore: Update public app URL to swastik.workers.dev
Swastikdan Aug 15, 2026
7e3595d
docs: update README with Cloudflare Workers, D1, Drizzle, and Valibot…
Swastikdan Aug 15, 2026
1b5c629
feat: implement RequestBatcher utility and batch watchlist membership…
Swastikdan Aug 15, 2026
1bb75c6
feat: implement upsert logic for watch items and episode progress, up…
Swastikdan Aug 15, 2026
a81daa2
refactor: improve watchlist import schema and validation logic for ro…
Swastikdan Aug 15, 2026
66f6f08
refactor: update watchlist metadata types to handle nullability and i…
Swastikdan Aug 15, 2026
253774a
refactor: update watchlist mutation handlers to return authoritative …
Swastikdan Aug 16, 2026
dc6ca80
refactor: add lifecycle-managed flush to RequestBatcher, introduce Da…
Swastikdan Aug 16, 2026
e833633
refactor: remove unnecessary pulse animations and optimize CSS transi…
Swastikdan Aug 16, 2026
80abae3
refactor: harden security with D1 batch constraints, live JWT admin c…
Swastikdan Aug 16, 2026
cfd4242
refactor: migrate daily pick logic to custom hook and integrate toast…
Swastikdan Aug 16, 2026
b69dffe
feat: implement user caching with fast-path lookups and optimize data…
Swastikdan Aug 16, 2026
68068ca
refactor: migrate backend from Convex to Drizzle and implement reposi…
Swastikdan Aug 16, 2026
5cce60d
refactor: migrate backend from Convex to Drizzle and implement reposi…
Swastikdan Aug 16, 2026
972393f
docs: add comprehensive project documentation and remove docs folder …
Swastikdan Aug 16, 2026
68e3eb0
perf: optimize memory usage and UI performance by reducing query garb…
Swastikdan Aug 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ VITE_CLERK_ISSUER_URL=https://your-app.clerk.accounts.dev
VITE_CLERK_PUBLISHABLE_KEY=pk_test_YOUR_CLERK_PUBLISHABLE_KEY

# App URLs
VITE_PUBLIC_APP_URL=https://pebbly.vercel.app
VITE_PUBLIC_APP_URL=https://pebbly.swastik.workers.dev

# TMDB API (read-only public API key — safe for client)
VITE_PUBLIC_TMDB_ACCESS_TOKEN=your_tmdb_read_access_token
Expand All @@ -21,3 +21,15 @@ CONVEX_DEPLOY_KEY=prod:your-deployment|your-deploy-key
# AI Providers (server-only — never expose in client code)
OPENROUTER_API_KEY=sk-or-v1-your-key
GEMINI_API_KEY=your_gemini_key

# ---- Cloudflare Workers backend (post-Convex migration) ----
# Local dev secrets live in .dev.vars (gitignored); production uses
# `wrangler secret put <NAME>` with the same names.

# Clerk (server-side session token verification via @clerk/backend)
CLERK_SECRET_KEY=sk_test_YOUR_CLERK_SECRET_KEY
CLERK_ISSUER_URL=https://your-app.clerk.accounts.dev

# Cloudflare (needed for `pnpm db:studio` remote dashboard + GitHub Actions)
CLOUDFLARE_API_TOKEN=your-api-token-with-d1-edit
CLOUDFLARE_ACCOUNT_ID=your-account-id
41 changes: 41 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: Deploy Cloudflare
on:
push:
branches:
- cloudflare
- feat/convex-to-traditional-backend
workflow_dispatch: # Allows manual trigger from GitHub Actions UI

jobs:
deploy:
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
with: { node-version: 22, cache: pnpm }
- run: pnpm install --frozen-lockfile
- run: pnpm typecheck

- name: Apply D1 migrations (prod)
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: d1 migrations apply pebbly --remote

- name: Build (Nitro cloudflare preset)
run: pnpm build
env:
VITE_CLERK_PUBLISHABLE_KEY: ${{ secrets.VITE_CLERK_PUBLISHABLE_KEY }}
VITE_PUBLIC_TMDB_ACCESS_TOKEN: ${{ secrets.VITE_PUBLIC_TMDB_ACCESS_TOKEN }}
VITE_PUBLIC_TMDB_API_URL: ${{ secrets.VITE_PUBLIC_TMDB_API_URL }}
VITE_PUBLIC_APP_URL: ${{ secrets.VITE_PUBLIC_APP_URL }}
VITE_PUBLIC_VIDEO_URL: ${{ secrets.VITE_PUBLIC_VIDEO_URL }}

- name: Deploy Worker
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: deploy
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,9 @@ implementation_plan.md
.skills-lock.json
.agents
skills-lock.json

# Cloudflare / wrangler
.dev.vars
.wrangler/
convex-export/

157 changes: 109 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Pebbly (Film Fanatic)

Pebbly is a modern, full-stack movie and TV show discovery application built with TanStack Start, Convex, Clerk, Google Gemini AI, and TMDB metadata. It combines rich media browsing with persistent watchlists, granular episode progress tracking, custom user lists, and a personalized AI Recommendation Engine.
Pebbly is a modern, full-stack movie and TV show discovery application built with **TanStack Start**, **Cloudflare Workers**, **Cloudflare D1 (SQLite)**, **Drizzle ORM**, **Valibot**, **Clerk**, **Google Gemini AI**, and **TMDB metadata**. It combines rich media browsing with persistent watchlists, granular episode progress tracking, custom user lists, and a personalized AI Recommendation Engine.

---

Expand All @@ -10,11 +10,11 @@ Pebbly is a modern, full-stack movie and TV show discovery application built wit
- **Comprehensive Browsing**: Explore trending, popular, top-rated, upcoming, and curated movie/TV collections.
- **Advanced Search**: Instant cross-media search with genre, media type, and keyword filtering.
- **Rich Details & Media Player**: Complete detail pages with cast/crew, trailers, season/episode browsers, and embedded video modal with responsive controls.
- **Smart Watchlist & Progress**: Track progress (`want-to-watch`, `watching`, `caught-up`, `finished`, `dropped`), per-episode watching status, and reaction tags (`loved`, `liked`, `mixed`, `not-for-me`).
- **Custom Lists & Management**: Create custom lists, export/import watchlists in JSON format, and sync seamlessly across devices via Convex.
- **Smart Watchlist & Progress**: Track progress (`watch-later`, `watching`, `done`, `dropped`), per-episode watching status, and reaction tags (`loved`, `liked`, `mixed`, `not-for-me`, `recommended`).
- **Custom Lists & Management**: Create custom lists, export/import watchlists in JSON format, and sync seamlessly across devices via Cloudflare D1.

### AI Recommendation Engine
- **Watchlist & Interaction-Aware AI**: Generates tailored movie and TV recommendations using Google Gemini models (`gemini-3.1-flash-lite-preview`, `gemini-2.5-flash`, etc.).
- **Watchlist & Interaction-Aware AI**: Generates tailored movie and TV recommendations using Google Gemini models (`gemini-2.5-flash`, `gemini-3.1-flash-lite-preview`).
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
- **Homepage "Picks For You"**: Dedicated homepage widget providing twice-daily refreshed recommendations with real-time watchlist exclusion.
- **Interaction Feedback Loop**: User interactions (thumbs up / thumbs down) train future recommendations. Liked recommendations are automatically added to your **Pebbly Picks** list, and disliked titles are excluded.
- **Advanced Filtering**: Generate recommendations by Watchlist, Custom List, Genre preferences, or Era presets (Classics, 80s, 90s, 2000s, 2010s, 2020s).
Expand All @@ -27,43 +27,46 @@ Pebbly is a modern, full-stack movie and TV show discovery application built wit
| Layer | Technology |
| :--- | :--- |
| **Framework** | [TanStack Start](https://tanstack.com/start) + [TanStack Router](https://tanstack.com/router) + React 19 |
| **Backend & Realtime** | [Convex](https://www.convex.dev/) |
| **Host & Compute** | [Cloudflare Workers](https://workers.cloudflare.com/) (Nitro `cloudflare_module` preset) |
| **Database** | [Cloudflare D1](https://developers.cloudflare.com/d1/) (SQLite) via [Drizzle ORM](https://orm.drizzle.team/) |
| **Validation** | [Valibot](https://valibot.dev/) (Lightweight, modular schema validation) |
| **Authentication** | [Clerk](https://clerk.com/) (`@clerk/react` + `@clerk/backend` JWT verification) |
| **AI Engine** | Google GenAI SDK (`@google/genai` - Gemini Flash models) |
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
| **Authentication** | [Clerk](https://clerk.com/) |
| **Styling** | Tailwind CSS 4, Radix UI, shadcn/ui |
| **Data Fetching** | TanStack Query (React Query) |
| **State Management** | Zustand |
| **Tooling & Linter** | Vite 7, Biome, TypeScript |
| **Tooling & Linter** | Vite 7, Biome, TypeScript, Wrangler |

---

## Project Structure

```
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
├── convex/ # Convex backend schemas, queries, mutations, and actions
│ ├── schema.ts # Database tables (users, watch_items, ai_recommendations, lists, etc.)
│ ├── recommendations.ts # AI recommendation engine actions, prompts, and feedback handling
│ ├── watchlist.ts # Watchlist management, custom lists, and snapshots
│ ├── crons.ts # Scheduled background tasks (e.g. daily watchlist snapshots)
│ └── admin.ts # Feature flags & RBAC permission checks
├── drizzle/ # Drizzle generated SQL migrations for Cloudflare D1
├── server/ # Nitro server routes and scheduled tasks
│ ├── routes/api/health.ts # /api/health endpoint (D1 status check)
│ └── tasks/snapshots.ts # Daily watchlist snapshots cron task
├── src/
│ ├── server/ # Co-located backend server functions & database layer
│ │ ├── db/ # D1 database schema & Drizzle client
│ │ ├── fns/ # Type-safe TanStack Start server functions (watchlist, lists, recs, admin)
│ │ ├── schema/ # Valibot schemas & typed API result contracts
│ │ ├── auth.ts # Clerk server-side JWT verification & user resolution
│ │ ├── ai.ts # Gemini AI client with model fallback chain
│ │ ├── prompts.ts # Context-aware prompts for AI recommendations
│ │ └── rbac.ts # Role-based access control & feature flags
│ ├── components/ # UI components & domain-specific widgets
│ │ ├── homepage-recommendations.tsx # Homepage "Picks For You" row with interaction buttons
│ │ ├── video-player-modal.tsx # Fullscreen-capable responsive video player
│ │ ├── media-card.tsx # Reusable media grid/carousel card
│ │ └── recommendations/ # Recommendation loading skeletons and UI elements
│ │ └── recommendations/ # Recommendation loading skeletons and UI elements
│ ├── hooks/ # Custom hooks (watchlist, watch progress, recommendations, RBAC)
│ │ ├── use-recommendations.ts # Client-side hook for AI recommendation generation & history
│ │ └── use-permissions.ts # RBAC & feature flag access control hook
│ ├── lib/ # Core utility libraries & clients
│ │ ├── recommendation-engine.ts # Shared TMDB resolution engine, fuzzy matching & caching hooks
│ │ ├── queries.ts # TMDB API query functions
│ │ └── media-transform.ts # TMDB payload transformations
│ ├── lib/ # Core utility libraries, query keys, and TMDB queries
│ ├── routes/ # TanStack file-based routes
│ │ ├── index.tsx # Homepage route
│ │ ├── recommendations.lazy.tsx # AI Recommendations management & generation page
│ │ └── search.lazy.tsx # Search & discovery page
│ └── types.d.ts # TypeScript declarations & domain types
├── wrangler.toml # Cloudflare Workers & D1 configuration
├── drizzle.config.ts # Drizzle Kit migration generator config
└── drizzle.studio.config.ts # Drizzle Studio dashboard config
```

---
Expand All @@ -72,77 +75,135 @@ Pebbly is a modern, full-stack movie and TV show discovery application built wit

### Prerequisites

- Node.js 20+
- `pnpm` (or `npm`/`yarn`)
- Node.js 22+
- `pnpm` (v10+)
- A TMDB API Read Access Token
- A Clerk Application
- A Convex Deployment
- A Google Gemini API Key
- A Cloudflare Account (with D1 database enabled)

### Environment Setup

1. Clone the repository:
1. **Clone the repository:**
```bash
git clone https://github.com/Swastikdan/Pebbly.git
cd Pebbly
```

2. Install dependencies:
2. **Install dependencies:**
```bash
pnpm install
```

3. Create a `.env.local` file in the project root:
3. **Configure environment variables:**
Create a `.env` or `.env.local` file in the project root:
```env
# TMDB API (read-only public API key — safe for client)
VITE_PUBLIC_TMDB_ACCESS_TOKEN=your_tmdb_read_access_token
VITE_PUBLIC_TMDB_API_URL=https://api.themoviedb.org/3

VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key
CONVEX_CLERK_ISSUER_URL=https://your-clerk-domain
# Clerk Auth
VITE_CLERK_PUBLISHABLE_KEY=pk_test_YOUR_CLERK_PUBLISHABLE_KEY
CLERK_SECRET_KEY=sk_test_YOUR_CLERK_SECRET_KEY
CLERK_ISSUER_URL=https://your-app.clerk.accounts.dev

VITE_CONVEX_URL=your_convex_url
# App URLs
VITE_PUBLIC_APP_URL=http://localhost:3000
VITE_PUBLIC_VIDEO_URL=your_video_provider_base_url

# AI Providers
GEMINI_API_KEY=your_gemini_key

# Cloudflare (needed for `pnpm db:studio` dashboard & GitHub Actions)
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
```

4. Set the Gemini API key in your Convex deployment environment variables:
4. **Initialize the local database:**
```bash
npx convex env set GEMINI_API_KEY your_gemini_api_key
pnpm db:migrate:local
```

### Running Locally
---

## Running Locally

- Run frontend & Convex dev server concurrently:
- **Run frontend dev server (Vite + Node SSR):**
```bash
pnpm dev
```

- Run typecheck and Biome validation:
- **Run full Cloudflare Workers + Miniflare D1 emulator locally:**
```bash
pnpm check
pnpm preview:cf
```

- Build for production:
- **Run TypeScript validation & Biome linting:**
```bash
pnpm build
pnpm typecheck
pnpm lint
```

---

## Database & Migrations

- **Generate new SQL migration after editing `src/server/db/schema.ts`:**
```bash
pnpm db:generate
```

- **Apply migrations to local database (`.wrangler` emulator):**
```bash
pnpm db:migrate:local
```

- **Apply migrations to remote Cloudflare D1 database (Production):**
```bash
pnpm db:migrate:prod
```

- **Open Drizzle Studio to view/edit database tables in your browser:**
```bash
pnpm db:studio
```

---

## Deploying to Cloudflare

Deploying to Cloudflare Workers is automated via GitHub Actions CI/CD whenever you push to the deployment branch, or you can deploy manually:

```bash
# 1. Apply any pending migrations to production D1
pnpm db:migrate:prod

# 2. Build and publish to Cloudflare Workers
pnpm deploy:cf
```

---

## Available Scripts

- `pnpm dev` — Run Vite frontend and Convex dev server in parallel
- `pnpm dev:vite` — Run frontend dev server only
- `pnpm dev:convex` — Run Convex local dev server only
- `pnpm build` — Type-check and build production bundle
- `pnpm check` — Biome linter check + TypeScript validation
- `pnpm format` — Format code with Biome
| Script | Description |
| :--- | :--- |
| `pnpm dev` | Run Vite development server |
| `pnpm preview:cf` | Build and run full app on local Cloudflare Worker & D1 emulator |
| `pnpm build` | Build production bundle (Nitro Cloudflare preset) |
| `pnpm db:generate` | Generate SQL migrations from `src/server/db/schema.ts` |
| `pnpm db:migrate:local` | Apply migrations to local Miniflare D1 database |
| `pnpm db:migrate:prod` | Apply migrations to Cloudflare production D1 database |
| `pnpm db:studio` | Launch Drizzle Studio database explorer |
| `pnpm deploy:cf` | Build and deploy directly to Cloudflare Workers |
| `pnpm typecheck` | Run TypeScript compiler type-checking |
| `pnpm lint` | Run Biome linter |
| `pnpm format` | Auto-format codebase with Biome |

---

## License & Acknowledgments

- Movie and TV metadata provided by [TMDB](https://www.themoviedb.org/).
- AI Recommendations powered by [Google Gemini](https://ai.google.dev/).
- Built with TanStack, Convex, Clerk, and Tailwind CSS.
- Built with TanStack Start, Cloudflare Workers, D1, Drizzle ORM, Valibot, Clerk, and Tailwind CSS.
10 changes: 10 additions & 0 deletions drizzle.config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import { defineConfig } from "drizzle-kit";

// generate-only config: `drizzle-kit generate` emits SQL migrations into ./drizzle.
// They are applied to D1 with `wrangler d1 migrations apply pebbly [--local|--remote]`,
// so no live DB connection (driver) is required here.
export default defineConfig({
dialect: "sqlite",
schema: "./src/server/db/schema.ts",
out: "./drizzle",
});
41 changes: 41 additions & 0 deletions drizzle.studio.config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import { defineConfig } from "drizzle-kit";
import fs from "node:fs";

/**
* Drizzle Studio dashboard for the remote (production) D1 database.
*
* pnpm db:studio
*
* Uses the `d1-http` driver (Cloudflare API) — no local sqlite client needed.
* Credentials come from the environment:
* - CLOUDFLARE_API_TOKEN (API token with "D1 Edit" permission)
* - CLOUDFLARE_ACCOUNT_ID (Cloudflare account id)
* The database id is read from wrangler.toml.
*
* For the local D1 database use:
* wrangler d1 execute pebbly --local --command "SELECT * FROM watch_items;"
*/
function readWranglerTomlValue(key: string): string | undefined {
try {
const raw = fs.readFileSync(
new URL("./wrangler.toml", import.meta.url),
"utf8",
);
const match = raw.match(new RegExp(`^${key}\\s*=\\s*"([^"]+)"`, "m"));
return match?.[1];
} catch {
return undefined;
}
}

export default defineConfig({
dialect: "sqlite",
schema: "./src/server/db/schema.ts",
out: "./drizzle",
driver: "d1-http",
dbCredentials: {
accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "",
databaseId: readWranglerTomlValue("database_id") ?? "",
token: process.env.CLOUDFLARE_API_TOKEN ?? "",
},
Comment thread
Swastikdan marked this conversation as resolved.
Resolved
});
Loading
Loading