Skip to content

chore: add AI agent configuration and ubiquitous language glossary #7091

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
diegolmello merged 3 commits into from
Apr 7, 2026
+239 −0
Merged

chore: add AI agent configuration and ubiquitous language glossary #7091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
398da3b
Added claude and opencode files
diegolmello Apr 1, 2026
cdfce88
https://github.com/mattpocock/skills/blob/651eab033bdf8f7fd535c274f8c…
diegolmello Apr 1, 2026
4170203
chore: format code and fix lint issues
diegolmello Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
CLAUDE.md
93 changes: 93 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Rocket.Chat React Native mobile client. Single-package React Native app (not a monorepo) using Yarn 1.22.22 (npm won't work). Supports iOS 13.4+ and Android 6.0+.

- React 19, React Native 0.79, Expo 53
- TypeScript with strict mode, baseUrl set to `app/` (imports resolve from there)
- Min Node: 22.14.0

## Commands

```bash
# Install & setup
yarn # Install dependencies (postinstall runs patch-package)
yarn pod-install # Install iOS CocoaPods (required before iOS builds)

# Run
yarn start # Start Metro bundler
yarn ios # Build and run on iOS
yarn android # Build and run on Android

# Test
TZ=UTC yarn test # Run Jest unit tests (TZ=UTC is set in script)
yarn test -- --testPathPattern='path/to/test' # Run a single test file
yarn test-update # Update snapshots

# Lint & format
yarn lint # ESLint + TypeScript compiler check
yarn prettier-lint # Prettier auto-fix + lint

# Storybook
yarn storybook:start # Start Metro with Storybook UI
yarn storybook-generate # Generate story snapshots
```

## Code Style

- **Prettier**: tabs, single quotes, 130 char width, no trailing commas, arrow parens avoid, bracket same line
- **ESLint**: `@rocket.chat/eslint-config` base with React, React Native, TypeScript, Jest plugins
- **Before committing**: Run `yarn prettier-lint` and `TZ=UTC yarn test` for modified files
- Pre-commit hooks enforce these checks

## Architecture

### State Management: Redux + Redux-Saga

- **Actions** (`app/actions/`) — plain action creators
- **Reducers** (`app/reducers/`) — state shape (app, login, connect, rooms, encryption, etc.)
- **Sagas** (`app/sagas/`) — side effects (init, login, rooms, messages, encryption, deepLinking, videoConf)
- **Selectors** (`app/selectors/`) — memoized with reselect
- **Store** (`app/lib/store/`) — configures middleware (saga, app state, internet state)

### Navigation: React Navigation 7

- **Stacks** (`app/stacks/`) — InsideStack (authenticated), OutsideStack (login/register), MasterDetailStack (tablets), ShareExtensionStack
- **Root** (`app/AppContainer.tsx`) — switches between auth states
- **Responsive layout** (`app/lib/hooks/useResponsiveLayout/`) — master-detail on tablets vs single stack on phones

### Database: WatermelonDB (offline-first SQLite)

- **Models** (`app/lib/database/model/`) — Message, Room, Subscription, User, Thread, Upload, Server, CustomEmoji, Permission, Role, etc.
- **Schema** (`app/lib/database/schema/`)
- Local-first: UI reads from DB, sagas sync with server

### API Layer

- **SDK** (`app/lib/services/sdk.ts`) — Rocket.Chat JS SDK for WebSocket real-time subscriptions
- **REST** (`app/lib/services/restApi.ts`) — HTTP via fetch
- **Connect** (`app/lib/services/connect.ts`) — server connection management

### Views & Components

- **Views** (`app/views/`) — 70+ screen components
- **Containers** (`app/containers/`) — reusable UI components
- **Theme** (`app/theme.tsx`) — theming context

### Other Key Systems

- **i18n** (`app/i18n/`) — i18n-js with 40+ locales, RTL support
- **Encryption** (`app/lib/encryption/`) — E2E encryption via @rocket.chat/mobile-crypto
- **Enterprise** (`app/ee/`) — Omnichannel/livechat features
- **Definitions** (`app/definitions/`) — shared TypeScript types
- **VideoConf** (`app/sagas/videoConf.ts`, `app/lib/methods/videoConf.ts`) — server-managed video conferencing (Jitsi); uses Redux actions/reducers/sagas. May be replaced or removed in the future.
- **VoIP** (`app/lib/services/voip/`) — new WebRTC peer-to-peer audio calls with native CallKit (iOS) and Telecom (Android) integration; uses Zustand stores, not Redux. VoIP and VideoConf are entirely separate features — do not conflate them.

### Entry Points

- `index.js` — registers app, conditionally loads Storybook
- `app/index.tsx` — Redux provider, theme, navigation, notifications setup
- `app/AppContainer.tsx` — root navigation container
145 changes: 145 additions & 0 deletions UBIQUITOUS_LANGUAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
# 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 |

## 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**)
Comment thread
diegolmello marked this conversation as resolved.
- 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.
Loading