Jovie

# Jovie

A modern artist profile and link-in-bio platform built with Next.js, Clerk authentication, Neon PostgreSQL, and Drizzle ORM.

[![CI](https://github.com/JovieInc/Jovie/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JovieInc/Jovie/actions/workflows/ci.yml?query=branch%3Amain)
[![CodeQL](https://github.com/JovieInc/Jovie/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/JovieInc/Jovie/actions/workflows/codeql.yml?query=branch%3Amain)
[![Security](https://github.com/JovieInc/Jovie/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/JovieInc/Jovie/actions/workflows/security.yml?query=branch%3Amain)

## Security & trust

Jovie tracks OpenSSF security posture in-repository and is working toward an OpenSSF Best Practices badge.

- Best Practices plan: `docs/security/OPENSSF_BEST_PRACTICES.md`
- Badge submission checklist: `docs/security/CII_BADGE_SUBMISSION_CHECKLIST.md`
- Vulnerability reporting: `SECURITY.md`

> Maintainers: once bestpractices.dev enrollment is complete, add the issued badge URL and project ID here.

## Tech Stack

Jovie uses a modern, secure stack designed for scalability, type safety, and exceptional developer experience:

### Core Framework
- **Next.js 16** - React framework with App Router, Server Components, and Server Actions
- **React 19** - Latest React with concurrent features
- **TypeScript 5** - Type-safe development across the entire stack
- **Turborepo 2.8** - Monorepo build system with intelligent caching, shared worktree cache, and `turbo docs` CLI

### Authentication & Security
- **Clerk 7** - Complete user management with social login, MFA, and webhooks
- **Doppler** - Centralized secrets management with audit logging (see [docs/DOPPLER_SETUP.md](docs/DOPPLER_SETUP.md))

### Database & ORM
- **Neon PostgreSQL** - Serverless Postgres with branching and autoscaling
- **Drizzle ORM 0.45** - Type-safe SQL with edge runtime support
- **Connection Pooling** - @neondatabase/serverless with optimized pooling

### Payments & Billing
- **Stripe** - Payment processing with subscriptions and webhooks
- **RevenueCat** - Cross-platform subscription management (mobile)

### Feature Flags & Experiments
- **Statsig** - Server-side feature flags and A/B tests
  - `@statsig/statsig-node-core` - Server SDK used by `apps/web/lib/flags/statsig.ts`
  - `flags` - App flag registry and bootstrap payloads for client consumers

### Error Tracking & Monitoring
- **Sentry 10** - Error tracking, performance monitoring, and session replay
- **Vercel Analytics** - Web vitals and performance metrics

### UI & Styling
- **Tailwind CSS 4** - Utility-first CSS with JIT compiler
- **Radix UI** - Accessible, unstyled component primitives
- **Headless UI** - Accessible UI components
- **next-themes** - Theme management (dark/light mode)
- **Biome** - Fast linter and formatter (replaces ESLint + Prettier)

### Testing
- **Vitest** - Fast unit testing with Vite
- **Playwright** - End-to-end testing with browser automation
- **@testing-library/react** - React component testing utilities

### Infrastructure & Deployment
- **Vercel** - Hosting and edge functions with automatic previews
- **GitHub Actions** - CI/CD with automated testing and deployment
- **Neon Branching** - Database branch per PR for isolated testing

### Media & Assets
- **Cloudinary** - Image and video hosting with transformations
- **Vercel Blob Storage** - File storage for user uploads

## Key Features

- 🎵 **Artist Profiles** - Customizable profile pages with themes and branding
- 🔗 **Link-in-Bio** - Centralized link hub with click tracking
- 💸 **Tipping & Payments** - Integrated Stripe payments with subscription support
- 📊 **Analytics Dashboard** - Real-time creator analytics
- 🔐 **Row Level Security** - Database-level security with Clerk JWT integration
- 📱 **Mobile Optimized** - Responsive design with touch-friendly UI
- ⚡ **Edge Performance** - Server-side rendering with edge optimization
- 🌙 **Dark Mode** - System-aware theme switching
- 🎭 **Feature Flags** - Gradual rollouts with Statsig

## Getting Started

### Prerequisites

- **Node.js 24.21.0+** (24.x only)
- **pnpm 9.15.9** (exact, via Corepack)
- **ripgrep (`rg`)** for local agent and search tooling
- **Doppler CLI** (secrets management) - [Install Guide](docs/DOPPLER_SETUP.md)
- **Accounts Required:**
  - [Neon](https://neon.tech/) - PostgreSQL database
  - [Clerk](https://clerk.com/) - Authentication
  - [Stripe](https://stripe.com/) - Payments
  - [Doppler](https://doppler.com/) - Secrets management
  - [Statsig](https://statsig.com/) - Feature flags and experiments (optional)
  - [Sentry](https://sentry.io/) - Error tracking (optional)

### Installation

1. **Clone the repository**

   ```bash
   git clone https://github.com/JovieInc/Jovie.git
   cd Jovie
   ```

2. **Bootstrap the workspace**

   ```bash
   ./scripts/setup.sh
   ```

   This verifies the required Node/pnpm/ripgrep tooling, installs dependencies when package manifests changed, and checks Doppler access.
   On supported macOS and Debian/Ubuntu systems it will attempt to install `ripgrep` automatically. If auto-install is unavailable, use:

   ```bash
   brew install ripgrep  # macOS
   sudo apt-get install -y ripgrep  # Ubuntu/Debian
   ```

### Internal Quickstart

From the repo root, use the root wrappers for the canonical internal workflow:

```bash
pnpm run db:web:migrate
pnpm run dev:web:fast
pnpm run benchmark:dev
pnpm run test:web
pnpm run dev:web:browse
```

`pnpm run dev:web:fast` is the daily coding loop. It pins Doppler to `jovie-web/dev`, enables the local test-auth bypass, disables local Sentry initialization unless `JOVIE_ENABLE_LOCAL_SENTRY=1`, uses `PORT=3100` by default, and prewarms `/`, `/app`, and `/api/health/build-info` after the server is ready.

Useful local speed toggles:

```bash
JOVIE_DEV_RESET_NEXT_CACHE=1 ./scripts/setup.sh
JOVIE_DEV_SYNC_CLERK_IDS=1 ./scripts/setup.sh
JOVIE_ENABLE_LOCAL_SENTRY=1 pnpm run dev:web:fast
JOVIE_DEV_RESET_NEXT_CACHE=1 pnpm run benchmark:dev
```

For authenticated local browser QA, open the dashboard-ready persona:

```text
/api/dev/test-auth/enter?persona=creator-ready&redirect=/app/dashboard/earnings
```

3. **Set up Doppler (Recommended)**

   Follow the [Doppler setup guide](docs/DOPPLER_SETUP.md):

   ```bash
   # Install Doppler CLI
   brew install dopplerhq/cli/doppler  # macOS

   # Authenticate
   doppler login

   # Configure project
   doppler setup --project jovie-web --config dev
   ```

4. **Manual Environment Setup (Non-Canonical Fallback)**

   Internal team and agent workflows should use Doppler plus the root wrapper commands above. Only use a manual `.env.local` flow if you explicitly need to run outside the standard internal setup:

   ```bash
   cp .env.example .env.local
   # Edit .env.local with your credentials
   ```

5. **Run database migrations**

   ```bash
   pnpm run db:web:migrate
   ```

6. **Start the development server**

   ```bash
   pnpm run dev:web:fast
   ```

   Open [http://localhost:3100](http://localhost:3100) in your browser.

## Development

### Monorepo Structure

```text
Jovie/
├── apps/
│   ├── web/              # Main Next.js application
│   └── should-i-make/    # Side project
├── packages/
│   └── ui/               # Shared UI components
├── drizzle/
│   ├── migrations/       # Database migrations (append-only)
│   └── migrations/_journal.json
└── docs/                 # Documentation
```

### Database Management

```bash
# Check schema matches database
pnpm --filter=@jovie/web run drizzle:check

# Generate migrations from schema changes
pnpm --filter=@jovie/web run drizzle:generate

# Run migrations on main branch
pnpm run db:web:migrate

# Open Drizzle Studio (database GUI)
pnpm run db:web:studio

# Note: Migrations are APPEND-ONLY - never modify existing migrations
```

### Testing

```bash
# Web app test suite with pinned Doppler scope
pnpm run test:web

# Changed web tests for quick local iteration
pnpm run test:web:changed

# Web smoke suite
pnpm run test:web:smoke

# Web E2E suite
pnpm run test:web:e2e

# Workspace-wide fast unit tests
pnpm test:fast
```

### Code Quality

```bash
# Fast web typecheck for local iteration
pnpm run typecheck:web:fast

# Type checking
pnpm typecheck

# Linting (Biome)
pnpm lint
pnpm lint:fix

# Code formatting (Biome)
pnpm format
pnpm format:check

# Tailwind CSS check
pnpm tailwind:check

# Dev server ready, first-route compile, and warm-route timing
pnpm run benchmark:dev
```

### Turborepo

```bash
# Search Turborepo docs from terminal (2.8+)
turbo docs "task configuration"

# Run only affected packages with local-read/remote-read Turbo cache policy
pnpm run build -- --affected
pnpm run test -- --affected

# Verify local remote-cache reads
pnpm run turbo:verify-cache

# Preview task execution plan without running
pnpm run build -- --dry

# Reduce memory pressure for tests (OOM fix)
pnpm run test -- --concurrency=1
```

### Parallel Development with Worktrees

Git worktrees enable parallel agent work with shared Turbo cache (2.8+):

```bash
# Create a worktree for parallel work
git worktree add ../Jovie-agent-1 -b agent/task-name
cd ../Jovie-agent-1 && ./scripts/setup.sh

# Work normally with the local remote-cache read policy
pnpm run build

# Clean up
git worktree remove ../Jovie-agent-1
```

### CI/CD

The project uses **trunk-based development**:

- **Main Branch** → deploys directly to production (`jov.ie`)
- **PR Checks** - Fast validation (typecheck, lint) - ~30 seconds
- **Post-Merge** - Full CI (build, tests, E2E) then deploy
- **Canary Gate** - Health check before deployment success
- **Smoke Tests** - Production validation after deploy

See [.github/workflows/README.md](.github/workflows/README.md) for workflow details.

## Environment Variables

### Using Doppler (Recommended)

All secrets are managed in Doppler with automatic sync to Vercel and GitHub Actions.

**Environments:**
- `d