Skip to main content

System Diagrams

Current as of October 2026

These diagrams follow the C4 model: one system landscape showing who and what Mozilla accounts talks to, then one container diagram per part of the platform showing the deployable pieces inside it, then a couple of sequence diagrams for flows that cross several containers. They are plain Mermaid in this Markdown file, so editing a diagram is editing this page. Keep each one small: a container diagram that needs more than a dozen boxes wants to be two diagrams.

Each box names the service as it appears in mozilla/fxa and the external systems come from each service's configuration, so when a service gains or loses a dependency the matching diagram should change in the same PR.

System landscape​

Everything inside the dashed "Mozilla accounts / Subscription Platform" box is one deployable platform from the outside world's point of view. The container diagrams below open it up.

Containers: accounts and authentication​

The core of Mozilla accounts. The content server is an Express app that serves the React UI and a few server-rendered routes; the UI lives in fxa-settings and talks to the auth server directly. See the content-server architecture page for the client side.

Notes:

  • The three logical MySQL databases live in one cluster. fxa holds accounts, sessions, devices and keys; fxa_oauth holds OAuth clients, codes and tokens; pushbox holds queued device commands. Their schemas are drawn on the Database Structure page.
  • Rate limiting is in process, in the @fxa/accounts/rate-limit library backed by Redis. See Rate limiting.
  • Email is rendered and sent from the auth server over SMTP to SES. SES bounces and complaints come back through an SQS queue consumed by the auth server's email_notifications process.

Containers: profile​

The profile server answers GET /v1/profile by combining its own data with account data fetched from the auth server, then caches the result in Redis. The auth server invalidates that cache by posting to the SQS queue whenever an email or other profile-relevant field changes.

Containers: event broker​

Account events (password change, account deletion, subscription state change, and so on) are fanned out to relying parties as Security Event Tokens. The event formats are documented on the Account Events page.

Containers: admin panel​

An internal tool for support staff and FxA admins. It is reachable only over VPN with SSO; nginx verifies the login and passes the user's email and LDAP groups to the admin server as headers, which decide what each user may do.

Containers: Subscription Platform​

Checkout and subscription management are a Next.js app under apps/payments/next, with the business logic in the libs/payments/* libraries. A separate NestJS API under apps/payments/api serves relying parties and the usage-metering pipeline. The auth server still owns the Stripe and in-app purchase webhooks and attaches subscription capabilities to OAuth tokens.

Flow: Send Tab​

How a tab sent from one Firefox reaches another. The auth server stores the encrypted command in the pushbox database and uses Mozilla's push service to wake the target device.

Flow: account event to a relying party​

Editing these diagrams​

Edit the Mermaid blocks on this page and check them with yarn start, or paste a block into mermaid.live for a quicker loop. Mermaid lays diagrams out automatically, so the lever you have is scope: if a diagram gets crowded, split it rather than fighting the layout.