Toju/emergency-fix/02-user-journeys.md

# 02 — User journeys (how it is supposed to feel)

Each journey: **steps the user takes**, **what should happen**, **failure symptoms**, **where to dig**.

---

## J1 — First-time home login

**User steps**

1. Open app → login/register.
2. Pick (or accept default) signal server.
3. Register or log in with username/password.
4. Land on dashboard / saved servers.

**Supposed to happen**

- Session token stored for that URL (`metoyou.authTokens` + credential store).
- Local user profile scoped in DB; NgRx `currentUser` set with `homeSignalServerUrl`.
- **Provision secret** created and persisted (Electron safeStorage / web sessionStorage).
- Signing public key registered on **home** server when possible.
- WebSocket connects, `identify` with home token + `clientInstanceId`, ready for joins.

**Broken looks like**

- Stuck on login; bounce back after “success”.
- Dashboard with no token → later `SESSION_EXPIRED`.
- Later foreign joins always open authorize (missing secret).

**Code**

- `domains/authentication/` (`AuthenticationService`, login/register UI)
- `store/users/users.effects.ts` (`authenticateUser`, `prepareAuthenticatedUserStorage`, `ensureHomeProvisionSecret`)
- Feature: `agents-docs/features/authentication.md`

---

## J2 — Restart app still logged in

**User steps**

1. Quit Electron fully; reopen.
2. Expect same user without typing password.

**Supposed to happen**

- Load user from local DB + valid home token (credential store or legacy token fallback).
- Identify on home (and later foreign) sockets.
- Opportunistic `ensureProvisioned` for active endpoints **without** login UI.

**Broken looks like**

- Flash of dashboard then `/login`.
- Profile restored but chat/presence dead (“alone”).
- Foreign rooms immediately open `/login?mode=authorize`.

**Code**

- `loadCurrentUser$`, `hasValidPersistedSession`, `migrateHomeCredential`
- Lessons: identify legacy token fallback; persisted user still needs token

---

## J3 — Join a community on the *same* signal server

**User steps**

1. Discover or invite → Join.
2. Open a text channel; send “hello”.
3. Join a voice channel; talk.

**Supposed to happen**

- REST join with bearer; then WS `join_server`.
- Receive `server_users` / `user_joined`; peer mesh forms.
- Text: local add + DC `chat-message` + WS `chat_message` fallback.
- Voice: `voice_state` broadcast; WebRTC offer/answer; same-channel audio routing.

**Broken looks like**

- Joined in UI but not in others’ member lists (identify/join race).
- Messages only on sender device.
- Voice tile appears, no audio.

---

## J4 — Join a community on a *different* signal server (critical)

**User steps**

1. Already logged into home Signal A.
2. Open invite / browser card whose `sourceUrl` is Signal B.
3. Join and chat/voice.

**Supposed to happen**

1. `ensureCredentialForServerUrl(B)` → silent provision (or reuse credential).
2. REST + WS use **actor id on B**, not home id.
3. No authorize login page.
4. Peers on B see actor display name (may show `#prefix` disambiguation).
5. Voice/chat use B’s WebSocket for that room’s affinity.

**Broken looks like**

- Redirect to `/login?mode=authorize&serverId=…` while user bar still shows logged in.
- Join “succeeds” locally but invisible on B.
- Can see members but WebRTC never connects (initiator/identity mismatch).
- DMs/calls to that person later miss rings or fork conversations.

**Code**

- `SignalServerAuthorizeService`, `SignalServerProvisionerService`, `room-signaling-connection.ts`
- Story: `agents-docs/user-stories/silent-cross-signal-server-auth.md`
- Pack: `04-auth-login-bugs.md`, `09-identity-cross-signal.md`

---

## J5 — Send a text message (server channel)

**User steps**

1. In text channel, type and send.
2. Peer in same room should see it live; late joiner should catch up after connecting.

**Supposed to happen**

