Get oriented to the Cosmo router, the GraphQL CDN, and Studio
AxonMundi is the project name for Axon 911's federated GraphQL graph. Services
bring their own GraphQL APIs (subgraphs), and the Cosmo router serves them to
frontends as one graph.
Architecture and infra status: Unified GraphQL Developmentopens in a new tab
(Notion, owned by Niklaus Buskirk). The facts these docs depend on are written
here, so you do not need Notion to follow them.
Status
Only the dev environment exists. Stage, QA and production are not deployed.
The dev router is the one dev GraphQL endpoint for the frontend. It needs no
VPN.
The console under the Unified login and the responder (Keycloak by default)
call the router with a Keycloak token. See
What works today.
Components
Component
What it does
Dev URL
Cosmo router
Stateless API gateway that serves frontends and proxies the graph to backends
Static registry of the graph's schema (see Routing URLs)
https://graphql-cdn.prepared911.dev
Cosmo Studio
Developer platform for inspecting the graph, compositions and checks
https://studio.prepared911.dev
Cosmo router control plane
Receives metrics, manages routers, composes the graph and updates the CDN
https://cosmo.prepared911.dev
NATS
Pub/sub that fans subscription events out across routers (EDFS, Cosmo Streams). The dev router runs it from its own chart, with no MSK
Internal
How a request flows
The router reads which subgraphs exist from the GraphQL CDN, and routes
each one to its service. For example, queries for yourStuff route to
http://your-service.namespace/graphql. The dev router takes these URLs from
the registry; see Routing URLs.
The router enforces authentication at the edge with Keycloak JWKS. Only an
authenticated token reaches the backends.
The router proxies the request to the subgraph. The subgraph sees the user's
JWT, authorizes the user, and fulfils the request.
For events, a service POSTs the event (for example
yourStuffUpdated(id:)) to its local router. The router publishes it through
NATS to fan out to the other routers, and handles fan-out and authorization.
Services do not connect to NATS directly. See
Real-time data and WebSockets.
Authentication
The router accepts only Carbyne Keycloak JWTs with the prepared-claims claim
and prepared_user_id. A Doorkeeper token gets a 401. This is not yet verified
end to end. To get one, sign in with Keycloak, not Okta, on the auth host's
client=axon-proto; see Test against the dev router.
What works today
The responder signs in with Keycloak by default and sends that token to the
router when GRAPHQL_ROUTER_URL is set; its example config sets the dev
router's URL. ?auth=prepared selects the Doorkeeper login, whose token the
router refuses with a 401. The responder refreshes the session once per
rejected access token and then leaves the error as it is.
The responder's checked-in apps/responder/public/config/appConfig.json is
empty, so it does not set GRAPHQL_ROUTER_URL. A deployed shell gets the
router URL from the build-time VITE_GRAPHQL_ROUTER_URL instead; see
Where the router URL comes from.
The console creates an Apollo client for the router URL (runtime
GRAPHQL_ROUTER_URL, else build-time VITE_GRAPHQL_ROUTER_URL) when it is set,
but no console screen runs a query against it. It sends a Keycloak token only
under the Unified login. The Core and Intelligence logins send a Prepared
token, which the router refuses.
Frontend developer: read Registry and schema workflow
to refresh @prepared911/data-gql from the composed client schema. Then follow
the existing GraphQL guides for operations and code generation.
These credentials have different purposes. They are not interchangeable.
Credential or session
What it authorizes
Where it belongs
Studio SSO
Studio features
Your browser session
wgc auth login
A human's interactive CLI administration session (Keycloak device flow)
Your local terminal after loading .env.wgc
Carbyne Keycloak access token
An end-user request to the Cosmo router and its subgraphs
An ephemeral Authorization request header
COSMO_API_KEY
Non-interactive schema fetch and check; CI publication is planned
The approved CI secret store only
GRAPH_API_TOKEN
Router access to the Cosmo control plane and CDN
The router runtime Secret only
Do not save, share, commit, or paste tokens into documentation, PRs, tickets,
or long-lived Studio Playground sessions. If Studio login or the CLI device flow
does not work, contact the Studio or Platform owner instead of using a shared
credential.
Frontend schema
Frontends sync the schema only from the registry's composed client schema,
with pnpm schema:sync, never from a local AxonMundi checkout. See
Sync only from the registry.