Architecture
A high-level, developer-facing look at how Selyf is put together — without exposing operational detail that would only be useful to someone trying to attack it.
For the full technical detail behind each section below, see API Reference, Security, and Privacy & Data Usage.
System overview
Selyf is a modular monolith, not a microservice mesh: one web application, one API service, one PostgreSQL database, and two external dependencies it talks to on a user's behalf — the Gmail API and a configured AI provider.
Request flow
The browser talks only to the API service, over HTTPS, from the web app’s own origin. The API validates the session, reads and writes data scoped to that session’s account, and — only when a user explicitly asks — calls the Gmail API or the AI provider. The web app never talks to the database or to Gmail directly.
Authentication model
Google OAuth 2.0 Authorization Code flow, minimum scopes, an encrypted refresh token, and a single encrypted session cookie — see Authentication for the full model and endpoint list.
Gmail data flow
Read-only metadata sync in bounded batches; full message bodies are fetched only for a thread a user actually opens; live updates arrive through a pull subscription rather than an inbound webhook — see Gmail integration.
AI processing flow
AI calls happen only on explicit request, are cached so a message is never re-analyzed, and treat email content strictly as data rather than instructions — see AI analysis & drafting.
Data isolation
Every database query used to serve a request is scoped to that request’s own authenticated account at the query layer itself. There is no request shape that can address another account’s data — isolation is a property of how queries are built, not a check applied after the fact.
Security boundaries
The read-only Gmail scope is enforced by Google, independent of application code. Sign-in and Gmail-notification access use two separate Google credentials, so a compromise of one cannot be used to impersonate the other. Cross-origin requests are restricted to the web app’s own configured origin, every route is rate-limited, and error responses are drawn from a small, fixed set of generic codes rather than surfacing internal detail — see Security, Errors, and Rate Limits for the full detail.
Privacy model
Message bodies are cached only for threads a user actively opens, not fetched in bulk. Disconnecting revokes Gmail access immediately; deleting an account removes the account and its data immediately and irreversibly — see Privacy & Data Usage.
Status & health architecture
A lightweight health check aggregates database, Gmail, and AI-provider reachability into one status. Selyf's status page is deployed as a fully independent surface, so it stays reachable even during an incident affecting the main API — see Status.
Deployment topology
Three independently deployable surfaces — the public web app, the API service, and the status page — each served from its own subdomain. Only the API service has direct access to the database, Gmail, and the AI provider; the other surfaces never do. This documentation site is a fourth, equally independent surface, with no access to any of the others.