Onboarding & First-Use Flow (with diagrams)

Date: July 19, 2026 · Companion to doc 22 (getting-started use cases) and doc 05 (PRD). This is the step-by-step path a new customer actually walks — from buying Trackmint to their team’s first task moving across the board — with flow diagrams, not just prose, per the request to make this visual.

1. The whole journey, end to end

flowchart TD
    A["Purchase / choose a plan"] --> B["First login — create account"]
    B --> C{"First person on this workspace?"}
    C -- Yes --> D["Auto-promoted to Administrator"]
    C -- No, invited --> E["Joins with role set by Admin"]
    D --> F["Setup Wizard — Step 1: Confirm Admin"]
    F --> G["Step 2: Company name"]
    G --> H["Step 3: Business type / profession pack"]
    H --> I["Step 4: Team & roles"]
    I --> J["Step 5: Projects / clients"]
    J --> K["Finish setup — clean, empty workspace"]
    E --> K
    K --> L["Board screen — 0 tasks, ready to go"]
    L --> M["Admin/Manager creates first task, assigns a teammate"]
    M --> N["Assignee: Accept assignment"]
    N --> O["Assignee: ▸ Start job"]
    O --> P["Task auto-moves to In Progress column"]
    P --> Q["Time tracked via one-tap timer on the card"]
    Q --> R["Hours flow to Time & Billing → Invoices"]

Every wizard step (F–J) has a Skip link, and a “Just exploring? Load the demo workspace” link that bypasses the whole flow with sample data — so a curious user is never blocked.

2. Step 1 — Purchase → first login → auto-admin

sequenceDiagram
    participant U as New user
    participant App as Trackmint app
    participant FB as Firebase Auth/Firestore

    U->>App: Signs up with email + password
    App->>FB: createUserWithEmailAndPassword()
    FB-->>App: New uid issued
    App->>FB: Load workspaces/{uid} document
    FB-->>App: Not found (first time)
    App->>App: setup.done = false → show Setup Wizard
    Note over App: The person who completes account creation<br/>for a brand-new workspace becomes Administrator —<br/>no separate "claim admin" step needed.

Why this matters: there’s no separate admin-claiming step to forget. The instant a workspace document doesn’t exist yet, the person creating the account IS the admin — the wizard formalizes that by adding them to the roster with role: 'admin' the moment they move past step 1.

3. Steps 2–5 — the setup wizard

flowchart LR
    S1["① You are the Admin<br/>confirm your display name<br/>+ set your hourly rate (default $100)"] --> S2["② Company<br/>company / firm name"]
    S2 --> S3["③ Business type<br/>Software · Law · Contractor · General<br/>(sets the profession pack)"]
    S3 --> S4["④ Team & roles<br/>add teammates: Worker / Manager / Admin"]
    S4 --> S5["⑤ Projects<br/>add your first clients/projects<br/>(full details later in Setup → Projects)"]
    S5 --> Done["Finish setup"]

    style S1 fill:#FCA311,color:#14213D
    style Done fill:#008300,color:#fff

Each step writes into one Firestore-backed document (workspaces/{uid}) — nothing is submitted until “Finish setup,” and Skip just leaves that field at its default (empty roster/company name), never blocking progress.

4. Team roles — who sees what

flowchart TD
    Admin["Administrator<br/>full access — company, team, billing, everything"]
    Manager["Manager<br/>manages workers, sees billing/invoices"]
    Worker["Worker<br/>sees & works ONLY assigned tasks — no billing"]

    Admin -->|manages| Manager
    Manager -->|assigns tasks to| Worker

This is the Housecall-Pro-style 3-tier model (doc 13): the 2-tier Admin/Member default still works for small teams that don’t need the split — Manager is simply a role option a workspace can start using the moment a team needs it.

5. Assign → accept → start (no new columns)

stateDiagram-v2
    [*] --> Assigned: Manager/Admin creates & assigns task
    Assigned --> Accepted: Assignee taps "Accept"
    Accepted --> InProgress: Assignee taps "▸ Start job"
    InProgress --> Done: Task worked & moved through existing columns

This status sits on top of the existing Kanban columns (Backlog/In Progress/Review/Done, or the legal-pack equivalents) — starting a job simply moves the card into whichever column is already labeled “In Progress.” No new column was added, per the explicit decision to keep the board simple across every profession pack for now.

6. Known limit — today’s model is single-login-per-workspace

Interim mitigation shipped in v4: Setup → Viewing as lets the person holding the device pick which roster member they are — Workers/Members then see time only (no $ figures, no Billing/Invoices tabs), while Admins/Managers see everything. It is an honest stand-in, not security: anyone can switch the viewer back.

Right now every person in members[] is a roster/assignment entry under one shared Firebase Auth login — true multi-person login (each teammate signing in with their own account into the same shared company workspace) is not built yet. That means the “assignee gets notified” step is an in-app status badge visible to whoever has the app open today, not a push notification to a specific person’s phone. This is tracked as the next infrastructure piece before the assign/accept/start flow is fully real for a distributed team — see the backlog doc for sequencing.