- Optimistic local message with stable id (attachments bind to that id).
- Broadcast on data channel; also relay `chat_message` on signaling for peers without DC.
- Edits/deletes primarily P2P (+ `account_sync` to sibling devices).
- On peer connect: inventory ↔ sync-batch (up to 20k recent msgs, chunks of 200).

**Broken looks like**

- Sender sees it; others don’t (no presence / no join / DC+fallback both fail).
- Others see live but not history (DC inventory never ran).
- Multi-device: one device has history, another empty (`account_sync` / identify).
- Attachments “Waiting for image…” forever (announce vs message ordering).

**Pack:** `08-messaging-visibility.md`

---

## J6 — Join voice in a channel

**User steps**

1. Click a voice channel.
2. Grant mic if prompted.
3. Hear others; they hear you; speaking indicators; optional camera/screen.

**Supposed to happen**

- Leave any previous voice/call first (exclusive).
- Publish `voice_state` with channel/server ids + `clientInstanceId`.
- Only one device owns mic (others passive; Join = takeover).
- Peer connections already for chat mesh; mic tracks attached only to same-channel peers.
- Playback only for peers in same voice channel.

**Broken looks like**

- “Connecting” forever.
- One-way audio.
- UI shows peers in channel but silent.
- After network blip: forever dead until full app restart.
- Works same-home, fails cross-home (initiator uses home id vs peer actor id).

**Pack:** `06-voice-webrtc-bugs.md`

---

## J7 — Call someone from DM / people card

**User steps**

1. Open DM or people card → Call.
2. Callee hears ring / sees modal (unless DND).
3. Answer → private call UI with optional chat panel.

**Supposed to happen**

- `direct-call` event delivered via PeerDelivery (DC then signaling).
- `targetUserId` = callee’s **currently connected signal identity**.
- Callee admission checks **all local aliases** (home + every provisioned actor id).
- Caller never sits “In Voice” if ring could not be delivered.

**Broken looks like**

- Caller In Voice; callee silent (outbound route null / wrong id).
- Callee never notified (inbound alias filter — partially fixed).
- Cross-signal: two DM threads; replies land in the “wrong” empty one.

**Pack:** `09-identity-cross-signal.md`

---

## J8 — Network blip / signal server restart

**User steps**

1. In voice + chat; Wi‑Fi blips or signal process restarts.
2. Continue without manual reconnect.

**Supposed to happen**

- WS reconnect with backoff; health probe forces fresh socket on instance change.
- `reIdentifyAndRejoin` then room resync.
- Peer disconnect grace 10s; then reconnect loop (~12 × 5s).
- DC close triggers repair; chat fallback covers live text meanwhile.
- Voice presence clears on dead voice-active disconnect server-side.

**Broken looks like**

- Zombie “online” with no events.
- Give-up after ~60s with **no error UI**.
- Docs promise soft DC replace; code tears down full peer (audio drop).
- Identify skipped → alone forever until manual leave/rejoin.

**Pack:** `05-signaling-multi-server.md`, `07-data-channel-drops.md`

---

## J9 — Two devices, same account

**User steps**

1. Desktop in voice; phone/browser also logged in.
2. Second device shows “in voice on another device”; can Takeover.
3. Chat/history appears on both.

**Supposed to happen**

- Distinct `clientInstanceId` per tab (sessionStorage).
- Broadcasts reach sibling connections; `account_sync` for owned state.
- Voice exclusive; takeover yields mic on old owner.

**Broken looks like**

- Tabs evict each other (shared clientInstanceId in localStorage — lesson says use sessionStorage).
- Second device never gets chat batches.
- Both think they own voice / neither transmits.

---

## J10 — Logout

**User steps**

1. Title-bar Logout (desktop) or Settings → Logout (mobile).

**Supposed to happen**

- Disconnect sockets; clear current user id; reset rooms/users/messages; `/login`.

**Broken looks like**

- Stale credentials for foreign URLs linger and confuse next account (verify credential clear scope when fixing auth).