CEO Quick Start Guide

• Navigate to /login in your browser.
• Enter the email address and password associated with your CEO account.
• Complete two-factor authentication if prompted (SMS or authenticator app).
• You will land on the CEO Overview Dashboard automatically because your account has the ceo role.

The CEO Overview Dashboard at /ceo-dashboard aggregates data from every location in real time. No location filter is applied by default, so you see the entire organization.

The dashboard includes:

• Revenue chart — month-over-month revenue across all locations with drill-down by dojo.
• Enrollment trends — new members, cancellations, and net growth per location.
• Alert panel — failed payments, expiring memberships, and overdue belt promotions.
• Staff quick links — jump to the cross-location staff roster, onboarding wizard, or platform admin.

Navigate to /ceo-dashboard/settings to manage organization-wide configuration. Settings follow a three-tier inheritance model (see Section 16).

The staff management page at /ceo-dashboard/staff shows every staff member across all dojos in a single, filterable table.

• View all staff — see name, role, assigned dojo, last login, and status at a glance. Filter by location or role.
• Change roles — promote or demote staff by selecting a new role from the dropdown. Changes apply immediately and are audit-logged.
• Reset password — send a password reset email to any staff member. The link expires in 24 hours.
• Transfer between dojos — reassign a staff member to a different location. Their permissions carry over; location-specific data (schedules, classes) does not.
• Deactivate / reactivate — suspend a staff account without deleting it. Deactivated accounts cannot log in but preserve historical data.

The subscription panel at /ceo-dashboard/subscription manages the platform-level subscription for your organization and individual location billing status.

• Platform subscription — view your current plan (per-location pricing), billing cycle, and next invoice date.
• Location chargebacks — configure how much each of your dojo locations pays your organization for use of the platform. Choose a charge model per location: flat (fixed monthly fee), per-member (rate × active member count), or custom. Use "Add Location" to set a rate or "Edit" to change an existing one.
• Chargeback invoices — monthly invoices generated from your organization to each location based on its configured rate. Track status (pending, paid, overdue, waived, suspended) and view expected monthly totals across all locations.
• Location suspend/reactivate — temporarily suspend billing for a location (e.g., seasonal closure). Suspended locations remain visible but stop generating chargeback invoices.
• Invoice generation — generate and download PDF invoices for any date range. Invoices include line-item detail per member and payment method breakdowns.
• Payment retry — failed auto-charges follow the retry schedule: 24h, 48h, 72h. After three failures, a $25 late fee is applied and the member is flagged for manual follow-up.

• Click the location dropdown in the top navigation bar (shows "All Locations" by default).
• Select a specific dojo to filter the dashboard, members, and financial data to that location only.
• The selected location is stored as a cookie so it persists across page navigations.
• To return to the cross-location view, select "All Locations" from the dropdown.

After selecting a specific dojo, the dashboard adapts to show location-specific data:

• Member count — active, paused, and cancelled members for this location.
• Revenue breakdown — monthly recurring revenue, one-time payments, and outstanding balances.
• Today's schedule — classes scheduled for today with instructor assignments and enrollment counts.
• Recent check-ins — live feed of member check-ins at this dojo's kiosk.
• Quick actions — add a member, create a class, process a payment, or view the schedule.

• Navigate to /members — because you are signed in as CEO, Row Level Security automatically returns every member across all locations (not just one dojo).
• Use the search bar to find members by name, email, phone, or member ID.
• Filter by location, membership status (active, paused, cancelled), belt rank, or program.
• Click any member row to view their full profile, billing history, attendance log, and belt progression.

The Expiring Memberships widget on the CEO Overview at /ceo-dashboard surfaces memberships approaching expiration. There is no separate renewals page — drill into any specific member from the widget to take action.

• Expiring memberships widget — shows members whose plans expire in the next 7, 14, or 30 days. Grouped by location.
• Renewal types — auto-renew (card on file charged automatically), manual renewal (member must take action), or lapsed (no renewal configured).
• Notification schedule — automated emails/SMS sent at 30 days, 14 days, 7 days, and 1 day before expiration. A final "membership expired" notice is sent on the expiration date.
• Bulk actions — select multiple members and send a renewal reminder, extend their membership, or change their plan.

• Revenue overview — total collected, outstanding, and projected revenue across all dojos or filtered by location.
• Transaction log — every payment processed through the Payment Abstraction Layer, with status (settled, pending, failed, refunded).
• Failed payments — a dedicated queue showing members with failed charges, retry status, and days overdue.
• Export — download transaction data as CSV for accounting software import.

Rather than a separate setup page, onboarding runs as an inline checklist widget at the top of your CEO Overview dashboard. It checks what's already configured and only shows the items that still need attention, with a progress bar and "Resume" links that jump to the right settings page.

