> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# User Lifecycle

> Sequence diagrams: how an account is created, onboarded into its Personal organisation, joins and leaves team organisations, and is erased.

# User Lifecycle

Every real account has one **Personal** organisation (`organisations.kind = 'personal'`): a private space only its owner belongs to, holding as many workspaces (bundles) as they like. Team organisations (`kind = 'team'`) are shared. Guests never get a Personal organisation. See [Organisations](https://docs.kair.is/api/organisations.md) for the rules.

## 1. Getting an account

An invite never creates workspaces or a Personal organisation; the first login does (step 2). Inviting an existing account only adds the membership.

```mermaid theme={null}
sequenceDiagram
    actor P as Person
    actor A as Platform admin
    actor OA as Org admin (team T)
    participant API
    participant DB

    alt Waitlist
        P->>API: POST /waitlist/signup
        API->>DB: waitlist row (pending)
        A->>API: POST /waitlist/{id}/approve {role, organisation_id: T or null}
        API->>DB: check T is a team organisation (a personal one is refused, 400)
        API->>DB: user (current org = T or none)<br/>+ membership in T when picked<br/>+ magic-link token (24 h)
        API-->>P: approval email with magic link
    else Org invite, new email
        OA->>API: POST /organisations/T/members {email}
        API->>DB: user (current org = T) + membership in T + magic-link token
        API-->>P: invite email with magic link
    else Org invite, existing account
        OA->>API: POST /organisations/T/members {email}
        API->>DB: membership in T (made current only if they had none)
    end
```

## 2. First login (onboarding)

`ensure_personal_organisation` runs on every magic-link login of a non-guest. It does the work once and is a no-op afterwards; if it fails the login fails, and the next login retries. The per-user slug (`personal-<user id>`) is unique: of two concurrent first logins, the second finds the first's. Workspaces without an organisation that only this account uses (from before personal organisations) move in, and a home workspace is created only when the account has none.

```mermaid theme={null}
sequenceDiagram
    actor P as Person
    participant API
    participant DB

    P->>API: POST /auth/validate-magic-link {token}
    API->>DB: mark token used, load user
    alt not a guest
        API->>DB: user has a Personal organisation?
        alt no (first login)
            API->>DB: in one transaction:<br/>Personal organisation (owner as member)<br/>+ private home workspace in it (default link, integrations live here)<br/>+ Personal made current if the user has no current org
        end
    end
    API->>DB: set onboarded_at (first time only)
    API-->>P: session + user (current org = T or Personal)
```

A guest who completes onboarding (`POST /auth/complete-guest-onboarding`) gets a magic link, and their Personal organisation at that login.

## 3. Everyday use

```mermaid theme={null}
sequenceDiagram
    actor P as Person
    participant UI
    participant API
    participant DB

    UI->>API: GET /organisations/mine
    API-->>UI: Personal first (kind personal), then team organisations by name
    UI->>UI: switcher: "Personal" with a person icon, divider, teams
    P->>API: POST /organisations/switch {Personal}
    API->>DB: users.organisation_id = Personal
    P->>API: POST /workspaces (any number)
    API->>DB: workspace in the current organisation
    P->>API: POST /workspaces/{id}/members (personal workspace)
    API-->>P: 409, personal workspaces aren't shared
```

* Workspace lists show only workspaces whose `organisation_id` is the current organisation.
* Personal workspaces show a folder with a lock, no Share button, and a hint to move sessions into a team workspace to share them.
* Sessions in Personal build topics like any other organisation; their summaries use the prompt override shared by all personal organisations.

## 4. Leaving a team organisation

```mermaid theme={null}
sequenceDiagram
    actor OA as Org admin (T)
    participant API
    participant DB

    OA->>API: DELETE /organisations/T/members/{user_id}
    API->>DB: drop links to T's workspaces (not the default one) and ownership of them
    API->>DB: delete the T membership
    alt T was current
        API->>DB: current org = Personal (else another membership)
    end
```

Every member-management call on a personal organisation (add, role, remove, rename, icon) returns 409, for platform admins too.

## 5. Erasure

```mermaid theme={null}
sequenceDiagram
    actor P as Person
    actor D as Decider
    participant API
    participant W as rag-worker
    participant DB

    P->>API: POST /me/data-requests {organisation_id}
    D->>API: approve
    API->>W: erasure job
    W->>DB: erase the person's content in that organisation's workspaces
    alt request is for their Personal organisation, or their last team
        W->>DB: also their Personal workspaces; delete them, shared or not
    end
    W->>DB: delete the membership, clear current org if it pointed there
    alt no team membership left
        W->>DB: remove account-level records and the Personal membership
    end
```

See [Data subject requests](https://docs.kair.is/platform/data-subject-requests).

## 6. Existing accounts at rollout

Migration `m20261110_000001_personal_organisations` brings accounts from before personal organisations in line. It runs on deploy, so run the read-only check below against production first and get it approved ([#197](https://github.com/meldtech/kair-voice/issues/197), "Before the backfill").

```mermaid theme={null}
sequenceDiagram
    participant M as Migration
    participant DB

    M->>DB: organisations.kind; prompt overrides keyed by organisation ('default' rows become the personal default)
    M->>DB: Personal organisation for every real account (not guests, deleted or pending deletion)
    M->>DB: workspaces with no organisation or in 'default':<br/>one real account → its Personal; several → the team most of them share;<br/>else left in place (logged as a notice)
    M->>DB: drop topic links that now cross organisations; strands follow their workspace
    M->>DB: queue topic merges for sessions that never had an organisation
    M->>DB: current org 'default' or none → Personal; guests → none; API keys follow
    M->>DB: dissolve 'default' once nothing refers to it
```

`users.customer_group` and `customer_prompt_overrides.customer_group` stay one more release, because pods of the previous release read them while this one rolls out. No code reads them; drop them in a migration of the next release.

### Read-only check

Run it in a read-only transaction. It returns account ids and counts, never content; don't copy its output into tickets or files.

```sql theme={null}
BEGIN READ ONLY;

-- Who administers 'default'.
SELECT m.user_id FROM user_organisations m JOIN organisations o ON o.id = m.organisation_id
WHERE o.slug = 'default' AND m.role = 'org_admin';

-- 'default' workspaces with strands and cross-workspace matching on.
SELECT w.id FROM workspaces w JOIN organisations o ON o.id = w.organisation_id
WHERE o.slug = 'default' AND w.strands_enabled AND w.cross_workspace_matching;

-- Topic links between workspaces of different owners (the backfill drops those that end up
-- in different organisations).
SELECT count(*) FROM strand_relations r
JOIN strands a ON a.id = r.from_strand_id JOIN workspaces wa ON wa.id = a.workspace_id
JOIN strands b ON b.id = r.to_strand_id JOIN workspaces wb ON wb.id = b.workspace_id
WHERE wa.owner_user_id IS DISTINCT FROM wb.owner_user_id;

-- Workspaces the backfill will place, by how many real accounts use them (1 → Personal,
-- 2+ → majority team), and how many accounts get a Personal organisation.
SELECT people, count(*) FROM (
    SELECT w.id, count(DISTINCT u.id) AS people
    FROM workspaces w
    LEFT JOIN users u ON (u.id = w.owner_user_id
        OR u.id IN (SELECT uw.user_id FROM user_workspaces uw WHERE uw.workspace_id = w.id))
        AND NOT u.is_guest AND u.deleted_at IS NULL
    WHERE w.organisation_id IS NULL
       OR w.organisation_id IN (SELECT id FROM organisations WHERE slug = 'default')
    GROUP BY w.id
) t GROUP BY people ORDER BY people;

SELECT count(*) FROM users u
WHERE NOT u.is_guest AND u.deleted_at IS NULL AND u.frozen_at IS NULL;

ROLLBACK;
```

After it runs, rebuild the topic graph so projected topics carry their new organisation: `kair-voice-topic-backfill project`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.