# Ubiquitous Language

## Rooms & Conversations

| Term               | Definition                                                                                                                     | Aliases to avoid              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| **Room**           | A server-side conversation container with shared state (name, type, settings)                                                  | Chat, conversation            |
| **Subscription**   | A user's personal relationship to a Room, holding per-user state (unread count, favorite, muted, open)                         | Membership, room entry        |
| **Channel**        | A public Room (type `'c'`) visible to all server users                                                                         | Public room                   |
| **Group**          | A private Room (type `'p'`) visible only to invited members                                                                    | Private room, private channel |
| **Direct Message** | A 1-on-1 private Room (type `'d'`) between two users                                                                           | DM, PM, private message       |
| **Thread**         | A branched conversation spawned from a single Message, identified by `tmid` (thread message id)                                | Reply chain                   |
| **Discussion**     | A separate Room spawned from a parent Room, identified by `prid` (parent room id) — unlike Threads, Discussions are full Rooms | Sub-room, sub-channel         |
| **Team**           | An organizational container that groups multiple Channels and users under a single entity                                      | Workspace (ambiguous)         |

## Messages

| Term               | Definition                                                                                                                     | Aliases to avoid    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| **Message**        | A unit of communication within a Room, identified by `_id` with content in `msg` and parsed markdown in `md`                   | Chat message, text  |
| **Thread Message** | A Message that belongs to a Thread, identified by presence of `tmid`                                                           | Reply, thread reply |
| **System Message** | A Message generated by the server to record events (user joined, room archived, role changed) — identified by `t` (type) field | Event, notification |
| **Attachment**     | Rich media or structured data embedded in a Message (image, video, audio, file, or action buttons)                             | File, media         |
| **Reaction**       | An emoji response to a Message, tracking which usernames reacted                                                               | Emoji reaction      |
| **Mention**        | An `@username` reference within a Message that triggers notifications                                                          | Tag, ping           |
| **Draft Message**  | A user's unsent composition stored on a Subscription or Thread (`draftMessage` field)                                          | Unsent message      |
| **Snippet**        | A saved excerpt from a Message                                                                                                 | —                   |

## Message Status

| Term        | Definition                                                           | Aliases to avoid |
| ----------- | -------------------------------------------------------------------- | ---------------- |
| **Sent**    | Message successfully delivered to server (status `0`)                | Delivered        |
| **Temp**    | Message created locally but not yet confirmed by server (status `1`) | Pending, sending |
| **Error**   | Message that failed to send (status `2`)                             | Failed           |
| **Pinned**  | Message flagged as important and pinned to the Room by a user        | Bookmarked       |
| **Starred** | Message bookmarked by the current user for personal reference        | Saved            |

## Users & Roles

| Term            | Definition                                                                         | Aliases to avoid        |
| --------------- | ---------------------------------------------------------------------------------- | ----------------------- |
| **User**        | An authenticated identity on the server with username, status, and roles           | Account, profile        |
| **Logged User** | The currently authenticated User session, holding auth token and preferences       | Current user, session   |
| **Role**        | A named permission group assigned to Users (e.g., owner, moderator, leader, guest) | Permission group        |
| **Permission**  | A named capability mapped to one or more Roles                                     | Privilege, access right |
| **Active User** | A User currently tracked as online/away/busy via real-time presence                | Online user             |
| **Member**      | A User viewed in the context of a specific Room's membership list                  | Participant             |

## User Status

| Term        | Definition                       | Aliases to avoid |
| ----------- | -------------------------------- | ---------------- |
| **Online**  | User is actively connected       | Active           |
| **Away**    | User idle past timeout threshold | Idle             |
| **Busy**    | User has set do-not-disturb      | DND              |
| **Offline** | User is not connected            | Disconnected     |

## Omnichannel / Livechat

