System architecture

Buzzio is a Flutter client backed by Firebase for auth/ops/relay, Cloud Functions for privileged delivery and product logic, and Cloudflare/Bunny for shared-history media and open-history storage.

This page is an explanation of the system shape. Exact path schemas belong in reference pages as they stabilize for public docs.

High-level diagram

┌─────────────────────────────────────────────────────────────┐
│ Flutter client                                              │
│  features/*  ·  services/*  ·  core/crypto  ·  SQLCipher    │
│  Secure Storage (mnemonic, keys, Buzzio ID)                 │
└───────────────┬───────────────────────┬─────────────────────┘
                │                       │
     ┌──────────▼──────────┐   ┌────────▼─────────┐
     │ Firebase Auth       │   │ FCM (wake-only    │
     │ App Check · Analytics│   │ on sealed paths) │
     └──────────┬──────────┘   └────────┬─────────┘
                │                       │
     ┌──────────▼───────────────────────▼─────────┐
     │ Cloud Functions (asia-southeast1)          │
     │  push · retention · sealed_sender · QR     │
     │  billing · vault · username · communities  │
     └──────────┬───────────────────┬─────────────┘
                │                   │
     ┌──────────▼────────┐  ┌───────▼──────────────┐
     │ Realtime Database │  │ Firestore            │
     │ pending_chats     │  │ users, profiles,     │
     │ qr_chats, signals │  │ communities, OHG,    │
     │ sealed_controls   │  │ Whisper Questions,   │
     │ presence, calls   │  │ subscriptions, etc.  │
     └───────────────────┘  └───────┬──────────────┘
                                    │
              ┌─────────────────────┼─────────────────┐
              │                     │                 │
     ┌────────▼────────┐  ┌─────────▼──────┐  ┌──────▼──────┐
     │ Cloudflare R2   │  │ Bunny CDN      │  │ Firebase    │
     │ + history Worker│  │ (shared media) │  │ Storage     │
     │ (OHG history)   │  │                │  │             │
     └─────────────────┘  └────────────────┘  └─────────────┘

Client responsibilities

Layer	Responsibility
UI features	Chat, communities, Whisper, profile, wallet, etc.
Services	Messaging orchestration, RTDB, sealed sender, receipts, secure mode
Crypto core	X3DH, Double Ratchet, sender keys, sealed envelopes, media chunk crypto
Local DB	SQLCipher message/history store
Secure storage	Mnemonic, identity keys, Buzzio ID

Heavy crypto work may run in isolates. Hardware-accelerated AES-GCM is preferred where available for sender-key and media paths.

Why Cloud Functions mediate sealed delivery

Firebase Realtime Database security rules cannot verify ECDSA/HMAC sender certificates cryptographically the way a custom server would. Unidentified / sealed delivery is therefore Cloud Function–mediated:

Client authenticates to Firebase Auth.
Client obtains a short-lived SenderCertificate (issueSenderCertificate).
Client seals the inner message to the recipient identity key.
Client calls deliverSealedMessage.
Function enforces blocks, rate limits, freemium gates from verified identity.
Function writes pending_chats/... with from: "sealed" (clients cannot forge this field under rules).
Function sends FCM wake without sender_id.

This is the architectural adaptation of Signal-style sealed sender to a Firebase stack.

Data store split

Store	Typical content	Privacy note
RTDB	Pending sealed inbox, QR chats, presence, call signaling, sealed controls	Transient / operational for sealed paths
Firestore	Profiles, usernames, communities, OHG metadata, Whisper Questions, billing entitlements	Product state; shared surfaces denser
SQLCipher (device)	Readable private chat history	Primary sealed history
R2	Open-history group payloads	Shared mode
Bunny	Community / broadcast / OHG media (planned: CDN bytes + content-hash dedup); Stories media (client-encrypted)	Shared mode

Push notifications

On sealed 1:1 preferred path, FCM is wake-only:

Payload identifies that a sealed message exists (message_id, sealed: 1)
Does not carry message body or plaintext sender id
Client fetches/opens the sealed envelope from RTDB, then Double Ratchet decrypts

Legacy plaintext-from writes are cut over (allowLegacyFallback = false). Non-sealed inbox junk is ignored and deleted.

Regional and operational notes

Cloud Functions region: asia-southeast1 (as deployed for this product)
Analytics: Firebase Analytics for product operation — not an ads sales channel
App Check: reduces anonymous API abuse against callables and backends