# Resuque

> Resuque is an AI-powered resume builder: users create tailored resumes and cover letters, align them to job descriptions, track applications, and export polished PDFs. Users can start free, then upgrade to Pro for premium templates, advanced AI tools, unlimited downloads, and advanced exports. The app is a pnpm + Turborepo monorepo with a single Next.js 16 deployment (marketing site, authenticated dashboard, API routes, and Inngest background jobs) plus shared packages for the resume DSL, Typst rendering, templates, and the database.

Things to remember when writing Resuque code:

- This is **not** a separate frontend/backend split — everything lives in one Next.js app under `src/`. API routes are thin HTTP controllers; business logic belongs in feature services, not route handlers
- **Next.js 16** has breaking changes vs older versions — read `node_modules/next/dist/docs/` before writing App Router code; heed deprecation notices in `AGENTS.md`
- Organize by **feature**, not by file type: `src/features/<feature>/` holds components, screens, `api/`, and `server/` for that domain
- Components never call `fetch` directly — use `src/features/<feature>/api/<feature>.api.ts` (built on `apiFetch` from `src/lib/http.ts`) and TanStack Query hooks in `*.queries.ts`
- All resume/cover-letter content normalizes to the **Resume DSL** in `packages/shared/resume/dsl.ts` — the canonical document shape for editor, analysis, and Typst rendering
- Protected API routes call `requireSession()` from `src/server/lib/require-auth.ts` at the top; validate bodies with Zod schemas from `@resume/shared/schemas/api`
- Async work (exports, uploads, profile build, email, AI batch fixes) goes through **Inngest** events via `sendEvent()` — not inline in request handlers
- Only add code to `packages/` when it is used in **2+ places**; prefer feature-local code over premature abstraction
- Auth is **Better Auth** (email/password + Google OAuth, same-origin cookies) — no separate API URL; `NEXT_PUBLIC_APP_URL` is the single origin
- Free-plan limits and Pro entitlements are enforced server-side in `src/features/account/server/billing/` — never gate premium features client-only. Use “start free” language unless the billing model changes, and avoid absolute free-for-everything claims.

## Docs

- [README](README.md): Setup, stack overview, scripts, and deployment
- [Environment variables](.env.example): Complete env reference for local dev and production
- [AGENTS.md](AGENTS.md): Next.js 16 breaking-changes warning for AI agents
- [Architecture enforcer](.claude/agents/architecture-enforcer.md): Feature-based frontend + route→service→repository backend rules
- [Next.js App Router docs](node_modules/next/dist/docs/01-app/index.md): Local Next.js 16 docs (read before writing routes, layouts, or server components)
- [Resume DSL](packages/shared/resume/dsl.ts): Canonical resume document schema and helpers
- [Shared API schemas](packages/shared/schemas/api.ts): Zod request/response types for API routes
- [Database schema](packages/database/schema/): Drizzle table definitions (auth, resume, trackers, subscription, usage, referral, agent)
- [Template registry](packages/resume-templates/registry.ts): Resume theme definitions mapped to Typst templates

## API

- [API route index](src/app/api/): All HTTP endpoints grouped by domain (`resumes`, `cover-letters`, `profile`, `onboarding`, `uploads`, `stripe`, `agent`, `inngest`, etc.)
- [HTTP client layer](src/lib/http.ts): `apiFetch`, `readApiError`, and download helpers used by feature `*.api.ts` modules
- [Query keys](src/lib/query/keys.ts): Centralized TanStack Query key factory (`qk`)
- [Route error handling](src/server/lib/route.ts): `jsonOk`, `handleRouteError`, and correlation ID helpers
- [Domain errors](packages/shared/errors.ts): `BadRequestError`, `NotFoundError`, `PlanLimitError`, `UpgradeRequiredError`, etc.
- [Inngest client](src/server/inngest/client.ts): Typed event names and `sendEvent()` helper
- [Inngest functions](src/server/inngest/functions/): Background jobs (email, profile build, resume upload, export, preview, analyze/fix)
- [Auth config](src/server/auth.ts): Better Auth instance (Google OAuth, Turnstile captcha, email verification)
- [Env validation](src/server/config/env.ts): Server-side environment variable schema

## Examples

- [Protected API route](src/app/api/resumes/route.ts): Thin handler — `requireSession()`, Zod validation, delegate to service, `jsonOk`/`handleRouteError`
- [Feature service](src/features/resumes/server/resume.service.ts): Business logic layer called by routes and Inngest
- [Feature repository](src/features/resumes/server/resume.repository.ts): Drizzle queries with user-ownership checks
- [Client API module](src/features/resumes/api/resumes.api.ts): Typed fetch functions for the feature
- [React Query hooks](src/features/resumes/api/resumes.queries.ts): Data-fetching hooks that components consume
- [App page (thin)](src/app/(app)/(dashboard)/resumes/page.tsx): Route imports a `*Screen` from `features/*/screens/`
- [Resume upload flow](src/server/inngest/functions/resume-upload.ts): Async upload → parse → profile/resume creation
- [Typst rendering](packages/resume-render-typst/): PDF/SVG compilation from Resume DSL via Typst templates

## Optional

- [Sanity Studio](studio-resuque/README.md): Blog CMS — run with `pnpm dev:studio`
- [PostHog integration skill](.claude/skills/integration-nextjs-app-router/SKILL.md): Analytics patterns for this App Router setup
- [Feature flags SDK](.agents/skills/flags-sdk/SKILL.md): Vercel Edge Config feature toggles
- [Mastra agent](src/mastra/): Workspace AI agent with human-in-the-loop approval for resume/cover-letter edits
- [Public marketing tools](src/features/public-resume-match/): ATS checker, resume review, and job-match tools (rate-limited, no auth required)
- [Billing & entitlements](src/features/account/server/billing/): Stripe checkout, webhooks, plan limits, daily AI usage metering
- [Onboarding flow](src/features/onboarding/): First-run wizard with resume upload and profile build
- [Job tracker](src/features/trackers/): Kanban-style application pipeline with contacts and notes
- [Tailoring sessions](src/features/tailoring/): Job-specific resume edits with diff review and apply
- [CI pipeline](.github/workflows/ci.yml): Lint, typecheck, test, and build on PRs and `main`
- [Better Auth docs](https://www.better-auth.com/docs): External reference for auth configuration and plugins
- [Drizzle ORM docs](https://orm.drizzle.team/docs/overview): External reference for schema and query patterns
- [Inngest docs](https://www.inngest.com/docs): External reference for background job functions and events