Creatora: AI Creator Marketplace
Creatora is a social marketplace where AI filmmakers, animators and generative artists show their work and get hired by brands and agencies.
- Creators publish portfolios that show the AI tools, models and workflow behind every piece.
- Brands write structured briefs, sometimes drafted by AI from a single sentence. They find creators with precise filters, swipe through ranked matches, shortlist, and hire by negotiating terms in chat and accepting the creator's final proposal.
All data comes from Supabase and every action persists. New accounts start completely empty.
Also in this repo: DATA_MODEL.md (submission data-model note) · DEMO_SCRIPT.md (3-minute demo path)
Recent changes
2026-10-24: Cosmic theme, app-open transitions and the scroll-story landing
Visual-only change: no routes, data, permissions, database or flows changed. After the change, test:rls passes 103/103, test:hiring 49/49 and test:workspace 97/97, plus 25/25 UI checks: scrolling, View Transitions, sheets, accessibility, reduced motion and no light-mode remnants. This supersedes the astral theme below.
- One cosmic theme. Light mode is removed: next-themes, the theme toggle, light tokens and
dark: variants are all gone, and the page sets color-scheme: dark.
- Tokens come from the landing reference: warm ink
#12100d, warm starlight text and an amber star #fdb828, with faint indigo, violet and teal nebula tints.
- Text stays ≥ 5.4:1 on every surface. The chart palette was re-validated on the new surfaces.
- Glass material:
- All glass gets grain, a brighter top hairline and an inner highlight.
- Nav rail, bottom bar, admin nav, menus and popovers also get a gradient hairline ring (
.glass-surface).
- Browsers without
backdrop-filter get an opaque fallback.
- Active indicators glide between items, and the top bar gains glass as you scroll.
- App-open transitions: clicking a nav item, card or list row grows the new page out of the pressed element (scale, opacity, blur-to-sharp and a rounded clip, ~420 ms spring).
- It uses React
<ViewTransition> where the browser supports View Transitions, and a Framer spring otherwise.
- It is entry-only and never delays navigation. It doesn't run on refresh or URL filter changes.
- Dialogs grow from their trigger on larger screens and become bottom sheets on phones.
- Sky: one canvas per page for the starfield (slow scroll parallax) and small, rare shooting stars (every 6–14 s).
- Intensity: landing rich, auth medium, app low, admin still and sparse with no shooting stars.
- Animation starts only after the page has loaded and the browser is idle.
- Landing page: the reference HTML's scroll story, ported to typed React modules (
src/components/landing/story/). It is client-only and code-split, with a no-shift server placeholder.
- Orb (shell, inner network, rings) → low-poly creator bust, skills ring, workflow arrows, brief → ranked creators, proof layers, rights checks.
- Two new scenes: Verified people and companies and Fund, deliver, release (test-mode escrow).
- CTA wired to sign-up, sign-in and the demo accounts. Live stats come from
/api/public-stats, followed by a footer.
- Lenis was removed. The page keeps the reference's own eased scroll progress.
- Story improvements:
- preallocated buffers instead of per-frame allocation
- adaptive quality (fewer shell and mesh edges, particles, hatching and shadow blur when frames slow down, and on phones)
- DPR cap per quality level, debounced resize, pause when offscreen or the tab is hidden
- cached DOM writes, with arrow geometry read before any write
- Story accessibility: reduced motion shows static chapter snapshots, there's a visually hidden text version, a "Skip to sign up" link and keyboard chapter dots.
- Story layout fixes: captions, the scroll hint and cards no longer collide on phones, short screens or ultrawide screens.
- Settings → Effects: Full / Reduced / Off, saved in the browser and capped by OS reduced motion.
- One motion config: spring and duration tokens live in
src/lib/motion.ts, with matching CSS linear() springs in globals.css.
2026-10-24: Astral theme and a scroll-driven landing page (superseded by the cosmic theme above)
Visual-only change: no routes, data, permissions, database or flows were touched (test:rls 103/103, test:hiring 49/49, test:workspace 97/97 after the change).
- Astral theme. The default theme is now Night: indigo-ink surfaces, hairline starlight borders, nebula washes and a drifting starfield, with amber as the single "star glow" accent. Paper (light) is the quiet version of the same design. Display type is Inter 600 with tight tracking, and the Bricolage font was dropped (−41 KiB of fonts).
- Effects layer (
src/components/astral/): starfield and constellation canvases, glow cards, magnetic buttons, scroll reveals, parallax, a scroll-progress bar, the constellation loader, Lenis smooth scrolling (landing only) and route transitions. Its successor is documented in Design system / cosmic theme.
- Intensity by area: rich on the landing page, medium on auth and onboarding, low in the creator/brand app, and minimal (still) in admin.
- Settings → Appearance: Theme (Night / Paper / System) and Effects (Full / Reduced / Off), saved per browser. OS reduced-motion caps effects at Reduced.
- Landing page rebuilt as a scroll story:
- hero with an interactive creator/brand constellation
- pinned 6-step "How it works"
- six feature chapters, each with an animated geometric illustration and a preview built from the real components (score breakdown, trust badges, project stepper, escrow chips)
- a constellation of real creators (
search_creators)
- trust section
- live counters from
public_stats (with skeleton, retry and fallback)
- final CTA, section anchors and a scroll-progress bar
- Primitives restyled once, inherited everywhere:
- glass, buttons, pill CTAs, chips, tabs, switches, inputs
- dialogs, menus and popovers get a soft depth entrance; toasts are restyled too
- skeletons shimmer, the infinite-scroll loader is a constellation, empty states carry a constellation mark
- nav rail and mobile bar get the glow; creator, campaign and project cards light up on hover
- charts get a faint glow line, with the chart palette re-validated on the new surfaces
- Accessibility fixes: the body background no longer hides the backdrop. The new
--amber-ink token gives amber text AA contrast on paper (4.6:1), where it was 1.8:1 before.
2026-10-24: Account verification overhaul (phone OTP, ID, company verification, brand types)
Migration 0026_identity_company_verification.sql (expand step, safe with the previous app). Rollback: supabase/rollback/0026_down.sql, captured from production. Contract step 0027_drop_tool_workflow_verification.sql (applied once nothing read them) deletes the old tool / workflow verification rows and drops verifications.tool_id / post_id. The rows are kept in private.verifications_retired_0027, which clients can't read. Rollback: supabase/rollback/0027_down.sql.
- Removed: AI Tool and Workflow verification. Badges, the request UI, admin queue items, ranking input ("Verified on…"), seed data and the request type are all gone. New requests are refused in the database. Kept: past-work verification and Creative Review's AI checks.
- Phone OTP (creators and brands):
POST /api/verification/phone/start and /check.
- 6-digit code stored hashed, 5-minute expiry, 5 attempts, 30-second resend cooldown.
- Hourly limits per user, per number and per IP; numbers normalised to E.164.
- One number = one account:
verified_phones.phone_hash is unique (peppered HMAC), and the number is AES-GCM encrypted for admin display.
- Twilio Verify is used when configured; otherwise demo mode shows the code in the UI ("Demo OTP, no SMS sent").
- ID verification (eKYC) for creators and individual recruiters:
POST /api/verification/identity.
- The ID number is stored as a peppered hash plus its last 4 characters. Date of birth and the ID image are in restricted storage: the private
identity-documents bucket has no client policies.
- Admins view the image only through
/api/admin/verifications/identity/:id/image (60-second signed URL, every view audit-logged). Images are deleted ID_RETENTION_DAYS after the decision.
- Statuses: not_started → pending → verified | rejected (with reason). 3 attempts. A notification goes out on every change.
- Mock government-ID API:
POST /api/mock-identity/verify. Its own service with an API key, JSON, latency and rate limit. It knows ~10 fictional identities (mock_identity_records) and answers only "Identity Verified" / "Identity Not Verified". The result is advisory ("Simulated check, not a government verification"); the admin's decision is final. No real government API is ever called.
- Brand types: signup asks Individual Recruiter or Company / Organization (
brand_details.brand_type), then routes brands to /verification.
- Gating: a new brand can draft but can't publish or hire until verified. This is enforced by a trigger on briefs going active and in the hire RPC (
brand_can_operate), controlled by app_settings.brand_verification_gating.
- Existing brands are grandfathered (
verification_required = false) and see a banner asking them to choose a type and verify. Demo brands are verified companies.
Demo mode (judges):
- Verify a phone: the code appears on screen.
- Use a sample ID from the banner (e.g. Maya Okafor · DEMO-100008 · 1997-12-09).
- As
[email protected], open Verifications to review it.
- For companies, use a demo domain (
northpeak.example). Find official contacts returns the demo directory; send the invitation and open the copyable link to approve.
Privacy / retention:
- Phones and ID numbers are never stored in clear (peppered hashes; phones also encrypted).
- ID images are private and deleted after
ID_RETENTION_DAYS (default 30) through the opportunistic purge or /api/cron/purge-identity, scheduled daily by Vercel Cron (vercel.json, authorised with CRON_SECRET). Migration 0028_identity_purge_reliability.sql (rollback supabase/rollback/0028_down.sql): a row is marked purged only once the image is gone from storage, and only once, so retries and overlapping runs are safe. The cron route returns exact counts, and 500 when anything wasn't purged; failures are audit-logged with the verification id only and retried on the next run. npm run report:id-orphans lists stored images with no verification row (report-only, deletes nothing).
- Sensitive fields are never logged.
- Users read only their own status.
2026-10-24: Clean files only after the payment is released; no "Create brief" for admins
Download-gating rule. A brand gets the clean (un-watermarked) original only if all three hold, checked on the server for every request:
- It owns the campaign.
- The version is approved.
escrow.status = 'released'.
Before that, the brand only gets watermarked previews. Released is final; a refund, dispute or cancellation can only happen before it, so any other escrow state keeps the files locked.
- The only way to a clean file is
GET /api/submissions/:id/files/:fileId/original (route).
- It returns a 60-second signed URL, or
403 with "Clean files unlock after the payment is released". The creator can always download their own upload.
- The link expires in a minute, so a leaked URL stops working almost immediately.
- Migration
0025_clean_files_after_release.sql:
- The
submissions (originals) bucket has no client read policy at all, for brand, creator or admin. Only submission-previews stays readable by the two parties.
can_access_originals now requires released; it was funded or released.submission_files.storage_path is no longer readable by clients (column grant), and submission_json no longer returns it.
- UI: before release the brand sees a disabled "Unlocks after payment is released" button.
- Updated in
version-card.tsx, project-view.tsx, payment-card.tsx, status.tsx, the Creative Review page and the submit form.
- The draft-file delete route reads the original's path with the service role.
- Licence record: issued by
release_escrow only, so it already follows the same rule.
- Admin "Create brief" removed:
- The profile page renders the briefs section only for brand profiles, so admins no longer get "New brief" or "Create a brief" (
u/[username]/page.tsx).
/campaigns shows its create actions only to brands./api/ai/brief now accepts brands only.- Brief creation was already brand-only on the server: the
campaigns insert policy, /campaigns/new and /brand/* pages, and /api/studio/*. Admin moderation pages are unchanged.
- Tests:
test:workspace covers the route and direct storage before and after release, other brands and creators, and that no path appears in project data.- covers admins being unable to create briefs or use the brief builder.
2026-10-24: Accept → Hire → Fund, no revisions / invites, AI Creator Finder
Migrations (rules enforced in RPCs, triggers and RLS), applied in two steps:
0023_accept_hire_funding_ai_finder.sql is the expand step. It is safe while the previous app is still serving: the old "final proposal" buttons get a "refresh the page" message.0024_accept_hire_funding_cleanup.sql is the contract step, applied after the new app is live. It drops the legacy RPCs, strips stored "revisions", and quietly moves unfunded hires to awaiting_funding.- Rollback:
supabase/rollback/0023_0024_down.sql (generated from the 0022 schema). It keeps every project, payment, proposal and message, and drops only the AI Finder tables.
Accepted offer = agreement → Hire.
- When one side accepts the other's latest offer, the server records an accepted, versioned proposal from it.
- The brand immediately gets a primary Hire button in the chat, on the pinned card and on the accepted offer.
- The "creator sends a final proposal" step is gone (
send_final_proposal and reject_proposal were removed).
- A new offer after acceptance voids the agreement.
hire_creator(p_proposal) still requires an accepted agreement and takes the price from it.
Hire → Fund project.
- A hire starts as
awaiting_funding, and the brand lands on Fund project, a simulated payment sheet labelled "Demo, no real money" that funds the existing demo escrow (unfunded → funded, shown as "Pending funding").
- Until it's funded, the creator sees "Waiting for the brand to fund" and can't start or submit. The brand can't assign tasks, and the creator isn't counted as a collaborator or added to the group chat.
- This is enforced by
create_submission, a submissions insert trigger, create_campaign_task, is_campaign_collaborator, campaign_stats and sync_campaign_group.
- Funding moves the project to
in_progress, notifies the creator, and makes them a collaborator; the group chat rule for 2+ creators still applies.
- The brand gets a notification plus a persistent banner, sees the hire under "Awaiting funding" in the collaborators panel, and can Cancel hire (nothing was paid, so there is no refund).
- The rest is unchanged: submission → review → approval → release → clean download → certificate.
- Existing hires that were never funded move to
awaiting_funding (0024). They also leave the campaign group chat quietly until funded.
Removed.
- "Revisions" is gone from offer terms (form, cards, validation, stored terms). Creative Review's Request revision is untouched.
- Invite is gone (
invite_creator RPC, the Studio button, the service). Message and Shortlist cover it, and old invite notifications now read "shared the brief with you".
AI Creator Finder (brand Discover page, "Find with AI").
- Gemini extracts requirements from the idea, using the brief builder's lookup vocabulary.
- The idea is embedded (
gemini-embedding-2, 768 dimensions).
run_ai_match ranks all available creators in SQL: semantic similarity (pgvector) + tools/skills/style/content type/specialization overlap + experience and completed projects + availability. Weights live in src/config/ai-match.ts.- The top results are stored and paginated. The 0-100 Match score is relevance, not a talent rating.
More details:
- Why this creator? is generated only on click, from that creator's real evidence (
ai_match_evidence), and cached in ai_match_reasons.
- Embeddings: creators get vectors in
creator_embeddings, never exposed to clients. Profile, attribute and portfolio changes mark them stale through triggers. Stale ones are re-embedded in the background after searches and creator saves (/api/ai/embeddings); backfill with npm run ai:embeddings.
- Fallbacks: if parsing or embeddings fail, ranking falls back to tags and keywords with a notice.
- Limits and history: searches are persisted (
ai_match_searches, ai_match_results, with Save per result), reopenable as recent searches, and rate-limited per brand in the database (15 per 10 minutes). Jobs are logged in ai_job_logs.
- Config:
GEMINI_API_KEY, already used. AI_FINDER_SEND_CREATOR_DATA=true is required before any creator profile or portfolio text is sent to Gemini (embeddings, "Why this creator?"). Off by default: the finder still works, ranked by tags and keywords. GEMINI_EMBEDDING_MODEL is optional (default gemini-embedding-2; creator vectors always use this one model, and queries fall back to gemini-embedding-001). The pgvector extension is enabled by the migration.
New: tables creator_embeddings, ai_match_searches, ai_match_results, ai_match_reasons; routes /api/ai/match, /api/ai/match/[searchId]/reason, /api/ai/embeddings; components discovery/ai-finder.tsx; scripts npm run ai:embeddings, npm run test:ai-finder.
2026-10-23: Negotiated hiring, published-only shortlists, creator targets, collaborators
Migration: supabase/migrations/0022_negotiated_hiring_collaborators.sql. Every rule below is enforced in the database (RPCs, triggers, RLS), not only in the UI.
Hiring (no more direct hires).
- Hire opens (or creates) the brand ↔ creator conversation for that brief. A pinned card shows the brief summary, the creator's proposed price and the terms status (open → negotiating → agreed → final proposal sent → hired). Nobody is hired yet.
- Both sides negotiate with structured offers: price, deliverables, deadline, revisions and usage rights, with Accept / Counter buttons, alongside normal text. Terms are agreed when one side accepts the other's latest offer.
- The creator then sends a final proposal. It is a new version built server-side from the agreed offer, and older versions become
superseded.
- The brand clicks Accept & hire. Only then does
hire_creator(p_proposal) run, with the proposal's price and terms; the client never sends a price. It opens the same internal demo escrow as before (funded after approval, the brand releases payment).
The old hire_creator(campaign, creator, amount, currency) now always refuses. A new offer re-opens agreed terms and supersedes a waiting proposal. Each step notifies the other side (notification type proposal). Existing hires were backfilled as accepted v1 proposals. Legacy hires that never had a fee agree one the same way, and accepting the proposal opens their escrow.
Shortlists need a published (active) brief: a trigger plus the insert policy. Draft, completed or closed briefs block new shortlists, and the UI disables the button with "Publish the brief first" and a Publish brief shortcut. Existing shortlists stay; ones added while a brief was still a draft are flagged (campaign_shortlists.added_while_draft). Swipe Save bookmarks are unaffected.
Creator count is a target, not a cap. It ranges from 1 to 100, and brands can hire beyond it ("6 of 5 hired", Add more creators). Editing can't lower it below the creators already hired (trigger campaigns_target_floor). One reusable Stepper (src/components/ui/stepper.tsx) edits it in the brief form, the Studio and the sprint form: [−] [number] [+], typed input that commits on blur/Enter, and arrow / Page / Home / End keys.
Swipe is its own item in the brand navigation (desktop rail and mobile bar). It is the same /swipe page that Discover and briefs link to.
Collaborators.
- Each brief card on the brand dashboard shows "N Collaborator(s)". N counts hired creators that aren't cancelled or rejected, from the
campaign_stats view.
- Clicking it opens a panel with members, status, chats, the group chat and tasks.
- When a second creator is hired, one group conversation per brief is created automatically (
conversations.type = 'group'). Later hires join it and removed creators leave, each with a system message.
- Tasks (
campaign_tasks): the brand assigns a task to one creator (posted in their brief chat) or to the whole group (posted in the group chat). Creators see their tasks on their project page and can update the status. RLS limits visibility to the brand and the assigned or hired creators.
New tables: proposals, campaign_tasks. New columns: conversations.type and conversations.campaign_id; messages.payload (messages.kind is the message type: user = text, system, offer, proposal, task); campaign_shortlists.added_while_draft.
New RPCs: start_negotiation, send_offer, accept_offer, send_final_proposal, reject_proposal, hire_creator(p_proposal), get_negotiation, get_conversation, get_campaign_collaborators, create_campaign_task, update_campaign_task_status, delete_campaign_task.
New components: chat/negotiation.tsx, workspace/hire-button.tsx (replaces the hire dialog), workspace/collaborators.tsx, campaign/shortlist-gate.tsx, ui/stepper.tsx. New test: npm run test:hiring.
Features
| Area | What works |
|---|
| Creator profiles & AI portfolios | Social header with real follower, following, pieces and likes counts. Follow, Contact and Edit profile. Specialisations, tools (with proficiency), skills, content types, styles, languages, platforms, rates, workflow overview and past brand work. Portfolio pieces are uploaded to Storage or pasted as links (YouTube, Vimeo, Instagram, TikTok, Behance). Each piece records tools, an ordered workflow pipeline, workflow notes, content type, style, aspect ratio and commercial-use clearance. A post modal shows likes, comments and save. |
| Verification (bonus) | Phone OTP (one number per account), ID verification reviewed by the trust team (with a simulated ID check), company verification confirmed by an official contact, and verified past work. Badges: Phone Verified, Identity Verified, Verified Company. Every badge explains what was checked and how. Creators request verification; admins review the requests, and each decision is audit-logged and notifies the creator. |
| Discovery & filtering | Debounced Postgres search across names, bios, posts, tools, skills and categories. Combinable multi-select filters: tools, skills, specialisation, content type, style, experience, availability, language and verified-only. Filters sync to the URL. Results show a count, can be sorted three ways and load with infinite scroll. When nothing matches, the empty state names each filter that is costing results ("removing it shows 4 creators"), offers one-click removal, and lists related creators. |
| Briefs & campaigns | Structured brief: content type, style, category, aspect ratios (including custom), platforms, audience, tools, skills, languages, budget, deadline and creators needed. Commercial-use terms: usage rights, territory, duration, exclusivity, licence type and AI-disclosure requirement. Statuses run draft → active → completed, and pipeline counts are computed live. |
| AI brief builder (bonus) | One sentence goes to a server-side Gemini call. The response must follow a JSON schema whose enums come from the live lookup tables. Zod validates the output, and the server maps names to IDs. The result pre-fills the form for review. Assumptions the AI made are listed. Without a key, or if the call fails, the user gets a clear message and the manual form. |
| Explainable matching | Each brief ranks creators with a 0–100 relevance score. Weights: tools 25, portfolio relevance 25, skills 20, campaign experience 10, platform/audience fit 10, availability 10. Every match shows a per-factor breakdown and a "Why this creator?" line. |
Design is the single dark cosmic theme (see Design system / cosmic theme). It keeps the glass panels, single amber accent, pill CTAs with an amber arrow, floating icon rail with bottom tabs on mobile and notched stat tiles, all on a warm night-sky backdrop with a starfield and rare shooting stars. Every screen has skeleton, empty, error-with-retry and toast states. Likes, saves and follows update optimistically.
1. Install
Requirements: Node 20+ (tested on 22) and a Supabase Cloud project.
npm install
2. Configure Supabase
- Create a project at supabase.com.
- Auth → URL configuration. Supabase only redirects to allow-listed URLs and otherwise falls back to the Site URL.
- Site URL: your production URL, e.g.
https://creatora-ai-psi.vercel.app.
- Redirect URLs:
https://<your-domain>/auth/callback, https://<your-domain>/auth/confirm, and for local development http://localhost:3000/auth/callback and http://localhost:3000/auth/confirm.
- Recommended: under Email Templates → Confirm signup, change the link to
{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email&next=/onboarding
so the link works on any device. The default link uses PKCE and only signs the user in automatically in the browser they signed up with.
- Auth → Providers → Email. Email + password is enabled by default.
- With Confirm email on, sign-up shows "check your inbox".
- With it off, users go straight to onboarding. That's convenient for demos.
- Storage buckets and Realtime publications are created by the migrations; no manual steps are needed.
3. Environment variables
Copy .env.example to .env.local and fill it in. Never commit .env.local.
| Variable | Where it's used | Exposure |
|---|
SUPABASE_URL | Browser + server | Public. Mapped to the browser in next.config.ts |
SUPABASE_PUBLISHABLE_KEY | Browser + server | Public. RLS protects all data |
SUPABASE_SECRET_KEY | /api/admin, seed and test scripts | Server only. Imported only in server-only modules |
SUPABASE_DB_URL | npm run db:migrate, db:types | Scripts only (Dashboard → Connect → Session pooler) |
GEMINI_API_KEY | /api/ai/brief | Server only, optional |
AI_FINDER_SEND_CREATOR_DATA | AI Creator Finder, npm run ai:embeddings | Server only. true allows sending creator profile + portfolio text to Gemini. Default off |
GEMINI_EMBEDDING_MODEL | AI Creator Finder | Optional, default gemini-embedding-2 |
GEMINI_MODEL | /api/ai/brief | Optional, default gemini-3.5-flash (falls back to 3.1-flash-lite → 3.5-flash-lite on retirement, overload or timeout) |
SUPABASE_JWKS_URL, SITE_URL | Reserved / docs | Optional |
IDENTITY_SECRET | Phone / ID-number hashes, phone encryption, invitation tokens | Server only. Optional (derived from SUPABASE_SECRET_KEY if unset). Set it before rotating the Supabase key, or existing hashes can't be matched |
OTP_MODE, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_VERIFY_SERVICE_SID | Phone OTP | Optional. Without Twilio (or with OTP_MODE=demo) codes are shown in the UI ("Demo OTP, no SMS sent") |
DEFAULT_PHONE_COUNTRY_CODE | Phone OTP | Optional, default (for numbers typed without a country code) |
4. Run migrations
npm run db:migrate # applies supabase/migrations/*.sql in order, once each
npm run db:migrate -- --dry-run # run pending migrations, then roll back
npm run db:migrate -- --to 0023_accept_hire_funding_ai_finder.sql # staged rollout: stop after this file
npm run db:types # optional: regenerates src/types/database.ts from the live schema
Applied migrations are tracked in private.schema_migrations. Each file runs in its own transaction and waits at most 5 s for table locks, so it fails fast instead of blocking traffic.
Newer Supabase projects don't auto-grant table privileges to the API roles. 0011_api_grants.sql sets them explicitly: clients read through RLS and write only specific tables and columns; the service role has full access.
5. Seed the 10 demo accounts
npm run seed # idempotent: safe to run again
The seed creates real Auth users through the Auth admin API. Each login works with the shared password below.
Password for all demo accounts: CreatoraDemo#2026
Dashboard history: each demo creator gets 90 days of generated views and profile visits (weekly rhythm, one viral spike, one dip), tagged source = 'seed'. Real likes, saves and follows between demo accounts are spread across the same window. Follower counts stay small because they are real follow rows between the 10 demo accounts. Most audience groups show "Not enough data yet", because no group reaches the 5-person privacy threshold.
Demo content: 29 portfolio posts with tool and workflow metadata, 7 briefs (draft, active and completed), applications, shortlists, selections, follows, likes, comments, saves, swipe signals, 4 conversations, verification records and a sample report.
- Media: royalty-free stock (Unsplash images, cropped to each post's aspect ratio and copied into Supabase Storage; Mixkit clips for videos). It stands in for AI-generated work.
- Isolation: every seeded row belongs to the 10 demo users and uses deterministic IDs. Re-running only upserts, and never touches anyone else's data. New sign-ups get a fresh UUID and an empty profile.
6. Run locally
npm run dev # http://localhost:3000
7. Build and checks
npm run typecheck && npm run lint && npm run build
npm run test:rls # permission + integrity checks against your Supabase project (needs seed)
npm run test:workspace # brand workspace acceptance flow against a running app (APP_URL, default localhost:3000)
npm run test:hiring # accept → hire → fund, shortlist rule, creator targets, group chat + tasks (throwaway accounts)
npm run test:ai-finder # AI Creator Finder routes, ranking, cached reasons, fallback, RLS (running app)
npm run test:verification # phone OTP, ID + mock check + admin decision, company invitation, gating, RLS (running app, demo modes)
npm run test:purge # ID-image retention purge: boundary, failures + retries, concurrency, cron secret, orphans (test project + local app only; needs CRON_SECRET)
npm run ai:embeddings # build / refresh creator embeddings for the AI Creator Finder
test:workspace uses throwaway accounts and deletes them afterwards. It covers:
- submit → watermarked preview + AI review → revision → v2 → approve
- fund → originals stay locked → release → originals unlock (server route only) → licence PDF + public verification → receipt + earnings
- sprint deadline enforcement
- cross-user access being refused
Run npm run seed to also seed the workspace demo states:
- brand guidelines
- a Studio draft
- a live sprint
- a submission awaiting review
- a revision request
- completed, paid projects with licence records
test:rls runs about 50 checks. They cover:
- demo logins
- a brand-new user starting empty
- role escalation, self-verification and fake counters being blocked
- private messages, notifications and applications staying private
- triggers updating counts and generating notifications
- realtime-backed messaging between participants only
- the discovery and ranking RPCs returning data
8. Deploy (Vercel)
- Push the repo to GitHub and import it in Vercel. The framework preset is detected as Next.js and no
vercel.json is needed.
- Add these environment variables in Vercel for Production and Preview:
SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY, GEMINI_API_KEY (optional), GEMINI_MODEL (optional).
SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY are inlined at build time, so they must be set before the build.
- In Supabase Auth, add
https://<your-domain>/auth/callback to the redirect URLs and set the Site URL.
- Run migrations and the seed from your machine against the production project. Don't run them from Vercel.
Design system / cosmic theme
One dark theme: a warm night sky behind the content, never in front of it. Effects are decorative only (aria-hidden, pointer-events: none, behind the page at -z-10), and the content always wins.
Tokens (src/app/globals.css, :root only)
| Token | Value | Used for |
|---|
--bg, --bg-2, --card | #12100d, #17140f, #1d1914 | Page, raised surfaces |
--ink, --ink-2, --ink-3 | #f4efe6, #c8bfb1, #a39885 | Text: AA everywhere (--ink-3 ≥ 5.4:1 even on glass over stars) |
--amber, --amber-2, --amber-ink, --on-amber | #fdb828, #e9a514, #fdb828, #1a1408 | The one accent ("the star"), its text use, text on it |
--glow, --glow-rgb | amber at 40% / 253,184,40 | Halos on key actions and active indicators, canvas highlights |
--glass, --glass-strong, --glass-fallback | warm translucent fills | Glass material, plus an opaque fallback without backdrop-filter |
--glass-border, --glass-border-hi, --glass-hi, --grain | warm hairlines, inner highlight, SVG noise | The glass texture |
--nebula-1..3 | indigo, violet, teal at 6–13% | Backdrop tints |
--star-rgb | 244,240,232 | Starlight (canvas) |
--chart-1..3, --chart-glow | validated on #1d1914 and #12100d | Charts |
--dur-open, --spring-open, --spring-glide, --ease-out | 420 ms, CSS linear() springs | CSS mirror of the motion config |
Utilities: .glass / .glass-strong (the material), .glass-surface (adds the gradient hairline ring; nav and menus only, not scrollable containers), .display, .eyebrow, .star-text, .glow-hover, .press (haptic press), .shimmer, .sheet / .pop / .fade (overlay entrances), .fx-motion / .fx-only-full / .fx-decor (effects-aware).
Motion config (src/lib/motion.ts)
SPRING.open (app-open, ~420 ms with slight overshoot), SPRING.glide (indicators), SPRING.press, SPRING.gentle (reveals, magnetic, tilt), plus DURATION, EASE_OUT and OPEN (start scale, clip radius, blur). The CSS linear() curves in globals.css are generated from the same stiffness, damping and mass, so View Transitions and Framer animations match.
Components (src/components/cosmic/)
| File | What it does |
|---|
effects.tsx | EffectsProvider, useEffects() (pref, effective level, setPref), useFinePointerFx(), EFFECTS_SCRIPT (sets <html data-effects> before first paint) |
canvas-loop.ts | Shared canvas driver: DPR cap, ResizeObserver, theme colours, rAF with an fps cap. Pauses when hidden or offscreen, and starts animating only after load and idle |
starfield-canvas.tsx | StarfieldCanvas: twinkling, drifting stars with scroll and pointer parallax and optional shooting stars, all on one canvas |
shooting-stars.ts | createShootingStars(): the small, rare meteor painter the starfield calls |
atmosphere.tsx | Atmosphere: fixed backdrop (nebula tints + sky canvas + still orbit line-art) and SKY, the per-area intensity table |
app-open.tsx | AppOpenTracker (records the pressed link or control) and PageTransition (route templates: <ViewTransition enter="app-open"> or a Framer spring fallback). Also exports pressOrigin() for dialogs |
interactive.tsx | GlowCard, MagneticButton, GlowButton (magnetic + halo, key actions only), ScrollReveal |
ornaments.tsx | OrbitLines, ConstellationMark (empty states), ConstellationLoader |
use-scrolled.ts | Scroll-linked headers (top bar and landing nav gain glass) |
appearance-settings.tsx | Settings → Effects card |
Tuning intensity
Edit SKY in src/components/cosmic/atmosphere.tsx; the area comes from the route (skyArea()):
| Area | Routes | Default |
|---|
landing | / | dense, twinkling, pointer + scroll parallax, shooting stars every 6–12 s, 60 fps |
auth | /login, /signup, /onboarding, /auth/*, /verify* | medium, shooting stars every 7–14 s, 30 fps |
app | creator + brand app | sparse, dim, slow scroll parallax, faint shooting stars every 8–14 s, 30 fps |
admin | /admin/* | very sparse and still: no animation, no shooting stars |
Effects setting
- Settings → Effects stores
creatora-effects = full | reduced | off in localStorage (per browser, nothing in the database).
- The effective level is capped by
prefers-reduced-motion.
- An inline script in
src/app/layout.tsx writes it to <html data-effects> before first paint.
- What each level does:
- Full: everything.
- Reduced: still sky, no shooting stars, no grow-from-icon (pages fade), no parallax, tilt or magnetic pull. Framer transforms are off and the landing story shows static chapter snapshots.
- Off: also no canvases or decorative motion.
Landing story modules (src/components/landing/story/)
| File | Role |
|---|
math.ts | Helpers from the reference (cl, sm, sg, win, rotate, persp), a seeded PRNG, colour constants |
geometry.ts | getGeometry(), built once: orb shell, inner network, rings, low-poly bust, portrait lines, hatched planes, mind network |
timeline.ts | SCENES (every scene window), CHAPTERS (dot targets / snapshots), STORY_UNITS, STORY_VH, computeLayout(), computeFrame() |
draw-orb.ts, draw-figure.ts | Canvas drawing with preallocated buffers and a Quality level (0–2) |
overlays.tsx | Scene markup, bindOverlays(), updateOverlays() (cached writes; arrow geometry read before writes) |
engine.ts | runStory(): eased scroll follow, pointer, adaptive quality + DPR cap, debounced resize, pause offscreen or hidden, reduced-motion snapshots, full cleanup |
scroll-story.tsx, story-lazy.tsx | Component and the code-split (ssr: false) loader with a no-shift placeholder |
copy.ts, story-text.tsx | Story copy (honest labels) and the visually hidden text version |
story.css, classes.ts | Story styles, prefixed cs- (the Tailwind Turbopack rule makes every .css global, so CSS modules aren't used) |
To add a scene: add its copy in copy.ts, its markup in overlays.tsx, its window in SCENES (and a CHAPTERS entry), its updates in updateOverlays(), then raise STORY_UNITS / STORY_VH if it needs more scroll.
Scrolling rules
- No smooth-scroll layer anywhere. The landing page uses native scroll plus the story's own eased progress.
- Swipe/reels snap scrollers, chat, dialogs and every nested container scroll natively.
- Chapter dots use native
scrollTo.
Architecture
Browser ──(publishable key + user JWT, RLS)──▶ Supabase Postgres / Storage / Realtime
│
└──▶ Next.js (App Router)
├─ proxy.ts session refresh + auth redirects
├─ server layouts verify session & role (getClaims) before rendering
├─ /api/ai/brief Gemini (server-only key), Zod-validated
├─ /api/admin role re-checked; service-role writes + audit log
└─ /api/link-preview allow-listed oEmbed lookups (no open proxy)
- Authorization in two layers.
- Postgres RLS on every table. Column-level grants stop users writing role, verification, suspension or counters.
- Server checks in layouts and route handlers.
- Business logic lives in SQL. Search, diagnostics, ranking, swipe deck, feed, opportunities, inbox, dashboards and admin lists are Postgres functions (
supabase/migrations/0006_rpcs.sql, 0010_read_rpcs.sql). They return ready-to-render JSON, and the scoring is transparent and inspectable.
- Hiring is a negotiation, enforced in SQL (
0022, 0023). Offers, the agreement (an accepted offer becomes an accepted proposal) and the hire are security-definer RPCs that check who may act and when. Clients can't insert hires, proposals or structured messages, and the hire price always comes from the agreement. A hire waits in awaiting_funding until the brand funds the demo escrow.
- AI Creator Finder:
/api/ai/match → Gemini (requirements) + embedding → run_ai_match (SQL over pgvector + tags) → stored, paginated results. Reasons are generated lazily and cached. Creator vectors are refreshed by triggers plus background jobs.
- Conversations are a plain DM per pair (
dm_key "a:b"), one 1:1 chat per brief and pair for hiring (dm_key "c:campaign:a:b"), and one group per brief (type = 'group'). Project updates for a hire are posted in its brief chat. Group membership follows campaign_creators through a trigger.
- Counts and notifications are triggers (
0005_functions_triggers.sql). They're never computed or stored by the client.
- Data access goes through
src/services/*, one file per domain. Components never query directly. The same service functions run with the browser client (TanStack Query) or the server client.
Where to change what
| I want to… | Edit |
|---|
| Add a tool, skill, style, platform or language | supabase/migrations/0009_lookup_data.sql (or insert rows). The UI loads lookups dynamically. |
| Change matching weights or reasons | rank_creators_for_campaign in 0006_rpcs.sql |
| Tune the home feed | get_feed in 0006_rpcs.sql |
| Change search behaviour or filters | creator_search_flags / search_creators (SQL), src/services/discovery.ts, src/components/discovery/* |
| Change brief fields | 0003_campaigns.sql → src/lib/validation/schemas.ts (campaignSchema) → src/components/campaign/campaign-form.tsx |
| Change the AI brief prompt or schema | src/lib/ai/brief-builder.ts |
| Add a notification type | 0004 check constraint (latest version in 0022) + trigger in 0005 + text and links in src/services/notifications.ts |
| Change the hiring negotiation (offer terms, who may act, states) | Latest RPC versions in 0023_accept_hire_funding_ai_finder.sql (send_offer, accept_offer, hire_creator, private.clean_terms) → src/services/messaging.ts → src/components/chat/negotiation.tsx |
| Funding rules (what's blocked until funded) | fund_escrow, is_campaign_collaborator, tg_submissions_require_funding in 0023; UI in workspace/payment-card.tsx ("Fund project") and project-view.tsx |
| AI Creator Finder weights / limits | src/config/ai-match.ts (weights, semantic calibration, page size, rate limits, embedding model) |
| AI Creator Finder logic | run_ai_match / ai_match_evidence in 0023, src/lib/ai/creator-finder.ts (requirements, reasons), src/lib/ai/embeddings.ts, src/components/discovery/ai-finder.tsx |
| Change who can shortlist / the creator target rules |
Project layout
src/
app/ (auth) login/signup · (onboarding) · (app) creator+brand screens · (admin) · api/
components/ cosmic/ (theme effects) landing/ (story/) ui/ layout/ profile/ posts/ discovery/ campaign/ swipe/ chat/ feed/ notifications/ admin/
features/ session context
services/ data access (profiles, posts, social, discovery, campaigns, messaging, notifications, verification, admin)
lib/ supabase/ (browser, server, admin, proxy) · ai/ · validation/ · utils/
hooks/ types/ config/
supabase/
migrations/ schema, triggers, RPCs, RLS, storage, lookups
seed/ idempotent demo seed (npm run seed)
scripts/ migrate · gen-types · test-rls · test-workspace · test-hiring
Security notes
- The secret key and Gemini key are read only in modules marked
server-only and in local scripts. They never use a NEXT_PUBLIC_ prefix, and they're never sent to the browser.
- Users can't self-assign
admin. The signup trigger maps any other value to creator.
- Uploads go only to
<user-id>/… in public buckets, with MIME type and size limits.
link-preview only fetches from allow-listed oEmbed providers.- If keys were ever shared in plain text, rotate them in the Supabase and Google AI dashboards.
