---
title: System architecture
description: The FlowOS services, the stores they share and the external systems they call, with the direction of each call.
sidebar:
  label: System architecture
  order: 0
---

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](/engineering/mail-to-processing) and [Worker jobs](/engineering/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](/engineering/deployment).

[![System architecture: web, API, mail, worker and units around Postgres, Redis and mail storage, with Microsoft 365 and the AI gateway outside](/blume-assets/content/content/engineering/system-architecture-preview.png)](/engineering/system-architecture-diagram)

<a href="/engineering/system-architecture-diagram">Open the interactive diagram</a>