| Term                   | Definition                                                                                           | Aliases to avoid             |
| ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Omnichannel Room**   | A customer-service Room (type `'l'`) connecting a Visitor to an Agent                                | Livechat room, support chat  |
| **Visitor**            | An external customer who initiates an Omnichannel conversation, identified by a unique token         | Client, customer, end-user   |
| **Agent**              | A User designated to handle Omnichannel conversations, with `statusLivechat` (available/unavailable) | Support agent, operator, rep |
| **Inquiry**            | A queued Omnichannel request waiting to be picked up or routed to an Agent                           | Queue item, ticket           |
| **Department**         | An organizational unit that groups Agents for Omnichannel routing                                    | Team (ambiguous), group      |
| **Omnichannel Source** | How an Omnichannel conversation was initiated (widget, email, sms, app, api)                         | Channel origin               |
| **Served By**          | The Agent currently assigned to handle an Omnichannel Room                                           | Assigned agent, handler      |
| **On Hold**            | An Omnichannel Room temporarily paused by the Agent                                                  | Paused, suspended            |
| **Transfer**           | Moving an Omnichannel Room to a different Agent or Department                                        | Forward, reassign, handoff   |

## Encryption

| Term               | Definition                                                                                                             | Aliases to avoid |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **E2E Encryption** | End-to-end encryption for Room content using AES-SHA2, with two protocol versions (`rc.v1.aes-sha2`, `rc.v2.aes-sha2`) | Encryption, E2EE |
| **E2E Key**        | A user's asymmetric key pair (public + private) for E2E Encryption                                                     | Crypto key       |
| **OTR**            | Off-The-Record messaging — ephemeral encrypted conversation mode between two users                                     | —                |

## Video & Voice

| Term                        | Definition                                                                                                                                                                                                | Aliases to avoid               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Video Conference**        | A video/voice call session with status lifecycle (calling, started, expired, ended, declined)                                                                                                             | Video call, meeting            |
| **Direct Video Conference** | A 1-on-1 Video Conference                                                                                                                                                                                 | —                              |
| **Group Video Conference**  | A multi-participant Video Conference with title and anonymous user support                                                                                                                                | —                              |
| **VOIP**                    | Voice-over-IP phone-style call, separate from Video Conference — uses ICE servers and media streams                                                                                                       | Phone call, voice call         |
| **Native Accept**           | An incoming VOIP call answered by native code (CallKit on iOS, Telecom on Android) before the JS runtime is available; native issues the REST accept and JS reconciles state on launch via initial events | JS accept, app accept          |
| **Per-call DDP**            | A short-lived DDP client opened by native code per incoming VOIP call so accept and signaling land before JS boots; separate from the main app DDP session                                                | Native socket, side socket     |
| **Media Signal**            | A typed event on the `@rocket.chat/media-signaling` wire protocol (offer, answer, ICE candidate, state update) carried over DDP `stream-notify-user` and replayable via REST `media-calls.stateSignals`   | Signal, RTC event              |
| **Pending Hangup**          | A VOIP call id recorded in-memory when the user taps End while the WebSocket is unhealthy, so the hangup Media Signal can be replayed through the lib's transporter on the next post-login reconnect      | Hangup intent, deferred hangup |

## Server & Connection

| Term               | Definition                                                                                        | Aliases to avoid                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Server**         | A Rocket.Chat server instance the app connects to, with version, settings, and enterprise modules | Workspace (used by web but not consistently in mobile), instance |
| **Server History** | List of previously connected Servers for quick reconnection                                       | Recent servers                                                   |
| **Meteor Connect** | The WebSocket connection to the Server's DDP (Distributed Data Protocol) endpoint                 | Socket, connection                                               |

## Navigation & Layout

