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.

Recent Workspace Navigation

Task, Plan, and Project services retain bounded query and entity results across page mounts through workspaceQueryCache.ts. Keys include the account, API environment, team, and key epoch. Loaded empty results count as cached data. Identical requests share one pending read; warm results render immediately while stale results refresh in the background. Local mutations update the shared results, and generations prevent earlier reads from replacing newer changes or repopulating a cleared identity. Logout and key/team changes clear these decrypted memory caches. Visible views also refresh on focus, reconnect, and their existing polling schedule.

Task detail uses the selected /v1/user-tasks/{id} record and its owner assignment metadata. Linked context resolves cached entities or explicit related IDs independently of the main content. Opening one Task does not fetch the full Task, Plan, or Project list. Task board moves serialize each Task’s action and reorder, and late action results cannot restore a previous account’s board.

recentChatWindowCache.ts retains up to eight settled persisted message windows within a 16 MiB payload budget. A matching authenticated selection can seed ActiveChat on its first render or publish an in-place selection before the route metadata and canonical IndexedDB reads finish. The composer waits for canonical ownership and draft context; cached history remains visible during that wait. Message mutations invalidate the snapshot and let a pending read retry; account, team, or key revocation clears the early plaintext and rejects its old completion. Public, anonymous, incognito, draft-only, and streaming content do not enter this recent-window path. Existing encrypted IndexedDB chat storage remains canonical; these additional decrypted projections stay in memory.

Workflows use the existing workspace store. Detail publication proceeds independently of run history, and background refresh preserves dirty editor state. A clean editor adopts refreshed graphs, including after a pending node draft closes. An unknown deep link verifies the list before treating the Workflow as missing, even when the cached list is empty. Native hash events and SvelteKit URL updates both keep the root workspace selection current. See the navigation cache Plan for scope and verification evidence.

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.