easy-resume: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Vitex is a Typst-based resume generator built with Next.js 16, React 19, and TypeScript 6. The application generates professional Typst code from structured resume data and compiles PDFs locally using Typst. It uses a custom two-column layout built with Typst's grid system for maximum compatibility.

Current stack (verify with package.json before relying on any number here): Next 16.2 (Turbopack builds) · React 19.2 · TypeScript 6.0 · AI SDK ai 7 + @ai-sdk/openai 4 · lucide-react 1.x · Node 24 LTS in Docker · Stripe SDK 20 · FontAwesome 6 (deliberately — see "Dependency & Toolchain Policy").

Positioning — "one core, N thin adapters" / "Career as Code": The target user is a person plus their AI assistant, and the product is designed so every surface (web UI, public v1 REST API, published vitex-cli, stdio MCP server, hosted OAuth MCP connector) is a thin adapter over one shared backend core — "The API is the UI". The framing that unifies the feature set is Career as Code: your career facts are source code (a candidate_profiles row = the repo), each tailored PDF is a reproducible build artifact, the refine chain is a sequence of commits (parent_job_id/root_job_id), outcome billing means you pay per successful build, and the exported .typ source is zero lock-in. This is recorded in ADR 0003.

Common Commands

# Development
npm run dev          # Start Next.js dev server on http://localhost:3000
npm run build        # Build production bundle
npm run start        # Start production server
npm run lint         # `eslint .` (flat config) — NOT `next lint`, removed in Next 16

# Testing
npm test             # Run vitest once (unit tests for the backend core)
npm run test:watch   # Vitest in watch mode

# Database migrations (idempotent, raw SQL — NOT drizzle-kit)
npx tsx scripts/migrate.ts   # Create/upgrade Neon tables; safe to re-run

# Docker / VPS Deployment
# Docker build + GitHub Actions CI/CD deploy to a DigitalOcean VPS.
# Flow: checks -> build-and-push -> migrate (npx tsx scripts/migrate.ts) ->
# health-gated rolling swap. The new container starts alongside the old one with
# the SAME Traefik labels (Traefik round-robins both = zero downtime), and the
# old one is retired only after the new container's HEALTHCHECK (/api/health)
# reports healthy; a failed gate removes the new container and keeps the old one.
# See .github/workflows/deploy.yml and Dockerfile

# Package management
npm install --legacy-peer-deps   # REQUIRED flag at the repo root (see Dependency policy);
                                 # cli/ installs with a plain `npm ci`
npx shadcn add <component>       # Add shadcn/ui components