System architecture
The FlowOS services, the stores they share and the external systems they call, with the direction of each call.
FlowOS is five services around two shared stores. The web app reaches data only through the API. Mail and the worker never call each other directly: they share rows in Postgres and jobs in Redis.
- Web renders the screens and signs users in through Microsoft Entra. It holds no database access and calls the API over HTTP.
- API verifies each request’s token, establishes the request context and applies office scoping to every query. It sends mail through Microsoft Graph, adds jobs to the queue for an enquiry entered by hand, and asks the units service to convert figures.
- Mail is the only service that reads Microsoft 365 mailboxes. It polls Graph for changes, stores raw mail in mail storage and its rows in Postgres, then adds a processing job. It runs as exactly one instance.
- Worker takes those jobs from Redis, reads the stored mail, and saves its results to Postgres. It calls the units service for conversions and the language models, through the AI gateway, for classification and reading. The queues and the steps are on Mail to processing and Worker jobs.
- Units is a stateless Python service for unit conversion. It has no database, queue or credentials.
- Postgres holds every fact that must survive a restart.
- Redis carries BullMQ jobs, which hold identifiers and never state.
- Mail storage holds raw messages and attachments, in an S3 bucket or a local folder.
The services share the packages db, auth, queue, catalogue, shared and config. Every Node service starts through flowos-secrets, which loads its secrets from Heizen Studio. How the parts are deployed is on Deployment.
