Choreo Studio

Choreo Studio is a scrapbook-style operations app for independent dance studios in India: fees, attendance, batches and WhatsApp reminders in one place. Live at choreostudio.live.

Who it's for

Studio owner. Finds the landing page, joins the founding-studios waitlist or opens Studio account, signs in (email or Google), saves studio details, and picks a Choreo Studio subscription plan. Day to day, the owner manages students, guardians, batches, attendance, each student's fee plan, ledger payments, and WhatsApp reminders.

Family. Parents and students don't install anything or create an account. They get a WhatsApp message with a link showing upcoming classes, attendance, charges, payments and balance.

How billing works

There are two separate kinds of money in Choreo Studio:

• Studio subscription (Dodo Payments). The studio pays Choreo Studio for the software: Regular ₹249/month (the starter plan id) and Studio+ ₹479/month (studio), after a free first month that needs no card. The older Growth plan is no longer sold but still works for existing subscribers. Checkout is created by the server function createSubscriptionCheckout in src/lib/billing.functions.ts. The Dodo API key and product IDs never reach the browser, and a studio cannot edit its own plan or billing status.
• Student fees (ledger-only). Choreo Studio records what each student owes and what the studio says it received by cash, UPI or bank transfer. It does not process those payments.

Fee plans are separate from batches. A batch says where a student dances; a fee-plan assignment says what that student owes. Two students in the same batch can pay different amounts, and past ledger charges keep the plan and amount that created them.

Stack

Piece	Role
TanStack Start, React, TypeScript, Vite	Web app and server functions
Supabase	Authentication, application data, and row-level security. Waitlist writes go through validated server functions; owner-only data sits behind authenticated row policies and a separate role table
Vercel	Hosts the web app. Pushes to main deploy automatically to choreostudio.live
Render	Heavy background jobs, such as scheduled WhatsApp reminders and retries
Dodo Payments	Choreo Studio's own studio subscriptions only
Lovable	Visual editor, synced with this repository

Local development

npm install
npm run dev

Checks:

npm run lint
npm run test
npm run build

Environment variables

