← All projects
Alpha 2025

Swae OS

An agentic Health OS on a federated microservices backbone

Seven FastAPI services behind one federated GraphQL supergraph, shipped to GCP Cloud Run by a dependency-ordered CI/CD pipeline

One-Pager Slides

Screenshots

Swae landing page, a health platform for coaches and clients

Results

Federated GQL

One typed API

Each capability is a thin, composable agent skill the gateway exposes, not a classical service baked into a single monolith.

Extensible

Skills, not rewrites

A new service joins the supergraph and its capabilities appear at the same endpoint, so the client, and any agent driving it, gains new powers without new wiring.

Isolated

Per-user at the database

Row-level security enforces access at Postgres itself, so a leaked or misrouted query still cannot read another user's rows.

Swae started as an AI personal-performance app: journal entries and curated knowledge feeding RAG-based coaching. The current work is a refactor of that premise.

It is becoming a federated backend mesh behind one GraphQL gateway, a universal interface where each capability (journaling, workout capture, meal capture, the strength-programming engine) is a thin, composable agent skill the gateway exposes, not a service baked into a single monolith.

The backend currently comprises seven FastAPI microservices, one per domain:

  • agent: the AI plane, running LangGraph flows and hybrid RAG over your own data.
  • journal: structured and freeform journaling, indexed for retrieval.
  • habits: habit definitions and the daily tracking against them.
  • meals: meal capture and nutrition.
  • movements: the exercise library, each movement with its own constraints.
  • practices: workouts, the logged training sessions themselves.
  • users: accounts, profiles, and identity.

A GraphQL supergraph, composed by mesh-compose and served by Hive Gateway, stitches them into a single typed API.

The Expo mobile app queries one endpoint over Apollo Client and never learns how many services sit behind it.

That indirection is the payoff. A new service joins the supergraph and its capabilities appear at the same endpoint, so the client, and any agent driving it, gains new powers without new wiring.

The domains do not want the same shape. Workout logging is write-heavy; knowledge retrieval is read-heavy and latency-sensitive. Federation lets each service choose its own storage, scaling, and deploy cadence instead of forcing one mold on all of them.

For Engineers

Architecture

Swae OS architecture diagram

Seven FastAPI services sit behind a Hive Gateway supergraph, composed from each service's subgraph by mesh-compose. The agent service carries the AI plane, covered below; the other six own a single domain each. Every service exposes a /health endpoint, follows a repository pattern over its data layer, and runs async end to end.

Storage follows the service boundaries. Movements, practices, and users each get an isolated Postgres instance with its own schema. Agent, journal, habits, and meals share a main database. Qdrant stores embeddings for hybrid retrieval, and Redis backs Celery for async indexing work that should not block a request. Supabase handles auth, and row-level security policies enforce per-user isolation at the database itself, so a leaked or misrouted query still cannot read another user's rows.

All of it is OpenTofu. Cloud Run services, Secret Manager, IAM, and the gateway are declared as code with GCS-backed remote state, parameterized per environment: staging on one GCP project, production on another.

What Was Hard

The gateway's supergraph is only valid once the services it composes are deployed and healthy, so ordering carried real weight. The workflow_run chain encodes that dependency directly, gating each step on the previous one's success rather than guessing with sleeps. Federation adds a second discipline: it pushes back the moment two domains reach for the same field, so deciding what belongs to which service, and what the gateway composes versus what stays internal, stayed an ongoing call as features grew.

The deployment pipeline

Splitting a backend into seven services only pays off if shipping them stays cheap. That is where most of the engineering went: making seven services as cheap to ship as one.

Swae deploys through twelve GitHub Actions workflows arranged as a workflow_run dependency chain, so a push turns into a deployment without anyone babysitting it.

Swae CI/CD pipeline: a workflow_run chain of build, OpenTofu apply, and gateway deploy, each authenticating to GCP through Workload Identity Federation, with the gateway gated on healthy services

A push to the staging branch starts the chain. The build workflow runs a change-detection script that diffs the push and selects only the services that actually changed, then builds those images across a matrix and pushes them to Artifact Registry.

When it finishes green, GitHub fires the next workflow on its workflow_run completion event. That one runs tofu plan and tofu apply against GCS-backed remote state to roll the new revisions onto Cloud Run. Its success triggers the gateway workflow, which recomposes the supergraph and redeploys Hive Gateway, but only after the services it depends on report healthy. A final workflow publishes the gateway revision.

Two details carry most of the weight. First, authentication: every stage talks to GCP through Workload Identity Federation, exchanging a GitHub OIDC token for a short-lived, scoped credential. There is no service-account key stored anywhere, so there is nothing to leak and nothing to rotate.

Second, ordering: the chain encodes the real dependency between services and the gateway. The supergraph is only valid once its subgraphs exist, so gating the gateway deploy on healthy services prevents the classic federation failure where the router advertises a schema its backends cannot answer.

Production mirrors the same chain off the main branch, scoped to a separate GCP project, with a manual approval gate before apply. The promotion path from a laptop to staging to production is the same shape every time. That is the property you actually want when you are the one on call for it.

The AI plane

The agent service is where retrieval and reasoning live. It runs a set of LangGraph graphs (chat, journal, and review flows) over a hybrid RAG pipeline: embeddings in Qdrant, plus structured pulls from the other domain services through typed clients. Vision and NLP handlers process uploaded images and free text into something the graphs can use. The retrieval step is isolated behind a single seam, currently served by Qdrant.

Where We’re Going

The gateway makes the next step small. Turning Swae into an agentic Health OS takes two passes: first a conversation layer that sits in front as a client, then a set of skills that let it read and write Swae through the same typed supergraph every other client already uses. The first pass is in progress.

Stack

FastAPI GraphQL Federation (Hive) mesh-compose Next.js 15 React Native (Expo) Apollo Client Postgres + RLS Qdrant Celery + Redis LangGraph Supabase Auth OpenTofu GCP Cloud Run GitHub Actions (WIF) Docker