• Organization Profile — name, logo, primary contact. Jumps to /ceo-dashboard/settings → Branding.
• Payment Setup — Authorize.net credentials for organization chargebacks (separate from each location's processor). Lives under Settings → Payment Processing.
• Communications — email (SendGrid) and SMS (Twilio / Vonage / Telnyx) providers. Test both before going live.
• First Location — opens the "Onboard New Dojo" modal (covered in Section 12).
• Programs & Belt Ranks — set up disciplines and belt progressions at the org level; locations receive location-scoped copies on onboarding.
• Invite Staff — add the first Admin at each location. They receive a password-setup email automatically.

Adding a new dojo is a data-only operation. No code deployment is required.

• From the CEO Overview at /ceo-dashboard, click the "Onboard New Dojo" button. A modal wizard opens.
• Fill in the dojo name, address, timezone, phone number, and operating hours.
• The system creates the locations row and copies Tier 2 defaults (belt ranks, programs, billing settings) from your organization settings.
• Belt ranks are location-scoped copies — the new dojo gets its own set that can be customized independently.
• Create an admin account for the new location as part of the same wizard. The admin receives an email invitation with a setup link.
• The new dojo appears in your location dropdown immediately and begins receiving data.

• Navigate to /belt-progress/grading and click "New Grading Event".
• Enter an event title (e.g. "Spring 2026 Grading") and the event date, then click Create & Edit.
• Inside the event, build one or more grading groups (for staggered sessions on the same day) and add candidates. The system suggests eligible members based on their current rank, days at rank, and classes since last promotion — instructors can add or remove candidates before finalizing.
• For each candidate, set the attempt belt and review prerequisites (days trained, injuries/notes). Generate a printable grading sheet for the committee from the event page.
• When the event is done, click Complete. The system validates that every candidate has been scored and that any grading fees are paid.
• Once completed, all passing candidates are auto-promoted to their attempt belt. Their profile and belt history are updated instantly.

• Membership report — active vs. inactive members over time, churn rate, and growth by location.
• Revenue report — monthly/quarterly/annual revenue by location, plan type, and payment method.
• Attendance report — class attendance rates, peak hours, and no-show patterns.
• Belt progression report — average time-in-rank, promotion rates, and grading outcomes by discipline.
• Staff report — classes taught, members managed, and login activity per staff member.

All reports support date range filtering, location filtering, and CSV/PDF export.

The DMS exports financial data as CSV files that import cleanly into QuickBooks, Xero, FreshBooks, or any accounting software. The export tools live on the Finance → Overview page at /billing, plus a separate financial summary dashboard at /reports/financial.

• Monthly Financial Export card — on /billing, pick a month and year, then choose an export:
  • Transaction Journal (CSV) — every ledger entry for the month, ready to paste into your general ledger.
  • Revenue Summary (CSV) — totals by category: revenue, tax, refunds, processing fees.
  • Email to me — sends both reports to your logged-in email address on demand via the /api/reports/financial-export/email endpoint.
• Financial summary dashboard — at /reports/financial, filter by any date range to see net revenue, charges, credits, and a per-source breakdown. Click Export CSV for the raw ledger over the selected range.

Outbound lead and communication tooling is consolidated under a single Outreach top-level sidebar item at /leads. Inbound replies live one click away in the separate Messages top-level item at /communications/inbox — not inside Outreach, so an unread badge is always visible no matter which page you're on.

The duplicate-detection engine has been rewritten to avoid false positives when family members share contact details. Navigate to /members/duplicates to review pairs.

How the new scoring works:

• Family-linked pairs are excluded entirely — if two members already share a family_id, they're known relatives, not duplicates.
• Date-of-birth conflicts are a hard exclusion — a 7-year-old and a 35-year-old will never be flagged as duplicates, even if they share an email address.
• High-confidence matches require corroboration — same email and same DOB scores 100. Same name and same DOB also scores 100.
• Single-signal matches score low — "shared email only" or "shared phone only" scores 20-25 with a "likely family — review" reason, instead of being flagged as a strong duplicate.

Platform Admin is a separate surface for the platform operator (not the CEO of a single organization). It lives under /platform/* and is gated by the is_platform_admin() check server-side. Primary pages: /platform/dashboard, /platform/tenants (plus /platform/tenants/onboard), /platform/health, /platform/audit, /platform/alerts, /platform/impersonate, /platform/database, /platform/feature-flags, /platform/billing, /platform/ops, and /platform/settings.

The DMS uses a three-tier settings model to balance consistency with per-dojo flexibility.

Tier 1 examples: Authorize.net credentials, SendGrid/Twilio keys, organization branding, CORS and security headers.

Tier 2 examples: Default billing cycle, late fee amount, belt rank templates, program templates, class duration defaults.

Tier 3 examples: Class schedule, instructor assignments, local promotions, dojo-specific announcements, kiosk PIN codes.

The DMS now ships as an installable Android app via a Trusted Web Activity (TWA) wrapper. The app is a thin native shell around the existing PWA, so functionality stays in sync automatically — no separate codebase to maintain.

• Distribution — the APK is published to Google Play under your organization's developer account. Members and staff install it like any other app.
• Offline check-in — the kiosk page works offline inside the TWA wrapper. Check-ins are queued in IndexedDB and synced when connectivity returns.
• Push notifications — the wrapper enables true native push for class reminders, payment alerts, and announcements.
• Auto-updates — because the wrapper points to the live PWA, app content updates immediately when you deploy. Only the wrapper shell needs Play Store submission.
• iOS — iPhone members can still install the PWA via Safari's "Add to Home Screen" for the same experience without a Play Store equivalent.

• Keyboard navigation — every interactive element is reachable via Tab. Focus indicators use a visible purple ring.
• Screen reader support — all images have alt text, all buttons have aria-labels, and dynamic content uses aria-live regions.
• Touch targets — all buttons and interactive elements meet the 44x44px minimum touch target size for mobile devices.
• Form inputs — all inputs use 16px minimum font size to prevent iOS auto-zoom on focus.
• Responsive layout — sidebar navigation on desktop, bottom tab bar on mobile. Data tables collapse to card layouts below 640px.
• Color contrast — all text meets WCAG 2.1 AA contrast ratios (4.5:1 for normal text, 3:1 for large text).
• Lighthouse scores — target gate is 80+ Performance and 90+ Accessibility on mobile.