Matrix is powerful. RelayDesk stays independent.
RelayDesk owns a neutral Unified Feed contract. Matrix is the first bridge/transport plugin because it can aggregate many networks, but direct provider adapters can coexist beside it and the user interface does not depend on Matrix internals.
Business architecture
One web feed, one search, one priority model and one action model.
Matrix bridges give breadth; direct APIs give control and provider-native features.
No single messaging network, bridge operator or AI vendor becomes an irreversible dependency.
High-level technical design
Browser UI ↓ RelayDesk Canonical Feed + Adapter Registry ├─ Matrix Adapter ──> Matrix Homeserver ──> Installed Bridge Services ──> External Networks │ └─ WhatsApp Bridge ──> linked-device session (no resident WhatsApp Web UI) ├─ Microsoft Adapter ──> Microsoft Graph ├─ Slack Adapter ──> Slack Web API ├─ Email Adapter ──> Gmail API / IMAP / SMTP └─ Future Adapters Every adapter returns the same RelayDesk Feed Item contract.
Backend split: Matrix + RelayDesk Core
Homeserver, Matrix rooms and reviewed bridges can carry communication events across many networks.
Owns users, connector configuration, feed metadata, priority, rules, automation, audit state and future AI permissions.
This split lets Matrix become the primary communication hub without making Matrix the identity database, business-rules engine or permanent storage model for every RelayDesk feature. The application backend can use PostgreSQL/Supabase or another replaceable service behind RelayDesk APIs.
Canonical feed item
provider account conversationId conversationName sender receivedAt unread priority safePreview supportedActions sourceLink streamClass adapterMetadata
Provider-specific fields stay inside adapter metadata so the main UI remains provider-neutral.
RelayDesk first merges clearly-labelled Demo, Test and connector events into one canonical source set, then applies the person/alias layer and provider-neutral attention overlay. Web 2.2.1 makes the resolved person/thread view the default feed presentation while preserving provider/account provenance on every event. The preview demonstrates Sarah Johnson across Outlook and Teams plus stable local Test Lab peer identities. The user can switch to Events mode to inspect the raw underlying communication items. Production resolution must rely on provider identifiers or explicit user-controlled links, and users must be able to split an incorrect merge.
RelayDesk now models thread identity and outbound route separately. The person/thread correlation layer decides what belongs together for the user. The selected event retains provider, provider account and connector capability metadata as the default reply route. Same-channel reply is therefore the default, not an accidental UI behavior. If a connector cannot send, the client must show that limitation and must not pretend an external message was delivered.
Person Thread ├─ Outlook event -> returnPath: Microsoft/Outlook account A ├─ Teams event -> returnPath: Microsoft/Teams account A └─ WhatsApp event-> returnPath: WhatsApp bridge/account B User selects event -> RelayDesk resolves connector capability -> Send on same route by default
The reply composer keeps the execution guard after route resolution. If the selected provider does not have a tested reply-capable adapter, the send action is blocked and the text is stored as a local draft with provider, account and conversation identity plus a reason code. Web 2.3.7 separated receive, reply, authentication and implementation state; Web 2.3.8 adds a provider-normalization contract for imported events and blocked drafts. Clear aliases normalize to canonical provider identities while the original label is preserved in rawProvider. Ambiguous sources remain Unknown and cannot be promoted to reply-ready. Thread Integrity Audit continues to validate provider + account + conversation keys and possible collisions before future connector code merges unrelated conversations.
Selected event -> Return Path Router -> capability matrix\n reply=true -> explicit user send path\n reply=false -> Identity Guard -> route-preserving local draft\n -> Draft Queue grouped by provider/account\n\nImported event / blocked draft\n -> canonical route key: provider + account + conversation\n -> Thread Integrity Audit\n -> missing identity / possible collision diagnostics\n -> no automatic mutation
Task, Schedule, Save Contact, Summarize/Draft and future services sit above the provider layer. A service intent carries conversation/person context plus provenance, then a service adapter decides how to execute it. This keeps calendar, CRM, tasks and AI optional and replaceable, exactly like communication transports.
Matrix role
Matrix Application Services are designed for extensible server-side behavior and bridges. A bridge can connect Matrix to a third-party platform and represent remote users/rooms inside Matrix. RelayDesk consumes the resulting Matrix rooms through its client adapter, but bridge deployment remains separate infrastructure controlled by the homeserver/bridge operator.
Web 2.1 Core state contract
RelayDesk Core State profile / user identity connector account metadata conversation attention state user preferences audit timestamps Never export/store in client state: provider access tokens passwords Matrix access token
The current app can export a browser-local Core State envelope for testing. The production target is authenticated RelayDesk APIs backed by an isolated PostgreSQL/Supabase project with Row Level Security (RLS), so each user can access only their own state.
Web 2.0 security boundary
- Use HTTPS homeserver URLs.
- The current developer preview keeps a test Matrix token in browser session storage only.
- No Matrix token is written into WordPress page content.
- Message rendering uses text nodes rather than trusting provider HTML.
- Production authentication should move to a hardened server-side/session design.
- Direct adapters will use their own scoped authorization and must not share credentials unnecessarily.
Connector resource policy
Heavy provider web applications should not remain resident merely to keep a RelayDesk account online. In Web 2.2.0, WhatsApp defaults to Bridge Mode: the linked-device bridge carries events while the native WhatsApp Web interface stays closed.
If a provider-native function is missing, its web client can open on demand as a disposable fallback and should be closed again when finished.
RelayDesk keeps the normalized conversation state and provenance so closing a provider tab does not remove the Unified Feed experience.
For personal WhatsApp testing, a reviewed Matrix/WhatsApp bridge is the preferred low-memory experiment. For business workflows, a provider-approved API adapter is the cleaner production direction. RelayDesk does not treat a permanently loaded WhatsApp Web tab as acceptable normal architecture.
Connector telemetry
Web 2.2.0 retains the application-level health panel and adds the WhatsApp Bridge Mode state to connector behavior. RelayDesk reports only what the browser/app can verify honestly rather than inventing operating-system memory numbers.
connector state resident provider UI required? yes / no last normalized activity normalized event count local preview cache size Matrix session configured? yes / no WhatsApp mode: bridge / native temporary fallback JavaScript heap: only when browser exposes it NOT claimed: exact per-tab RAM when the browser/OS does not expose it
Web 2.3.0 local action layer
The Action Center sits above normalized communication. It never changes the provider event or its return route. A user-authorized action creates a separate local object—task, event, contact, summary or draft—with a reference to the provider/account context.
Provider event -> normalization -> person thread -> selected provider/account provenance -> user-approved action -> local task / event / contact / draft Portable Workspace -> JSON / CSV / EML import -> normalization -> local priority rules -> Unified Feed Backup -> RelayDesk browser state -> portable JSON -> excludes session tokens and passwords
Browser storage is an honest developer-preview boundary, not the production account model. Cross-device continuity will require authenticated RelayDesk services, encryption, tenant isolation and connector-specific authorization without making Matrix or any Artificial Intelligence provider a core dependency.
Adapter capability contract
Each adapter should explicitly declare capabilities such as read, send, edit, delete, mark-read, attachment support, reactions, thread support, deep-link support and whether a resident provider user interface is required. The UI exposes only actions actually supported by the selected adapter.