Personas
The product is built for four personas: three external (Member, Coach, Studio Owner) and one internal (Platform Admin). Membership role enum is the source of truth — see libs/db/src/lib/schema/enums.ts: membershipRole (owner | admin | coach | member). “Platform Admin” is not a membership role; it’s a FitKit-employee role enforced through the apps/admin console.
Studio Owner and Coach often overlap in small operators — Danny-style PTs are simultaneously owner and coach. Roles are per-membership, not per-user, so the same user can be a member at gym A and an owner at gym B.
Member (gym client)
Membership role: member. Schema: libs/db/src/lib/schema/memberships.ts, libs/db/src/lib/schema/member-profiles.ts.
Profile
Adult fitness consumer: trains 2–5 times a week, follows a program (group classes or 1:1 coaching), pays a monthly subscription or class pack. In Israel, defaults to communicating on WhatsApp and prefers paying with Bit / credit card / horaot keva.
Jobs to be done
| Job | How FitKit serves it today | Feature folder |
|---|---|---|
| Find a place to train | Studio minisite + lead capture | features/minisites/, features/leads-crm/ |
| Buy a plan or class pack | Public purchase flow, Israeli payment gateways | features/payments/, features/subscriptions-plans/ |
| Sign waivers and health declarations | Forms engine (FIT-176/158) — Hebrew signed PDFs | features/forms/ |
| Book / cancel classes | Schedule + bookings; waitlist + auto-promote | features/scheduling-bookings/ |
| Get programmed workouts | Daily programming feed; assigned workouts in coaching grid | features/daily-programming/, features/workout-assignments/ |
| Log results + PRs | Workout result entry; goal tracking | features/workout-results/, features/goals/ |
| Track progress | Body metrics, progress photos | features/body-metrics/, features/progress-photos/ |
| Talk to coach | 1:1 messages; class/workout comments | features/messages-comments/ |
| Stay paid | Subscription auto-renew; debt management; cancellation flow | features/payments/, features/subscriptions-plans/ |
Day in the life
- Morning: PWA push notification (“Workout assigned: Wednesday strength”). Opens app, scans the workout, sees coach video for new movement.
- Midday: Books the 18:00 class from
/he/schedule. Already-booked sessions render with a check; full sessions go on a waitlist. - Evening: Arrives, coach scans QR check-in. After the session, member logs their score from the member workout view. Coach gets a fist-bump notification.
- Sunday: Subscription renewal charges via Cardcom. Member gets an email receipt and (when push prefs allow it) a push notification.
Key screens
/[lang]/home— member home / dashboard./[lang]/schedule— week view, book/cancel./[lang]/program— assigned workouts (when in a coaching program)./[lang]/profile— body metrics, goals, history, progress photos./[lang]/shop— class packs / drop-ins.
What blocks them today
- Forms validation gap — signed PDFs work end-to-end but field-level validation lives in the form template, not in the renderer; some edge inputs (date pickers, multi-select) need polish.
- WhatsApp — currently no WhatsApp notifications; everything is email or web push. The Twilio middleware integration is on the near-term roadmap.
- Native mobile — PWA only. iOS push has limits compared to a real native client.
Spotter (AI coach) integration
Spotter Phase 1 is coach-only (see features/spotter-agent/). Members do not see it yet. Phase 2 brings a member-facing assistant for FAQ (“what time is open gym tomorrow?”, “what’s my current PR for back squat?”).
Coach (trainer / instructor)
Membership role: coach. Often also owner in small operators (Danny persona).
Profile
Working trainer at a studio or independent coach. Owns the relationship with 10–80 members. Cares about programming quality, attendance, retention, member progress. Doesn’t want to deal with billing or admin but has to.
Jobs to be done
| Job | How FitKit serves it | Feature folder |
|---|---|---|
| Build programs / workouts | Workout builder, program templates, library | features/workouts/, features/program-templates/ |
| Post daily WOD | Daily programming surface | features/daily-programming/ |
| Assign workouts to members | Coaching grid (cells with assignments) | features/workout-assignments/ |
| Track classes they teach | Schedule, sessions, check-ins | features/scheduling-bookings/ |
| Review member progress | Member profile, body metrics, PRs, history | features/body-metrics/, features/workout-results/ |
| Send check-in forms | Forms engine — recurring check-ins (FIT-183) | features/forms/ |
| Message members | 1:1 messages, workout comments, announcements | features/messages-comments/, features/announcements/ |
| Use AI to draft programs | Spotter (Phase 1, coach-only) | features/spotter-agent/ |
Day in the life
- Morning: Reviews coaching grid for the week — drags last week’s pattern forward, edits one member’s load down because they reported soreness.
- Class time: Marks attendance, leaves a comment on a member’s clean & jerk video.
- Afternoon: Asks Spotter to draft a 4-week strength block for a new member; reviews and applies it as a program-template.
- Evening: Sees a check-in form came back with concerning answers (“low energy 7 days in a row”) — opens a 1:1 thread.
Key screens
/[lang]/dashboard/workouts— workout library + builder./[lang]/dashboard/coaching-grid— per-member assignment grid./[lang]/dashboard/programs— program templates./[lang]/dashboard/schedule— sessions they teach./[lang]/dashboard/members/[id]— member profile./[lang]/dashboard/forms— check-in templates and instances.
What blocks them today
- Coaching grid scale. Works well for 20–30 members; large rosters need virtualization improvements.
- Spotter rate limits. Tier-based (
apps/api/src/ai/agent/rate-limit.service.ts); coaches on Pro can hit the daily ceiling on heavy days. - No mobile-native coach app. PWA works; many coaches want a real iOS app at the gym floor.
Studio Owner / Admin
Membership role: owner (one per org) and admin (delegated). Schema: libs/db/src/lib/schema/organizations.ts, libs/db/src/lib/schema/memberships.ts.
Profile
Runs the business. Cares about ARPU, churn, capacity utilization, debt collection, staff payroll, compliance. Will move studios off Arbox only if FitKit demonstrably saves time and money in the first month.
Jobs to be done
| Job | How FitKit serves it | Feature folder |
|---|---|---|
| Onboard the org | Onboarding flow (org → legal acceptance → first members) | features/onboarding/ |
| Build plans + pricing | Plans + pricing config (subscription, class pack, drop-in, course) | features/subscriptions-plans/ |
| Invite staff and members | Invitations (Clerk-backed) | features/users-auth/ |
| Configure payments | Payment provider configs (Cardcom, Morning, iCredit, etc.) | features/payments/ |
| Import from Arbox | CSV / Arbox importer | features/exports-imports/ |
| Manage leads | Lead pipeline (minisite + manual) | features/leads-crm/ |
| Build minisite | Minisite editor + publish | features/minisites/ |
| Run schedule | Class types, sessions, bulk session actions, location config | features/class-types/, features/scheduling-bookings/, features/locations/ |
| Watch the business | Dashboard overview, insights widgets | features/analytics/, features/insights/ |
| Collect debt | Debt status on memberships; cancellation review tasks | features/payments/, features/memberships/ |
| Stay compliant | Compliance forms — Hebrew signed PDFs (Israeli Sports Promotion Law, FIT-158) | features/forms/, features/legal/ |
Day in the life
- Morning: Opens dashboard overview. Three new lead notifications from the minisite; two members past-due; one cancellation request to review.
- Mid-morning: Approves a member-initiated immediate-cancel-with-refund (Cardcom auto-refund, no manual task needed).
- Afternoon: New class type for “Open Gym Saturday” — 10 instances published in one bulk action.
- End of day: Reviews coach activity, exports a CSV of members for an SMS campaign.
Key screens
/[lang]/dashboard/overview— KPIs, getting-started checklist (new orgs)./[lang]/dashboard/members— full roster./[lang]/dashboard/plans— pricing config./[lang]/dashboard/payments— transactions, debt, payouts./[lang]/dashboard/leads— pipeline./[lang]/dashboard/minisite— public page editor./[lang]/dashboard/settings— org config, payment providers, integrations.
What blocks them today
- No analytics dashboard v1. Insights widgets exist; full reporting (cohort, churn forecast) is on the near-term roadmap.
- No audit log surfaced in UI. FIT-20 — audit log table exists (
auditLogsinlibs/db/src/lib/schema/admin.ts) but the UI isn’t wired up. Trust-signal gap for new paying customers. - WhatsApp campaigns. Not yet — owner has to export and use an external tool.
- Manual Arbox migration. Importer exists; full Arbox migration tool with mapping UI is later.
Platform Admin (FitKit team)
Not a membership role. Lives in apps/admin (Vite/React, Clerk-protected, internal). API surface is under apps/api/src/admin/.
Profile
You. Support, billing reconciliation, incident triage, manual data fixes, platform observability.
Jobs to be done
| Job | How served | Where it lives |
|---|---|---|
| Look up an org or user | Admin org/user explorer | apps/admin/src/pages/ |
| Change a platform tier | Admin tier-management endpoint | apps/api/src/admin/ + apps/api/src/platform-tiers/ |
| Reconcile a Cardcom payment | Payment investigation tools | apps/admin/, apps/api/src/payments/ |
| Watch system health | Bull-Board, Sentry, PostHog | apps/api/src/bull-board/, observability stack |
| Manually retry a failed billing cycle | Test/admin endpoint | apps/api/src/admin/ |
| Audit access | audit_logs table (FIT-20 — table only, no full UI yet) | libs/db/src/lib/schema/admin.ts |
Key tools
apps/admin— internal-only admin UI (not deployed to customer domains).apps/api/src/bull-board/— BullMQ job dashboard (gated).- Sentry dashboards (one project per app — see
architecture/observability.md). - PostHog dashboards — funnel + cost dashboards.
- Drizzle Studio (
pnpm db:studio) for direct DB inspection when needed.
What blocks them today
- Audit log surfacing. Schema exists; admin UI for browsing it isn’t built. Highest-impact next admin work.
- Cross-org reporting. Admin cost/usage dashboards exist (Neon, Railway, PostHog integrations) but per-org observability is shallow.
- Impersonation. No first-class “log in as customer” flow — currently relies on Clerk dashboard tooling.
Spotter integration per persona (current state)
| Persona | Spotter access | Notes |
|---|---|---|
| Member | None | Phase 2 will add a member-facing assistant |
| Coach | Yes (Phase 1) | Tier-gated; uses aiConversations etc. in libs/db/src/lib/schema/agent.ts |
| Owner/Admin | Yes (Phase 1) | Same access as Coach today |
| Platform Admin | Read-only observability | Per-turn cost, cache hit ratio surfaced via PostHog |