ChapterCheck

Your personal audiobook library, beautifully organized.

Features · Tech Stack · Getting Started · Running the Web App · Testing · Deployment

---

Features

• Book Management — Add, edit, search, and organize your audiobook collection with cover images
• Author Tracking — Author profiles with photos, support for narrators and translators
• Audio Player — Stream MP3/M4A/M4B files with progress tracking and playback speed control
• Series Organization — Group books into series with decimal position numbering (e.g., 2.5 for novellas)
• Real-time — Powered by Convex for instant updates across all connected clients

---

Tech Stack

Category	Technology
Monorepo	Turborepo + Yarn 4 workspaces
Web	Next.js 15 (App Router), React 19
Database	Convex (real-time)
Authentication	Clerk
Storage	Cloudflare R2 (S3-compatible)
Web UI	shadcn/ui + Radix UI
Styling	Tailwind CSS + CSS Variables
Forms	React Hook Form + Zod
Testing	Vitest + React Testing Library, Playwright (E2E)
Deployment	Cloudflare Workers + Pages (via OpenNext)

---

Project Structure

chaptercheck/
├── apps/
│   ├── web/                    # Next.js web application
│   └── ios/                    # Native SwiftUI iOS app
├── packages/
│   ├── convex-backend/         # Convex schema, queries, mutations
│   ├── shared/                 # Shared hooks, validations, utils, types
│   └── tailwind-config/        # Shared Tailwind theme, cn(), color tokens
├── e2e/                        # Playwright E2E tests
├── scripts/                    # Seed scripts
├── turbo.json                  # Turborepo task config
├── convex.json                 # Points Convex CLI to packages/convex-backend/convex
└── package.json                # Root workspace config (Yarn 4)

---

Getting Started

Prerequisites

• Node.js 20+
• Yarn 4 (the repo uses packageManager: yarn@4.12.0 — Corepack will auto-install it)
• A Convex account
• A Clerk account (with a dev instance for local development)
• A Cloudflare account (for R2 storage)

Clone and Install

# Clone the repository
git clone https://github.com/griggen/chaptercheck.git
cd chaptercheck

# Enable Corepack (provides Yarn 4 automatically)
corepack enable

# Install all dependencies (root + all apps/packages)
yarn install

Environment Variables

Copy the example file and fill in your credentials:

cp .env.example .env.local

The web app reads from apps/web/.env.local, which symlinks to the root .env.local.

# Convex
CONVEX_DEPLOYMENT=dev:your-deployment
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Cloudflare R2
R2_ACCOUNT_ID=your-account-id
R2_TOKEN_VALUE=your-token
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key

Start the Convex Backend

The Convex dev server must be running. Run this from the repo root:

npx convex dev

This watches packages/convex-backend/convex/ for changes and syncs to your dev deployment.

---

Running the Web App

# From the repo root — starts the Next.js dev server (port 3000)
yarn dev --filter=@chaptercheck/web

Or run everything at once (all apps that have a dev script):

yarn dev

Then open http://localhost:3000.

---

Testing

Unit Tests (Vitest)

# Run all tests in watch mode
yarn test

# Single run (CI-friendly)
yarn test:run

E2E Tests (Playwright)

E2E tests live in e2e/ and run against the web app. They require E2E_CLERK_USER_EMAIL to be set in .env.local (pointing to a test user in your Clerk dev instance).

# Run E2E tests (headless)
yarn e2e

# Interactive UI mode
yarn e2e:ui

# Headed browser
yarn e2e:headed

# Debug mode
yarn e2e:debug

Quality Checks

yarn lint           # ESLint (--max-warnings=0)
yarn type-check     # TypeScript strict mode across all packages
yarn format:check   # Prettier check
yarn format         # Auto-format with Prettier

---

Deployment

Cloudflare Workers (Web)

# Build and deploy to Cloudflare
yarn cf-deploy

This runs opennextjs-cloudflare build && opennextjs-cloudflare deploy for the web app.

Convex Backend

npx convex deploy

CI/CD

GitHub Actions workflow runs on every push:

1. Checks code formatting (Prettier)
2. Runs ESLint
3. Runs TypeScript checks
4. Builds the application
5. Runs tests
6. Deploys to Cloudflare (on main branch)

---

Scripts Reference

All scripts are run from the repo root via Turborepo unless noted otherwise.

Script	Description
yarn dev	Start all dev servers
yarn build	Build all packages and apps
yarn lint	Run ESLint across all packages
yarn type-check	TypeScript check across all packages
yarn format	Format all files with Prettier
yarn format:check	Check formatting without writing
yarn test	Run unit tests in watch mode
yarn test:run	Run unit tests once
yarn cf-deploy	Build and deploy web app to Cloudflare
yarn e2e	Run Playwright E2E tests
yarn seed	Seed the Convex database with sample data
yarn seed:nuke	Wipe and re-seed the database

---

License

This project is private and not licensed for public use.

---

Built with Next.js, Convex, and Cloudflare