architecture
Standing on a protocol, not a silo
Xoyo doesn’t invent a messaging protocol. It builds on Matrix — an open, federated standard with a decade of hardening behind its encryption — and adds the pieces Matrix deliberately leaves out: phone-first onboarding, push infrastructure, brandable clients, and (later) organizational bridges.
The pieces, and why they’re shaped this way
Synapse — the Matrix homeserver
Rooms, message history, device management, federation, and the E2EE machinery all come from Synapse, the reference Matrix homeserver. We validated it hands-on before committing: multi-device encryption exercised end-to-end, with a direct database check confirming zero plaintext rows server-side.
Xoyo server — the platform layer
An Elixir/Phoenix service that owns what Matrix doesn’t: OTP phone verification, device-token registry and push fan-out, the media pipeline, and background jobs on Oban. It talks to Synapse over the Application Service API — extension, not fork.
Clients — one codebase, any brand
The React web client and the planned React Native mobile client both read a typed brand config (name, icon, splash, colors, bundle IDs). White-labeling is a build input, not a fork — that’s a product decision enforced by the architecture.
The trust boundary is drawn in ink
Our encryption decision record commits to a rule the UI must keep: E2EE applies to direct conversations between Xoyo users, and any room bridged to an external organization is visibly marked. The product never implies blanket encryption where a bridge exists.
Infrastructure as scripts
The whole dev environment — VM, firewall, Postgres, Synapse deploy, storage, CDN — is a sequence of numbered shell scripts in the repo. Deleting the environment and rebuilding it from nothing is a supported operation, not a crisis.
Separate by decision, not accident
Xoyo shares no code or database with any other system — including Glific, which it will one day bridge to. That separation is a recorded architecture decision (our ADR-007), which keeps the bridge honest: it’s an integration, never a backdoor.
Decisions are written down
Every significant call — protocol choice and licensing, the E2EE trust boundary, phone-first auth, platform separation — lives in a numbered, immutable architecture decision record in the repo. Join the project and you inherit the reasoning, not just the code.