| Term                 | Definition                                                                                | Aliases to avoid       |
| -------------------- | ----------------------------------------------------------------------------------------- | ---------------------- |
| **Outside Stack**    | Navigation screens shown when unauthenticated (server selection, login, register)         | Auth stack, login flow |
| **Inside Stack**     | Navigation screens shown when authenticated (rooms, settings, profile)                    | Main stack, app stack  |
| **Master-Detail**    | Tablet layout with room list (master pane) and room content (detail pane) side by side    | Split view, two-pane   |
| **Chats Stack**      | The primary messaging navigation within Inside Stack (room list, room view, room actions) | —                      |
| **Drawer Navigator** | Side navigation containing tabs: Chats, Profile, Settings, Admin, Accessibility           | Sidebar, menu          |

## Unread & Notification Indicators

| Term               | Definition                                                                                               | Aliases to avoid  |
| ------------------ | -------------------------------------------------------------------------------------------------------- | ----------------- |
| **Unread**         | Count of unread regular Messages in a Subscription                                                       | Badge count       |
| **User Mentions**  | Count of Messages that `@mentioned` the current user in a Subscription                                   | Personal mentions |
| **Group Mentions** | Count of `@all` or `@here` mentions in a Subscription                                                    | Channel mentions  |
| **Tunread**        | Array of Thread IDs with unread replies                                                                  | Thread unread     |
| **Alert**          | Boolean flag on a Subscription indicating it has unread mentions or special activity requiring attention | Notification flag |

## Relationships

- A **Room** can be of type **Channel**, **Group**, **Direct Message**, or **Omnichannel Room**
- A **Subscription** belongs to exactly one **Room** and one **User**
- A **Message** belongs to exactly one **Room** (via `rid`)
- A **Thread** is spawned from exactly one **Message** and contains one or more **Thread Messages**
- A **Discussion** creates a new **Room** linked to a parent **Room** (via `prid`)
- A **Team** has exactly one main **Room** and can contain multiple **Channels**
- An **Omnichannel Room** connects exactly one **Visitor** with zero or one **Agents** (via **Served By**)
- An **Agent** belongs to one or more **Departments**
- An **Inquiry** becomes an **Omnichannel Room** when picked up by an **Agent**

## Example dialogue

> **Dev:** "When a user opens the app, do they see their **Subscriptions** or their **Rooms**?"
> **Domain expert:** "**Subscriptions**. The sidebar shows the user's Subscriptions — each one points to a Room, but carries user-specific state like **Unread** count and **Alert** flag. A Room exists independently; a Subscription is the user's window into it."
> **Dev:** "So if someone starts a **Thread** in a **Channel**, does that create a new **Subscription**?"
> **Domain expert:** "No. A **Thread** lives inside the parent Room's **Subscription**. Thread unreads are tracked via **Tunread** on the Subscription. A **Discussion**, on the other hand, creates an entirely new Room with its own Subscription."
> **Dev:** "And for **Omnichannel** — when a **Visitor** sends a message from the widget, what happens?"
> **Domain expert:** "An **Inquiry** is created and queued. Once an **Agent** picks it up or routing assigns it, the Inquiry becomes an **Omnichannel Room** with the Agent recorded in **Served By**. If the Agent needs to escalate, they do a **Transfer** to another Agent or **Department**."

## Flagged ambiguities

- **"Workspace"** is used by Rocket.Chat web to mean a server instance, but the mobile codebase uses **Server**. Use **Server** in mobile context to avoid confusion with the web admin concept.
- **"Room type `'e2e'`"** and **"Room type `'thread'`"** appear in `SubscriptionType` enum but are marked with FIXME in code — these are not true room types but flags. Do not treat them as room types in new code.
- **"Account"** is sometimes used loosely to mean either **User** (the identity) or **Server** (the connected instance). These are distinct: a **User** authenticates on a **Server**.
- **"Channel"** in everyday speech can mean any Room, but in domain terms it strictly means a public Room (type `'c'`). A private Room is a **Group** (type `'p'`).
- **"Forward"** in omnichannel context means **Transfer** (reassigning a room to another agent/department). The codebase uses both `forwardRoom` and "transfer" — prefer **Transfer** as the domain term.
