Use your existing stack

You can adopt AxiomCore without a rewrite. Extract a contract (the .axiom artifact that describes your API's endpoints, models, validation and errors) from the backend you already run, generate a client for the frontend you already have, and review every contract change before release. Extraction reads a supported backend and produces the Acore declarations the contract is built from. Acore is optional at each layer.

Diagram source

flowchart TD
  BE[Existing FastAPI or Go backend] --> EX[Extraction]
  EX --> SRC[axiom.acore]
  AB[Optional Acore backend source] -.-> SRC
  SRC --> C[.axiom contract]
  C --> GEN[axiom pull generates a client]
  GEN --> FE[Existing web, React or Flutter frontend]
  C -.-> AU[Optional Acore UI]
  C --> CI[Semantic diff and tests in CI]
  DB[Existing database and migrations] --- BE
  AD[Optional Acore database contract] -.-> DB

Your backend keeps serving requests and your database keeps its migrations. The CLI builds the contract from the extracted surface plus any Acore in axiom.acore; axiom pull turns it into a client; CI compares each new contract with the last accepted one. Dashed lines are optional moves to Acore.

Choose a starting point

Framework support comes from the support matrix, not from the portability of the contract alone.

Decide who owns each fact

Record which input owns each fact before you generate anything, so generated Acore and your framework never become two authorities for one route or model. Use extend, an explicit policy or a reviewed projection only for facts Acore is meant to own.

Adopt one boundary at a time

Start with one service, one audience and one consumer you can verify.

1. Diagnose. axiom doctor reports prerequisites without changing files (add --json --strict in CI). axiom onboard detects the repository's role and prints a plan; it writes axiom.acore only with --apply and pulls a client only with --contract.
2. Build a local proof. Run the domain and security checks only if the source declares those optional models. A build proves the source can be evaluated and packaged, not that the backend behaves correctly.

   axiom eval axiom.acore
   axiom domain validate axiom.acore
   axiom security check axiom.acore
   axiom test axiom.acore
   axiom build axiom.acore --out backend.axiom
   axiom inspect overview .

3. Prove one consumer. Pull a client from the local artifact. Start your backend, or axiom serve axiom.acore with a reviewed deployment when the source uses managed or sandboxed actions. Test base URL, CORS, credentials, request validation, error mapping, caching, and one success and one failure.
4. Review changes deterministically. Commit the source with its lock and compare each candidate with the last accepted input: axiom diff previous.acore axiom.acore --format semantic. Review removals, validation, authentication and package dependency changes separately. Never resolve an unpinned latest in the build that creates release evidence.
5. Expand after the boundary is stable. Add a consumer, target or package only after the first path has a repeatable CI gate and a rollback artifact. Moving a frontend to Acore UI is a separate decision, not a prerequisite.

After the first working request, add a CI contract check, review production readiness, and document your failure and recovery paths. For agent-assisted work, see AI coding agents.

Connect an existing frontend

axiom pull accepts a local .axiom file, a URL, an AxiomDeps.toml or JSON config, or an organization/project[/version] release reference. Named targets are atmx-web, atmx-react, flutter and dart.

axiom pull ../backend/backend.axiom --framework atmx-web --out src/generated
axiom pull organization/project/1.2.0 --framework flutter

Pull records the dependency in AxiomDeps.toml under an alias (--name). Commit it with a source that works on other machines. A release build uses the pinned artifact and never falls back to live backend introspection.

[contracts.tasks]
source = "../backend/backend.axiom"

Do not hand-edit generated code into a second schema. Generated APIs differ between ATMX and Flutter or Dart and can change while a target is Alpha. Test runtime startup and an artifact integrity failure, one query and one declared error, authentication headers (no secrets in the contract), cache identity and invalidation, the stream lifecycle where supported, and a release build, not only hot reload. To upgrade, pull the new immutable version, read the semantic diff, run the consumer tests, and commit the change with its lock.

Next steps

• Connect FastAPI to a web client
• Connect Go to a web client
• How extraction works
• Add contract checks to CI