Figma Analysis & Doc Updates (May 2026)

1. Image Analysis Summary

The Figma file contains roughly twelve distinct screen families. We group them below; each entry follows the requested template.

1.1 Group Chat Room (counselor view)

1.2 Group Chat Room (client view)

1.3 Active Video Call (Inside Chat)

1.4 Inquiry Acknowledgement / "So geht es weiter"

1.5 Notifications Page

1.6 Chat List with Filters & Phases

1.7 Multi-Recipient Send Tool

1.8 Mark Text + PII Blur Tool

1.9 Chat Room Settings ("Chatraum Einstellungen")

1.10 AI Chat Summary

1.11 Help Requests / Internal Escalation

1.12 Case Handover

1.13 Admin Settings — "Berechtigungen" (Permissions Matrix)

1.14 Agency / Tenant Display ("Beratungsstelle Caritas Mainz")

1.15 File Upload Drop-Zone

1.16 Tags / Topic Chips

1.17 Welcome / Inbox Empty States

2. Feature Mapping

3. Documentation Updates

The following pages were touched (or newly created) to reflect §2:

4. Missing or Incomplete Logic

The Figma exposes several gaps where backend or product behaviour is not yet defined.

4.1 Video-Call Self-Delete (Figma question)

"What happens when a user deletes himself during a video call (if he's the initiator)?"

• [MISSING FLOW] — there is no UI for "promote initiator" or "end-call-on-initiator-leave" decision.
• Proposed: see Edge Cases §9.1.7. When a client deletes themselves mid-call, the LiveKit room continues for remaining counselors. The originator role transfers to the next counselor by joined_at ASC; if no counselor remains, the room ends.

4.2 Group-Chat Self-Delete (Figma question)

"What happens if a client deletes himself from a group chat?"

• [MISSING FLOW] — group chats so far were assumed to be all-counselor.
• Proposed: see Edge Cases §9.1.8. Client's pseudonym is wiped immediately; their messages stay (E2EE bodies are not personal data) but their authorship label becomes "Ehemaliger Teilnehmer". If the client was the only advice-seeker, the group is auto-archived.

4.3 Multi-Recipient Send — server-side enforcement

• [UNCLEAR BEHAVIOR] — Matrix has no native "visible only to" message-level restriction.
• Proposed implementation: a server-side bot ("Carimat-relay") is the only sender for restricted messages — it forwards each addressed copy as a 1-to-1 sub-thread, OR uses Matrix m.room.encrypted with per-recipient Megolm sessions. Decision needed.

4.4 PII Blur — durability of marks

• [UNCLEAR BEHAVIOR] — when message bodies are E2EE in Matrix, where do blur ranges live? Options:
  • (a) inside the same encrypted event payload as a structured field;
  • (b) as a separate "annotation" event tied by event_id. (b) is more durable across re-key but requires the receiver client to fetch annotations.

4.5 Phase Model

