Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Working With Data
  3. Axonmundi
  5. Getting Started

AxonMundi onboarding

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. For the full platform and operator documentation, start with the AxonMundi repository. Architecture and infra status: Unified GraphQL Development (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
ComponentWhat it doesDev URL
Cosmo routerStateless API gateway that serves frontends and proxies the graph to backendshttps://eu-west-1-cosmo-router-dev.carbyneapi-dev.com/graphql
GraphQL CDNStatic registry of the graph's schema (see Routing URLs)https://graphql-cdn.prepared911.dev
Cosmo StudioDeveloper platform for inspecting the graph, compositions and checkshttps://studio.prepared911.dev
Cosmo router control planeReceives metrics, manages routers, composes the graph and updates the CDNhttps://cosmo.prepared911.dev
NATSPub/sub that fans subscription events out across routers (EDFS, Cosmo Streams). The dev router runs it from its own chart, with no MSKInternal
How a request flows
  1. 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.
  2. The router enforces authentication at the edge with Keycloak JWKS. Only an authenticated token reaches the backends.
  3. The router proxies the request to the subgraph. The subgraph sees the user's JWT, authorizes the user, and fulfils the request.
  4. 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.
To try the dev router from a local responder, see Test against the dev router.
Choose your starting point
  • 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.
  • Subgraph owner: use Studio to inspect checks and compositions, then follow the AxonMundi add a subgraph and subgraph CI runbooks in the owning service repository. Those runbooks are not yet updated for the GraphQL CDN.
  • Anyone adding or consuming live data: read Real-time data and WebSockets.
  • Anyone testing against the dev router: read Test against the dev router.
Access and credentials
These credentials have different purposes. They are not interchangeable.
Credential or sessionWhat it authorizesWhere it belongs
Studio SSOStudio featuresYour browser session
wgc auth loginA human's interactive CLI administration session (Keycloak device flow)Your local terminal after loading .env.wgc
Carbyne Keycloak access tokenAn end-user request to the Cosmo router and its subgraphsAn ephemeral Authorization request header
COSMO_API_KEYNon-interactive schema fetch and check; CI publication is plannedThe approved CI secret store only
GRAPH_API_TOKENRouter access to the Cosmo control plane and CDNThe 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.
Next steps
  • Use Cosmo Studio to inspect the graph and safely run a query.
  • Registry and schema workflow to update frontend types from the composed client schema.
  • Real-time data and WebSockets for live updates through the router.
  • Test against the dev router to call the dev router with a real token.
  • GraphQL overview for frontend operation and codegen conventions.
Previous
Working with data / Local Storage
Next
AxonMundi / Use Cosmo Studio
On this page
Status
Components
How a request flows
Authentication
What works today
Choose your starting point
Access and credentials
Frontend schema
Next steps