Copy .env.example to .env.local for local work (it's untracked, so secrets stay out of git). In production, set them in Vercel under Project → Settings → Environment Variables.

Variable	Where it's used
SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY	Server functions
VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY	Browser client (publishable values only)
DODO_PAYMENTS_API_KEY	Server only. Creates checkout sessions
DODO_PAYMENTS_WEBHOOK_KEY	Server only. Verifies the signature on Dodo webhooks
SUPABASE_SERVICE_ROLE_KEY	Server only. Webhook, reminder job and the public family view
RENDER_JOB_SECRET	Server only. Bearer secret the scheduler sends to the reminder job
WHATSAPP_PROVIDER_URL, WHATSAPP_PROVIDER_TOKEN	Server only. The WhatsApp provider the reminder job posts to. Unset means reminders stay queued
DODO_PAYMENTS_ENVIRONMENT	test_mode (default) or live_mode
DODO_PAYMENTS_STARTER_PRODUCT_ID, DODO_PAYMENTS_GROWTH_PRODUCT_ID, DODO_PAYMENTS_STUDIO_PRODUCT_ID	Server only. One Dodo subscription product per plan
PUBLIC_APP_URL	Base URL for the checkout return link, e.g. https://www.choreostudio.live. Falls back to the origin of the incoming request

If a plan's product ID or the API key is missing, choosing that plan shows a "not available for checkout yet" message instead of failing silently. A studio with a live subscription can't start a second checkout; one whose subscription has expired (cancelled, back on the waitlist) can subscribe again.

plan and billing_status only change through the Dodo webhook (below), which writes with the service role. Owners can edit their contact details but never their plan or billing state.

Backend

Everything is a TanStack Start server function (src/lib/*.functions.ts) that loads its logic from src/lib/*.server.ts inside the handler, so no secret reaches the browser bundle. Rules that must never be bypassed (the ledger, attendance, reminders, billing state) live in SQL (drizzle/migrations/0003 to 0006) behind row-level security, and are tested against a real in-process Postgres.

Area	What it does
Directory	Guardians, students, batches with dated rosters, fee plans assigned per student (separate from batch membership)
Ledger	Monthly charges and payments the studio records (cash, UPI, bank). ChoreoStudio never processes student payments. Charges keep the plan and amount that created them; entries are corrected by voiding with a reason, never edited
Attendance	One mark per student per class date, only for students on that batch's roster
Reminders	queueReminders adds a WhatsApp reminder for each due or overdue charge (once per charge per day). The send job delivers them with retries
Family view	Studios create a private link per guardian; the page behind it shows classes, attendance, charges, payments and balance. Only a hash of the link is stored, and it can be revoked
Billing	POST /api/webhooks/dodo turns verified Dodo events into the studio's plan and status

Reminder job

POST /api/jobs/send-reminders sends one batch of due reminders. Schedule it every few minutes (for example a Render cron job) with the header Authorization: Bearer <RENDER_JOB_SECRET>. Failed sends are retried with growing delays and give up after five attempts. If the provider settings are missing the job answers 503 and leaves every reminder queued. Creating the schedule is a deployment step, not part of the code.

Dodo webhook

In the Dodo dashboard add a webhook pointing to https://<your domain>/api/webhooks/dodo with the subscription events, and copy its signing secret into DODO_PAYMENTS_WEBHOOK_KEY. The signature is checked on the raw body before anything is read. Each event is applied once, only if it is newer than the last one applied, and only for the studio's own subscription.

Payment claims and screenshots

A dancer can report a payment from their private link (/family/<token>). A claim changes no balance until the owner confirms it under To verify; confirming runs the same amount-versus-owed gate as any payment, and the owner's own bank or UPI statement, matched by reference number, is the source of truth. A screenshot is optional: it uploads straight to the private claim-screenshots storage bucket (PNG, JPEG or WebP, up to 5 MB, created by migration 0013) through a one-time signed URL, is viewed by the owner through a 60-second signed URL, and is deleted when the claim is decided.

POST /api/jobs/purge-screenshots deletes screenshots of decided claims and of claims left pending for over 30 days. Schedule it daily with the same header as the reminder job (Authorization: Bearer <RENDER_JOB_SECRET>). Have a lawyer review the privacy notice on the family page before real dancers' screenshots are collected.

Database changes

The migrations in drizzle/migrations are additive. Apply 0003 onward (currently to 0013) to the database, then run drizzle/verify/rollout-checks.sql against it: it must return no rows. Apply the migrations before deploying the code that uses them.

Security

• Never commit API keys, webhook secrets or Dodo product IDs. The tracked .env is managed by Lovable and holds only Supabase publishable values; don't add secrets to it. Put secrets in Vercel's environment variables, or in an untracked .env.local locally.
• Never prefix a secret with VITE_; Vite exposes those to the browser.
• This repository is public. If a secret has ever been committed to it, treat it as leaked: rotate it in the provider's dashboard (Supabase, Dodo Payments, WhatsApp provider) and update Vercel, even after deleting it from the code. Git history keeps the old value.
• The repository is connected to Lovable: don't force-push or rewrite published history.

WhatsApp reminders and owner nudges

Reminders you queue in the console are sent by POST /api/jobs/send-reminders; the owner email nudge is POST /api/jobs/owner-nudge. Call both from your scheduler (the reminder job every few minutes, the nudge once a day) with Authorization: Bearer <RENDER_JOB_SECRET>. With nothing configured the console falls back to tap-to-send chats and the jobs send nothing.

WhatsApp (Meta Cloud API). Set WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_ACCESS_TOKEN and optionally WHATSAPP_TEMPLATE_LANGUAGE (default en). Create two approved utility templates, fee_due_reminder and fee_overdue_reminder, whose body uses these variables in order: {{1}} guardian name, {{2}} dancer, {{3}} studio, {{4}} amount, {{5}} month, {{6}} due date. Example body: "Hi {{1}}, a reminder from {{3}}: {{2}}'s fee for {{5}} ({{4}}) is due on {{6}}. Thank you!"

Owner nudge email (Resend). Set RESEND_API_KEY, NUDGE_FROM_EMAIL (a sender Resend has verified) and PUBLIC_APP_URL. The owner is emailed on a due date and every Monday while any dancer is unpaid this month.

Vobiz instead of your own number. Vobiz (a Meta-approved provider) can supply the WhatsApp number, so reminders do not come from a personal phone. Set VOBIZ_AUTH_ID and VOBIZ_AUTH_TOKEN (console.vobiz.ai), VOBIZ_CHANNEL_ID and VOBIZ_WABA_ID. It is used before the Meta settings when all four are present. Submit the same two templates through Vobiz.