First Fitting is a workspace for costume designers. You record a garment you actually sourced (seller, price, link, photo), preview it on a consenting performer's photo through YouCam AI Clothes V4, and get a named person's approval on that exact revision. Publishing then updates every scene that look appears in, so the costume plot, dressing cards and sourcing list stay in step.
Two rules shape the product:
- A preview is an AI visual preview, not proof of physical fit, fabric or exact colour. Every generated image is shown next to its source photo and the original product image, with that label.
- Approval is a human action on one revision. It never publishes on its own and never orders anything.
There's no hosted instance. To use or work on First Fitting, run it on your own machine as described below. It runs fully offline in demo mode, and you only need a YouCam API key for real try-on previews.
You need Node 24, pnpm 10, and PostgreSQL 16 running on localhost:5432.
pnpm install
pnpm exec playwright install chromium # used by the worker to render PDFs, and by the E2E tests
cp .env.example .env
# Fill BETTER_AUTH_SECRET and MEDIA_SIGNING_SECRET with `openssl rand -base64 36` (one each)
createdb firstfitting_dev
pnpm db:migrate
pnpm db:seed # labelled demo accounts and two illustrated sample productions
pnpm dev # web on http://localhost:3200 plus the background workerSign in at http://localhost:3200/auth/sign-in. The demo accounts panel fills in the form. All three demo accounts use the password first-fitting-demo:
| Account | Role |
|---|---|
| designer@demo.firstfitting.app | Owner and lead designer, can open /admin |
| director@demo.firstfitting.app | Director, approves looks in the sign-off sample |
| wardrobe@demo.firstfitting.app | Wardrobe viewer who can update purchasing |
pnpm db:reset drops all data and reseeds.
Out of the box VTO_MODE=demo. Previews come from a local simulator, are watermarked "Demo simulation — not a YouCam result", and are labelled as simulated everywhere they appear. To run real previews, set VTO_MODE=live and YOUCAM_API_KEY. Each preview then uses YouCam account units.
Emails (magic links, invitations) are captured at http://localhost:3200/dev/outbox instead of being sent. Set EMAIL_TRANSPORT=smtp and SMTP_URL to deliver them.
- Productions and people: email and password or magic-link sign-in, productions with an approval policy (lead designer may approve, or a separate approver is required), invitations, and roles (owner, designer, approver, viewer) enforced on the server.
- Cast and scenes: performers with recorded consent and private photos, characters, a scene running order with drag reordering, and who appears in each scene.
- Sourcing and budget: garments with seller, link, price in minor units per currency, image rights, purchasing state (candidate, shortlisted, cleared to buy, ordered, acquired, fitted, returned or rejected) and its history. Budgets keep currencies separate unless a conversion rate is recorded, and each physical item counts once however many scenes use it.
- Studio: preview one garment on a performer photo, compare with a slider or toggle, accept a preview as the design direction, submit for review.
- Looks and reviews: immutable submitted revisions, approve or request changes, stale-review checks, public review links for guests, and publishing with an impact preview. Scenes follow the latest approved revision unless they're pinned, and "change this scene only" branches a look.
- Paperwork: costume plot, dressing cards and sourcing list as live views, frozen snapshots, PDF (rendered by the worker) and CSV.
- Privacy and operations: signed, short-lived media URLs that re-check membership on every read, consent revocation that can delete photos and previews, retention, production deletion with a background purge, an audit log, and an admin page for vendor mode, queues, failures and alerts.
Next.js 16 (App Router) and React 19, PostgreSQL with Drizzle, Better Auth, pg-boss for background jobs, sharp for image checks, and Playwright's Chromium for PDFs. See:
- docs/architecture.md: layers, invariants, flows and the decision log.
- docs/design-system.md: the visual language.
- docs/integrations/youcam-clothes-v4.md: the vendor contract and how failures are classified.
- docs/api/: request and response shapes.
- docs/deployment.md: notes for self-hosting on Railway or any Docker host, if you want to.
- docs/test-evidence.md: what has been tested and what still needs live credentials.
| Command | Does |
|---|---|
pnpm dev |
Web on port 3200 plus the worker |
pnpm typecheck / pnpm lint |
TypeScript and ESLint |
pnpm test |
Unit and integration tests (integration uses a real firstfitting_test database) |
pnpm test:e2e |
Playwright against a production build on port 3100 with its own firstfitting_e2e database. Run pnpm build first |
pnpm mock:youcam |
A local server that follows the YouCam V4 contract, for testing live mode without spending units |
pnpm db:generate --name=<what> |
New migration from schema changes |
Issues and pull requests are welcome. Read CLAUDE.md for the conventions the codebase follows, and run pnpm typecheck && pnpm lint && pnpm test before opening a PR.