OpenMates Docs Open Chat

Web App Architecture

Web App Architecture The OpenMates web app at serves as both the product landing page and the full application, replacing the old informative website. Why Th...

[T:documentation.sender_name]

Web App Architecture

The OpenMates web app at openmates.org serves as both the product landing page and the full application, replacing the old informative website.

Why This Exists

A single web app reduces development effort and gives visitors immediate exposure to product capabilities. Unauthenticated visitors see demo chats that showcase features; authenticated users get the full experience.

How It Works

Unauthenticated Experience

When a visitor loads openmates.org without being logged in:

  1. The main surface opens on the new-chat welcome screen rather than auto-opening a demo chat.
  2. Demo chats remain available in the sidebar and from welcome cards with fixed chat IDs (for deep-linkable URLs like /chat/stay-up-to-date-contribute). These are precompiled into the static bundle for SEO and fast load times.
  3. Legal chats (Privacy Policy, Terms of Use, Imprint) are always shown alongside demo chats using the same static-bundle infrastructure.
  4. Logged-out visitors see OpenMates product explainer daily inspirations and a local interest tag rail. Selected guest tags are stored only in sessionStorage under openmates.guest_interest_tags.v1 and locally reorder inspirations, demo/example chats, and new-chat suggestions.
  5. The message input shows a “Signup to send” button instead of “Send”, which opens the signup flow and saves the draft message.

Topic Preferences

Guest topic preferences are privacy-preserving by default. Before signup, cleartext selected tags never leave the browser session and are not written to localStorage.

After login or signup, the web client promotes selected guest tags into encrypted account settings. The API route POST /v1/settings/topic-preferences accepts only encrypted settings ciphertext, and the server does not inspect selected tag IDs. Authenticated web, CLI, and Apple clients decrypt the topic preference payload locally to display Settings > Account > Interests and to rank public fallback surfaces when the account has no personal chats yet.

Demo Chat Content

  • “Welcome to OpenMates!” – short product introduction
  • “What makes OpenMates different?” – comparison to ChatGPT, Claude, etc.
  • Monthly changelog summary
  • Example chats: learning, app power, personalization
  • “OpenMates for developers” – developer features + Signal group link
  • “Stay up to date & contribute” – social media and community links

Legal documents are stored as TypeScript files in frontend/packages/ui/src/legal/documents/:

  • privacy-policy.ts
  • terms-of-use.ts
  • imprint.ts

Updating legal documents requires three steps:

  1. Update the static legal chat files for new users
  2. Send follow-up messages to existing users with a summary of changes
  3. Include the updated full text as an assistant message

Post-Signup Flow

On signup completion, demo chats are kept and the user receives a message explaining they can delete the example chats. Draft messages saved before signup are sent automatically.

WebSocket Auth Expiry

websocketService.ts dispatches an authError event when the server rejects the WebSocket with an authentication or policy-violation signal. The app shell handles that event in +page.svelte by running the local logout cleanup directly instead of re-checking /auth/session, because the session check intentionally treats non-OK responses as offline-first recoverable failures. Pair-login deep links are explicitly excluded so stale WebSocket failures from an old session do not invalidate a fresh passkey pairing flow.

Onboarding

See Onboarding Guide for the implemented user onboarding flow.

Native Apps

The web app is the primary client and ships new features first. Fully native Apple clients (iPhone, iPad, Mac, Apple Watch) are planned and tracked separately in Native Apps Architecture.