Appearance
Authority Doc / Public V1 Lifecycle
Workflow states define how CoachMe moves from invite to active coaching, review, pause, end, and retention.
This page is the source of truth for cross-feature lifecycle states and gates in Public V1. Feature pages can add local implementation detail, but they must not invent states or transitions that conflict with this map.
Core Coaching + Nutrition BaselineCoach Web BuildersCoach Mobile ReviewClient Mobile Execution
Note
Public V1 uses coach web as the primary creation surface, coach mobile for review, messaging, task inbox, client context, progress, nutrition review, risk signals, and lightweight actions, and client mobile for daily execution. Full coach mobile builder parity, full Priority view, payments, broad integrations, and comprehensive food provider search remain Post-V1.
Public V1 End-To-End Loop
The canonical happy path proves one paid coaching relationship from setup through execution and review.
1. Coach Setup
Coach registers, creates the workspace, configures baseline settings, and prepares the first client invitation.
Workspace
2. Invite And Register
Client validates an active invitation, registers or logs in with a matching verified contact, and enters onboarding.
Identity
3. Onboard And Review
Client completes or skips the onboarding questionnaire. Coach reviews profile, questionnaire, goals, status, and private notes before assignment.
Readiness
4. Assign
Coach web assigns forms, programs, nutrition guidance, meal plans, supplements, and reminders when gates allow publishing.
Coach Web
5. Execute
Client mobile presents Today tasks, workouts, meals, check-ins, progress prompts, messages, and offline-capable workout logging.
Client Mobile
6. Review And Adjust
Coach reviews adherence, workouts, progress photos, measurements, risk signals, task inbox items, and messages, then manually adjusts coaching plans.
Coach Review
7. Continue Or Exit
The relationship continues, pauses, ends, reactivates, or enters deletion/export handling under privacy and retention policy.
Lifecycle
Whole-Workflow Correlation Boundaries
This map owns canonical workflow starts, terminal outcomes, and hand-offs; API owns identifier issuance and Observability owns propagation and search expectations.
General Rule
- One API-issued
correlationIdfollows retries and steps in the same bounded product workflow. - Later independent workflows receive a new identifier and remain linked by canonical domain ids and receipts.
- The identifier never becomes a permanent coach-client relationship identifier or a W3C trace id.
- Feature authorities name equivalent start/end boundaries for upload, notification, and other multi-step workflows.
Invitation Acceptance Example
The workflow starts when the API begins an acceptance attempt for the presented invitation, before invitation-state and contact validation. An ACTIVE invitation continues through authentication return, account binding, relationship creation, and onboarding-context creation.
Success ends only when the invitation is CONSUMED, the relationship is ONBOARDING, and the onboarding context exists. EXPIRED, REVOKED, and contact mismatch are terminal failure outcomes for that attempt.
Canonical State Machines
These states are the shared lifecycle vocabulary for Public V1. Feature docs may add local rules, but they must preserve these names, transitions, and downstream effects.
CoachWorkspace
The workspace controls whether a coach can operate the platform and invite clients.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
DRAFT | Workspace exists but setup is not ready for active coaching. | ACTIVE, CLOSED | Blocks client invitations, publishing, and coach-facing operational surfaces. |
ACTIVE | Workspace is usable for Public V1 coaching workflows. | SUSPENDED, CLOSED | Allows invitations, onboarding, assignments, review, communication, and progress tracking. |
SUSPENDED | Workspace access is temporarily restricted by operational or policy action. | ACTIVE, CLOSED | Restricts new invites, publishing, and non-essential coach actions while preserving records. |
CLOSED | Workspace is no longer available for active coaching. | Terminal | Retains or anonymizes records according to privacy and retention rules. |
ClientInvitation
Invitations are single-client access paths into registration and onboarding.
Invite validation is not consumption. The invite is consumed only when account binding succeeds and the relationship/onboarding context is created.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
ACTIVE | Invitation can be used by the intended client contact. | EXPIRED, CONSUMED, REVOKED | Allows client registration, login binding, and onboarding start when contact checks pass. |
EXPIRED | Invitation passed its validity window before use. | Terminal; issue a new ACTIVE invite | Blocks registration from that invite and requires coach action. |
CONSUMED | Invitation was accepted and bound to a client account. | Terminal | Prevents reuse and hands control to the relationship and onboarding workflows. |
REVOKED | Coach or system invalidated the invite before acceptance. | Terminal; issue a new ACTIVE invite | Blocks registration and surfaces an invite replacement path to the coach. |
CoachClientRelationship
The relationship state determines whether the coach can manage, review, pause, end, or reactivate client work.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
INVITED | Coach has invited the client, but onboarding has not started. | ONBOARDING, ENDED | Blocks duplicate active coach acceptance and waits for invite completion. |
ONBOARDING | Client is registered and completing required setup and review inputs. | ACTIVE, PAUSED, ENDED, DELETED_OR_ANONYMIZED | Enables onboarding, profile readiness, form collection, and coach review gates. |
ACTIVE | Client is in active coaching and eligible for daily execution. | PAUSED, ENDED, DELETED_OR_ANONYMIZED | Allows assignment, Today projection, reminders, messages, risk signals, and progress review. |
PAUSED | Relationship is intentionally inactive but not ended. | ACTIVE, ENDED, DELETED_OR_ANONYMIZED | Suppresses selected reminders and risk escalation while preserving context. |
ENDED | Coaching relationship is closed for active editing. | ACTIVE through explicit reactivation, DELETED_OR_ANONYMIZED | Removes coach edit access except allowed reactivation, retention, export, or deletion paths. |
DELETED_OR_ANONYMIZED | Relationship data was deleted or anonymized under policy. | Terminal | Removes identifiable coaching context and keeps only permitted audit or aggregate records. |
OnboardingWorkflow
A skipped questionnaire creates COMPLETED_WITH_PENDING_TASK and blocks program/nutrition assignment until submitted or explicitly cancelled.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
NOT_STARTED | Client has not begun onboarding. | IN_PROGRESS, PAUSED, CANCELLED | Blocks profile readiness and assignment publishing. |
IN_PROGRESS | Client is completing onboarding steps and questionnaire inputs. | COMPLETED, COMPLETED_WITH_PENDING_TASK, PAUSED, CANCELLED | Feeds coach review, profile readiness, forms, and onboarding progress surfaces. |
COMPLETED | Required onboarding inputs are complete. | Terminal unless reopened by exception handling | Unlocks coach review and readiness decisions when relationship gates also pass. |
COMPLETED_WITH_PENDING_TASK | Onboarding was accepted with a known pending task, usually a skipped questionnaire. | COMPLETED, CANCELLED | Blocks program and nutrition assignment until the questionnaire is submitted or explicitly cancelled. |
PAUSED | Onboarding is intentionally paused. | IN_PROGRESS, CANCELLED | Preserves progress but blocks readiness and publishing until resumed or cancelled. |
CANCELLED | Onboarding or a pending onboarding task was intentionally cancelled. | Terminal unless a new onboarding run is created | Records the exception and allows downstream gates only where cancellation is explicit and permitted. |
ProfileReadiness
Readiness is the coach-controlled gate between collected profile data and safe assignment publishing.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
NOT_READY | Profile lacks the minimum information for coach review. | READY_FOR_REVIEW, BLOCKED | Blocks programming, nutrition publishing, and readiness-dependent reminders. |
READY_FOR_REVIEW | Profile has enough information for coach assessment. | NEEDS_CLARIFICATION, READY_FOR_PROGRAMMING, BLOCKED | Creates coach review work and allows readiness decision capture. |
NEEDS_CLARIFICATION | Coach needs more information before publishing assignments. | READY_FOR_REVIEW, BLOCKED | Prompts client or coach follow-up and keeps publishing locked. |
READY_FOR_PROGRAMMING | Coach has reviewed the profile and approved assignment work. | READY_FOR_REVIEW, BLOCKED | Unlocks program and nutrition publishing when other gates pass. |
BLOCKED | Known risk, missing consent, or material constraint prevents safe progression. | READY_FOR_REVIEW, NOT_READY | Blocks publishing and raises visible coach follow-up before daily execution continues. |
Assignment
Assignments represent forms, programs, workouts, nutrition guidance, meals, supplements, and reminders.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
DRAFT | Coach-created assignment is not visible to the client. | PUBLISHED, CANCELLED | Has no Today, reminder, adherence, or client-facing effect. |
PUBLISHED | Assignment is released and ready for activation by schedule or start condition. | ACTIVE, SUPERSEDED, CANCELLED | Feeds projection, schedule, and client visibility. |
ACTIVE | Assignment is currently actionable by the client. | PAUSED, SUPERSEDED, CANCELLED, COMPLETED | Creates Today tasks, reminders, adherence facts, and review inputs. |
PAUSED | Assignment is temporarily held without ending it. | ACTIVE, SUPERSEDED, CANCELLED | Suppresses projected tasks and reminders until resumed or replaced. |
SUPERSEDED | A newer assignment or version replaced this one. | Terminal | Preserves historical adherence while moving future projection to the replacement. |
CANCELLED | Assignment was stopped before normal completion. | Terminal | Stops future tasks and records cancellation context for review. |
COMPLETED | Assignment reached its intended completion condition. | Terminal | Feeds adherence, progress, and coach review history. |
DailyTask
Daily tasks are the client-facing execution units generated from assignments and reminders.
Today tasks are projections. Today does not own forms, programs, nutrition plans, progress records, or chat messages.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
PROJECTED | Task is forecast from the plan but not yet available for action. | AVAILABLE, MISSED | Supports Today planning, upcoming schedule, and reminder preparation. |
AVAILABLE | Task is visible and actionable for the client. | IN_PROGRESS, COMPLETED, SKIPPED, MISSED | Drives client mobile actions, reminders, and pending adherence. |
IN_PROGRESS | Client has started the task but has not finalized it. | COMPLETED, SKIPPED, MISSED | Creates resumable execution state and offline sync requirements. |
COMPLETED | Client completed the task and produced an adherence fact. | CORRECTED | Feeds progress analytics, coach review, and risk signals. |
SKIPPED | Client intentionally skipped the task. | CORRECTED | Feeds adherence and risk signals without treating the task as a missed action. |
MISSED | Task window closed without completion or explicit skip. | CORRECTED | Feeds risk signals, review queues, and adherence summaries. |
CORRECTED | Original completion, skip, or miss was amended after the fact. | Terminal for the correction record | Supersedes prior adherence facts while retaining audit context. |
Implementation note (M1)
DailyExecution also persists the canonical workout record behind a workout task. Its states are IN_PROGRESS, COMPLETED, and SKIPPED; COMPLETED and SKIPPED close the record to further sync mutation until a correction path exists. PROJECTED, AVAILABLE, and MISSED remain projection-only states with no persisted record.
Device
Devices are per-installation sync grants scoped to a user account and app surface. Offline Sync Protocol owns registration, receipt, and purge detail.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
ACTIVE | Device is registered to the user account and trusted for sync. | REVOKED | Allows sync push and pull for that installation. |
REVOKED | User or system withdrew the installation's sync grant. | Terminal; register the device again | Blocks sync push and pull in both directions until a fresh registration exists. |
CoachReviewItem
The full Priority view is Post-V1; Public V1 uses task inbox sorting and deterministic risk signals.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
OPEN | Review item needs coach attention. | SNOOZED, IN_REVIEW, RESOLVED, DISMISSED | Appears in coach task inbox ordering and deterministic risk surfaces. |
SNOOZED | Coach intentionally delayed the item until a later time. | OPEN, IN_REVIEW, DISMISSED | Removes immediate pressure while preserving future review visibility. |
IN_REVIEW | Coach has opened or claimed the item for action. | RESOLVED, SNOOZED, DISMISSED | Signals active review without implying a plan change. |
RESOLVED | Coach handled the review item. | Terminal; new signal creates a new OPEN item | Updates task inbox history, analytics context, and client follow-up state where applicable. |
DISMISSED | Coach intentionally closed the item without action. | Terminal; new signal creates a new OPEN item | Removes item from active review while preserving dismissal audit context. |
MessageThread
Thread state controls communication availability and retention handling.
| State | Meaning | Allowed Transitions | Downstream Effects |
|---|---|---|---|
ACTIVE | Coach and client can exchange messages in the thread. | RESTRICTED, RETAINED, PURGED_OR_ANONYMIZED | Enables messages, attachments, voice notes, read receipts, and notifications. |
RESTRICTED | Thread remains visible but sending or attachment actions are limited. | ACTIVE, RETAINED, PURGED_OR_ANONYMIZED | Supports moderation, ended relationships, failed media handling, and policy restrictions. |
RETAINED | Thread is retained for policy, audit, or client history without normal active messaging. | PURGED_OR_ANONYMIZED | Keeps permitted records accessible under privacy and retention rules. |
PURGED_OR_ANONYMIZED | Thread content was deleted or anonymized. | Terminal | Removes identifiable message content while preserving permitted audit metadata. |
Cross-Feature Gates
These gates define the blocking conditions that multiple features must honor before allowing downstream actions.
| Source State | Blocked Action | Unlock Condition | Owner | Consumers |
|---|---|---|---|---|
| Invalid, expired, revoked, or consumed ClientInvitation | Client registration from that invite | New active invite is issued | IdentityAccess | Client login, onboarding |
| Existing ONBOARDING or ACTIVE relationship | Accepting another coach invitation | Current relationship ends | CoachClientManagement | IdentityAccess, onboarding |
| OnboardingWorkflow COMPLETED_WITH_PENDING_TASK | Program and nutrition assignment | Questionnaire submitted or explicitly cancelled | CoachClientManagement | ProgramsAndExercise, Nutrition |
| ProfileReadiness READY_FOR_PROGRAMMING missing | Program and nutrition publishing | Coach marks profile ready after review | CoachClientManagement | ProgramsAndExercise, Nutrition |
| Material profile constraint changed | Silent plan continuation | Coach acknowledges or re-reviews readiness | CoachClientManagement | ProgramsAndExercise, Nutrition, DailyExecution |
| CoachClientRelationship PAUSED | Selected reminders and risk escalation | Relationship returns to ACTIVE | CoachClientManagement | Push, DailyExecution, ProgressAnalytics |
| CoachClientRelationship ENDED | Coach edit access | Reactivation creates allowed active context | CoachClientManagement | All coach surfaces |
| CoachClientRelationship DELETED_OR_ANONYMIZED | Normal product access and coach/client interaction | No normal unlock; export, deletion, or anonymization handling completes under privacy and retention policy | CoachClientManagement with PrivacyAndRetention handoff | All product surfaces |
| Offline operation pending | Accepted completion/adherence fact | Server sync accepts the operation; a rejected or conflicted operation is terminal for that attempt and never produces the fact | DailyExecution | Today, ProgressAnalytics, CoachReview |
| Device REVOKED | Sync push and pull | New device registration | DailyExecution | Client mobile, offline queue |
| Media upload failed | Source action completion if media is required | Upload retry succeeds or source action is cancelled | Communication or owning feature | Forms, Progress, Communication |
Exception Paths
Each exception path names the canonical product response so features handle edge cases consistently.
Expired invite
Block registration from the expired invite, show a replacement path, and require a newly issued ACTIVE invitation.
Revoked invite
Block registration, explain that the invite is no longer valid, and route the client back to the coach for a new invite.
Contact mismatch during invite registration
Stop account binding when the verified contact does not match the invite, then require corrected identity or a new invite.
Skipped questionnaire
Set OnboardingWorkflow to COMPLETED_WITH_PENDING_TASK and block program/nutrition assignment until submitted or explicitly cancelled.
Incomplete or blocked profile
Keep ProfileReadiness away from READY_FOR_PROGRAMMING and prevent publishing until coach review clears the issue.
Coach pauses client
Move the relationship to PAUSED, preserve context, suppress selected reminders, and pause risk escalation until ACTIVE resumes.
Travel, illness, injury, Ramadan, vacation, or equipment unavailable
Capture the constraint, require coach acknowledgement or readiness re-review when material, and avoid silent plan continuation.
Offline pending workout, check-in, or nutrition operation
Keep the operation pending locally and delay accepted completion/adherence facts until server sync accepts it. Offline Sync Protocol owns the pending operation and receipt behavior.
Failed media upload
Keep required-media actions incomplete until retry succeeds or the source action is cancelled by the owning feature. API Contract and Offline Sync own upload-session refresh and retry hand-offs.
Meal swap request awaiting coach action
Keep the request visible in coach review, preserve the current meal plan version, and apply changes only after coach action.
Relationship end
Move CoachClientRelationship to ENDED, remove coach edit access, and apply retention, export, or deletion handling as privacy-and-retention requires.
Reactivation after ended relationship
Create an allowed active context from ENDED only through explicit reactivation and restore gates before publishing resumes.
Account deletion or export request
Route to privacy-and-retention, preserve required audit records, and delete, anonymize, or export permitted data.
Feature Ownership
Each feature owns its canonical records and exposes stable lifecycle facts to the features that consume them.
| Feature | Owns |
|---|---|
| IdentityAccess | authentication provider context and client invitations |
| CoachClientManagement | relationship, onboarding, profile readiness, client status, private notes, offboarding |
| Forms | form templates, assignments, submissions, amendments, submission review |
| ProgramsAndExercise | program templates, published versions, exercise references, workout prescription, workout review inputs |
| DailyExecution | Today projection, workout logs, task completion state, adherence facts, sync receipts |
| Nutrition | targets, meal plan versions, food snapshots, supplement schedules, meal logs, meal swap requests |
| Communication | conversations, messages, attachments, voice notes, read receipts, message retention state |
| ProgressAnalytics | progress entries, measurements, photos, PR history, adherence summaries, deterministic risk inputs |
| Integrations | provider adapters and provider health when implementation starts |
Next Authority Docs
These linked authority docs extend the lifecycle map into permissions, retention, contracts, operations, and release governance.
roles-and-permissions
Defines user roles, permission boundaries, and surface-specific authority checks.
privacy-and-retention
Defines deletion, anonymization, export, retention, and privacy handling.
api-contract-standard
Defines API contract conventions shared by frontend and backend modules.
event-and-outbox-standard
Defines lifecycle events, outbox reliability, and downstream integration behavior.
offline-sync-protocol
Defines offline operations, sync receipts, conflict handling, and retry rules.
environment-runbook
Defines local, staging, and production environment expectations.
toolchain-contract
Defines TypeScript-first tooling, repo standards, and developer workflow constraints.
integration-register
Defines integration ownership, implementation timing, and provider health expectations.
observability-plan
Defines whole-workflow propagation/search expectations plus Launch logs, metrics, errors, dashboards, alerts, and operational visibility; tracing remains Maturity.
Test And Release Gate
Defines required test evidence and release readiness gates.