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

Registry and schema workflow

Publish subgraphs to the GraphQL CDN and refresh the frontend client schema

The GraphQL CDN is the registry of the graph's schema. The Cosmo router control plane composes the graph and updates it, and the Cosmo router reads it to learn which subgraphs exist. Studio is where you inspect the result. See AxonMundi onboarding for the URLs.
A successful composition means the registry has a valid graph configuration. It does not prove a service is healthy or that a new client surface is deployed. Producers deploy compatible services before publishing a schema, then verify the composition and router telemetry afterward.
Routing URLs
The router needs a URL for each subgraph. The dev router takes subgraph URLs from the registry (confirmed by Niklaus Buskirk on Nov 2), so the --routing-url you publish is the one it uses. It must be reachable from the dev router in carbyne-dev-eu-west-1. Which address form works (for example an in-cluster service name or an internal load balancer) is not yet verified.
See also: Unified GraphQL Developmentopens in a new tab (Notion, owned by Niklaus Buskirk) for router and infra architecture and status.
Refresh the frontend schema
@prepared911/data-gql vendors the composed client schema so code generation and mocks do not depend on a running router. The normal refresh fetches the latest valid schema from axonmundi/default:
  1. Copy .env.wgc.example to the untracked .env.wgc file and load it:
  2. Log in with the Keycloak device flow (realm cosmo). Whether it signs in with Okta, and whether the control plane needs the VPN, is not yet verified. The dev router itself needs no VPN:
  3. Refresh the schema, regenerate dependent types, and check the committed copy:
    pnpm schema:sync:check compares the committed copy without writing. It must print matches Cosmo registry.
pnpm schema:login is a personal login session. Do not run it for another person or substitute a CI API key. Neither COSMO_API_URL nor COSMO_API_KEY belongs in a local file you commit, a repository variable, or a log.
Sync only from the registry
Refresh the vendored schema only with pnpm schema:sync against the Cosmo registry, as above. Do not sync axon911-frontend's schema from a local AxonMundi checkout (AXONMUNDI_DIR) or a hand-picked file (SCHEMA_SOURCE), and never edit packages/data-gql/src/schema.graphql by hand.
If a subgraph change is not in the registry yet, wait for its owner to publish it. See Publish a subgraph.
Publish a subgraph
Note for frontend developers: You do not need to run these commands or publish subgraphs. This section is for backend service owners.
A service defines its GraphQL schema (*.graphqls) and exposes a GraphQL or gRPC endpoint. Publishing uploads the schema, and an optional gRPC mapping, to the registry, which tells the router to serve the subgraph.
For now, publish by hand with wgc from your service's repository. CI/CD comes later. These steps are not yet verified end to end against the dev router.
  1. Log in with the Keycloak device flow, as above:
  2. Set the subgraph name and the URL the dev router can reach:
    The dev router uses this URL; see Routing URLs.
  3. Check the schema. This changes nothing:
  4. Publish. This stops if the composition fails:
  5. For an event subgraph (EDFS), publish its owner first. Then create the event subgraph, and publish it with no --routing-url:
  6. Sync axon911-frontend. The last command must print matches Cosmo registry:
Watch out
  • publish never changes an existing subgraph's URL or labels. Use wgc subgraph update for that.
  • Publish the owner before its EDFS subgraph, or the EDFS check fails.
  • A router below 0.335.0 fails to start once an EDFS subgraph is in the graph. Never roll a router back below 0.335.0 while an EDFS subgraph is published. Delete it first with wgc subgraph delete <name>-edfs -n default.
  • Kafka providers live in router config, not in the registry.
  • A new registry owned from git is planned. Subgraphs will be republished from git, so set URLs correctly now.
For generated-code requirements, CI credential setup, and rollback details, use the subgraph CI and registry publication runbookopens in a new tab. These runbooks are not yet updated for the GraphQL CDN.
Next steps
  • Use Cosmo Studio to inspect the composition and client schema.
  • GraphQL development workflow for writing and regenerating frontend operations.
  • Real-time data and WebSockets before adding a subgraph that needs live updates.
  • Add a subgraphopens in a new tab for new graph participants.
Previous
AxonMundi / Use Cosmo Studio
Next
AxonMundi / Real-time data and WebSockets
On this page
Routing URLs
Refresh the frontend schema
Sync only from the registry
Publish a subgraph
Watch out
Next steps