• [MISSING FLOW] — Anfragephase and Vermittlungsphase are visible in the inbox but the transition rules are not specified. Likely:
  • Anfragephase: ticket created, no counselor assigned.
  • Vermittlungsphase: counselor accepted but client has not yet consented (GDPR #2) or waiting for handover acceptance.
  • Active: both consents given, room finalised.

4.6 Handover Reasons & Consent

• [UNCLEAR BEHAVIOR] — for a "Law Violation" handover, the figma annotation says "Law Enforcement Representative" — meaning a regulator may need access. The legal mechanics (warrant, disclosure scope, encryption-key access) are out of scope for the UI but must be defined before this code path is enabled. Today the platform has no escrow of E2EE keys, so even with a warrant the message bodies remain unreadable.

4.7 Notification Channels

• [UNCLEAR BEHAVIOR] — Notifications can include email mirror (if email captured). What about push? Matrix has push gateways; do we use them for clients with no email? Decision needed.

4.8 Optional Email — privacy

• [UNCLEAR BEHAVIOR] — "Email is not visible to counselors" — is it visible to Counselor Admin? The default should be no (treated as privileged auth field, only readable by Platform Admin for legal/auth purposes).

4.9 Voice Messages

• [NEW FEATURE] — flagged as a permission row but not yet detailed: format, duration cap, transcription? Voice-message E2EE is non-trivial in Matrix.

5. User Flow Reconstruction

5.1 Client Joins via Link → Optional Email + 2FA

sequenceDiagram
  autonumber
  participant Cl as Client
  participant FE as ORISO-Frontend
  participant US as UserService
  participant KC as Keycloak
  Cl->>FE: Open live-chat link
  FE->>US: POST /live-chat/anonymous
  US->>KC: create anonymous user
  KC-->>FE: cookie + pseudonym
  FE-->>Cl: Waiting Room + GDPR popup #1
  Cl->>FE: Confirm consent
  Note over Cl,FE: After session ends, before final wipe:
  FE-->>Cl: "So geht es weiter" — capture optional email?
  alt opted-in
    Cl->>FE: Provide email
    FE->>US: PUT /me/email (privileged-only field)
    Cl->>FE: Enrol 2FA (App or email-magic)
    FE->>KC: required-action: configure TOTP / Magic
  end
  alt account deletion
    Cl->>FE: Click "Konto löschen"
    FE->>US: DELETE /me
    US->>KC: full wipe
  end

5.2 Counselor Picks a Live-Chat Ticket → Optional Group Promotion

sequenceDiagram
  participant Co as Counselor
  participant FE as ORISO-Admin
  participant US as UserService
  participant MX as Matrix
  Co->>FE: Pick ticket from Inbox (Anfragephase)
  FE->>US: POST /live-chat/accept
  US->>MX: create encrypted room
  Note over Co,FE: Active 1-1 chat ongoing
  Co->>FE: "Invite more people" (⇧I)
  FE->>US: POST /rooms/{id}/invite
  US->>MX: invite peers → room becomes group
  Note over Co,FE: Client sees "Counsellor invited X" system msg + may consent again

5.3 Counselor Sends Restricted Message ("visible only to: Moderators")

sequenceDiagram
  participant Co as Counselor
  participant FE as ORISO-Element
  participant Bot as Carimat-Relay (server)
  participant MX as Matrix
  Co->>FE: Compose msg → Adressaten wählen
  FE->>FE: Lock send unless ≥1 recipient selected
  Co->>FE: Pick "3 Moderators" + send
  FE->>Bot: encrypted_payload + recipient_set
  Bot->>MX: For each recipient, send 1-to-1 sub-thread (or per-recipient Megolm)
  Bot-->>FE: ack with sub-event-ids
  FE-->>Co: chip "visible only to: 3 Moderators"

5.4 Counselor Marks & Blurs PII, Then Sends to Editor

sequenceDiagram
  participant Co as Counselor
  participant FE as ORISO-Element
  participant US as UserService
  Co->>FE: Highlight client text
  FE->>FE: Apply color (Tiptap mark)
  Co->>FE: Toggle "blur" eye → 80% white overlay
  Co->>FE: Click "send all marked → editor"
  FE->>FE: Decrypt locally, scrub, package as case-note draft
  FE->>US: POST /case-notes (encrypted at rest)
  US-->>FE: 201 Created

5.5 Case Handover Flow

sequenceDiagram
  autonumber
  participant Co1 as Counselor A (going off)
  participant Co2 as Counselor B (taking over)
  participant FE as ORISO-Admin
  participant US as UserService
  participant Cl as Client
  Co1->>FE: Open Handover modal
  Co1->>FE: Pick reason (Sickness)
  Co1->>FE: Select Co2 from same agency
  FE->>US: POST /handover { from, to, reason }
  US->>US: check consent rules for reason
  US->>Co2: invite to room
  US->>Cl: System msg "Deine vorherige Beraterin ist leider krank…"
  alt reason needs client consent
    US->>Cl: ask consent
    Cl-->>US: accept / reject
  end
  Co2->>FE: accept
  US->>MX: rotate room ownership; remove Co1

5.6 Help Request / Internal Escalation

sequenceDiagram
  participant Co as Counselor
  participant FE as ORISO-Admin
  participant US as UserService
  participant Sup as Supervisor
  Co->>FE: Chatraum Einstellungen → Help requests (⇧Ä)
  FE->>US: POST /escalation { chatId, recipient, mode: internal|external }
  US->>Sup: notification + read-only Matrix invite
  Sup-->>FE: review and respond (in-thread)

5.7 AI Summary

sequenceDiagram
  participant Co as Counselor
  participant FE as ORISO-Element
  participant AI as AI Workflow (self-hosted)
  participant US as UserService
  Co->>FE: Click "Chat Zusammenfassen" (⇧Ü)
  FE->>FE: Decrypt last N events locally
  FE->>FE: Strip PII tokens
  FE->>AI: POST /summarize (scrubbed text)
  AI-->>FE: bullet-summary
  FE->>Co: editable summary panel
  Co->>FE: Save
  FE->>US: PUT /case-notes/{id}

6. Role-Based Insights

6.1 Platform Admin

• Adds: edits the per-chat-type Permissions Matrix (F8) at the platform default level.
• Adds: chooses which handover reasons are available globally and which require which consent.
• Adds: turns AI Summary, Blur tool, Multi-Recipient Send on/off platform-wide.
• Restriction: still cannot read message contents.

6.2 Tenant Admin

• Adds: overrides the Permissions Matrix for the whole tenant (subject to platform allowance).
• Adds: enables/disables Voice Messages, Threads, Calls per chat-type.
• Adds: maintains the agency context label that shows on counselors' avatars.

6.3 Counselor Admin

• Adds: per-agency override of Permissions Matrix.
• Adds: invites for group chats (round-tables, peer support).
• Adds: chooses which counselors have the Supervisor function for a given group.

6.4 Counselor

• Adds: full toolset in 1-1 / group / supervision chats — multi-recipient send, mark/blur, AI summary, handover, help-request, file upload.
• Restriction: every tool is gated by the Permissions Matrix for the chat type they are in.

6.5 Client (Anonymous or with Optional Email)

• Adds: optional email + 2FA + account deletion.
• Adds: notifications inbox (only their own).
• Adds: may participate in group chats (peer support) but multi-recipient send, mark/blur, AI summary, handover, help-request are hidden.
• Adds: may leave a group chat at any time → wipe of pseudonym, messages remain in others' history under "Ehemaliger Teilnehmer".

6.6 Supervisor (Function on Counselor)

• Adds: receives Help-Request invites.
• Adds: read-only or full participation depending on configuration.
• Adds: visible to the room with a system message "Supervision Enabled!".

7. Assumptions

These are explicit and remain to be validated against code / Frank.

• A1 — Group chat = generalized Matrix room. No new chat protocol; group chats use the same Synapse, just with multiple counselor / client members and chat-type metadata.
• A2 — Multi-Recipient Send is implemented via a server-side relay bot or per-recipient Megolm sessions. Not native to Matrix; needs decision.
• A3 — Mark/Blur lives as message-overlay annotations, separate from message body, synced as encrypted events.
• A4 — AI Summary runs in browser (decrypt+scrub) → self-hosted summarizer. Server never sees ciphertext or PII.
• A5 — Phase model uses three states: Anfragephase, Vermittlungsphase, Aktiv. The Vermittlungsphase covers GDPR-#2-pending and handover-pending. Needs validation.
• A6 — "Email not visible to counselors" means visible only to Platform Admin for legal / auth purposes; never to Counselor Admin or Counselor.
• A7 — 2FA via App or Email for clients is opt-in and only available if they captured an email.
• A8 — Account deletion triggers the same wipe pipeline as client-leaves-room, plus removal of the optional email and any notifications.
• A9 — Tenant-level permission overrides cascade: Platform → Tenant → Agency → Chat-type. Final effective permission = AND of all applicable layers (a parent disabling a feature beats a child enabling it).
• A10 — Voice messages: Megolm-encrypted Opus blobs uploaded to Matrix media repo; stored ≤ 48 h like text.
• A11 — Tags are agency-scoped vocabularies; "Cant find Matching Tag?" CTA opens an "ask the admin" inquiry.
• A12 — Animations rule: each animation plays once per click; ≤ 0.7× speed; never loops. Adopted as a global UX constant.
• A13 — Languages: DE / EN / TR / FR are confirmed first-class. Default = browser language with EN fallback (not DE).
• A14 — File upload limit is 10 MB per file; mime allow-list is jpg, png, pdf, docx, xlsx. Server rejects others.
• A15 — Inviter rule: when a counselor invites someone to an active 1-1 room, the room becomes a group; the client gets a system message and may see a re-consent prompt depending on tenant policy.
• A16 — Handover reasons that touch external authority ("Law Violation") still cannot break E2EE; the system only delivers metadata access. Legal escalation is documented but not implemented in v3.
• A17 — Carimat / Chatbot scripted onboarding is the planned name for the on-rails first-message bot that asks topic / language; not yet implemented.

If any of A1-A17 is wrong, please update this page first and let the rest of the docs cascade.