# mrxsin/xax architecture

> Architecture diagram of the GitHub repository mrxsin/xax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrxsin/xax
- Repository: https://github.com/mrxsin/xax

## Overview

XAX is a research-prototype compiler for programs represented as verified semantic graphs rather than text. Its principal workflow is an AI-authored semantic edit, verification and compilation, then generation of a target artifact. The repository also supports carrier decoding, workspace transactions, graph rendering and numerous platform backends. The map follows the README and the supplied source index; connections to unsampled backends are omitted unless documented, so it does not claim to trace every build path.

Main entry points: [`compiler/reference/xax_compiler.py`](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_compiler.py) (Compiler and store), [`compiler/reference/xax_build.py`](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_build.py) (Build service), [`compiler/reference/xax_workspace.py`](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_workspace.py) (Workspace queries), [`compiler/src/xax_selfhost_verify.py`](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_verify.py) (Store verifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and transactions"]
  node_carrier["Carrier reader<br/>[reader.py]"]
  node_resolver["Carrier resolver<br/>[resolve.py]"]
  node_workspace["Workspace queries<br/>[xax_workspace.py]"]
  node_transactions["Semantic edits"]
end

subgraph group_semantics["Semantic compiler"]
  node_structured["Graph construction<br/>[xax_structured.py]"]
  node_compiler["Compiler and store<br/>[xax_compiler.py]"]
  node_typing["Operation typing"]
  node_facts["Memory facts"]
  node_cfg["Control flow"]
  node_verifier["Store verifier"]
  node_diagnostics["Diagnostics"]
  node_render["Graph rendering"]
end

subgraph group_runtime["Native execution"]
  node_native["Native image runner<br/>[xax_native.py]"]
end

subgraph group_build["Build and artifacts"]
  node_build["Build service<br/>[xax_build.py]"]
  node_workspace_store["Artifact provenance<br/>[xax_artifact.py]"]
end

subgraph group_targets["Target backends"]
  node_linux["Linux backend<br/>[xax_linux.py]"]
  node_x86["x86-64 backend<br/>[xax_x86_64.py]"]
  node_aarch64["AArch64 backend<br/>[xax_aarch64.py]"]
  node_riscv["RISC-V backend<br/>[xax_riscv64.py]"]
  node_jvm["JVM backend<br/>[xax_jvm.py]"]
  node_dex["DEX backend<br/>[xax_dex.py]"]
end

node_ai(("AI agent"))

node_ai -->|"submits edit"| node_transactions
node_transactions -->|"verifies store"| node_compiler
node_ai -->|"queries graph"| node_workspace
node_carrier -->|"decodes carriers"| node_resolver
node_resolver -->|"builds objects"| node_compiler
node_structured -->|"uses compiler"| node_compiler
node_compiler -->|"invokes typing"| node_typing
node_compiler -->|"uses facts"| node_facts
node_compiler -->|"uses control flow"| node_cfg
node_compiler -->|"verifies store"| node_verifier
node_compiler -->|"reports errors"| node_diagnostics
node_render -->|"uses facts"| node_facts
node_render -->|"verifies input"| node_verifier
node_native -->|"runs image"| node_verifier
node_build -->|"compiles graph"| node_compiler
node_build -->|"records provenance"| node_workspace_store
node_workspace -->|"uses compiler"| node_compiler
node_workspace -->|"uses provenance"| node_workspace_store
node_build -.->|"builds target"| node_linux
node_build -.->|"builds target"| node_x86
node_build -.->|"builds target"| node_aarch64
node_build -.->|"builds target"| node_riscv
node_build -.->|"builds target"| node_jvm
node_build -.->|"builds target"| node_dex

click node_carrier "https://github.com/mrxsin/xax/blob/main/compiler/integration/construct/reader.py"
click node_resolver "https://github.com/mrxsin/xax/blob/main/compiler/integration/construct/resolve.py"
click node_workspace "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_workspace.py"
click node_transactions "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_edit.py"
click node_structured "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_structured.py"
click node_compiler "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_compiler.py"
click node_typing "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_typing.py"
click node_facts "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_facts.py"
click node_cfg "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_cfg.py"
click node_verifier "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_verify.py"
click node_diagnostics "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_diagnostics.py"
click node_render "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_render.py"
click node_native "https://github.com/mrxsin/xax/blob/main/compiler/src/xax_native.py"
click node_build "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_build.py"
click node_workspace_store "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_artifact.py"
click node_linux "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_linux.py"
click node_x86 "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_x86_64.py"
click node_aarch64 "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_aarch64.py"
click node_riscv "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_riscv64.py"
click node_jvm "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_jvm.py"
click node_dex "https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_dex.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_carrier,node_resolver,node_workspace,node_transactions toneBlue
class node_structured,node_compiler,node_typing,node_facts,node_cfg,node_verifier,node_diagnostics,node_render toneAmber
class node_native toneMint
class node_build,node_workspace_store toneRose
class node_linux,node_x86,node_aarch64,node_riscv,node_jvm,node_dex,node_ai toneIndigo
```

## Components

### Authoring and transactions

- [Carrier reader](https://github.com/mrxsin/xax/blob/main/compiler/integration/construct/reader.py): `compiler/integration/construct/reader.py`
- [Carrier resolver](https://github.com/mrxsin/xax/blob/main/compiler/integration/construct/resolve.py): `compiler/integration/construct/resolve.py`
- [Workspace queries](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_workspace.py): `compiler/reference/xax_workspace.py`
- [Semantic edits](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_edit.py): `compiler/src/xax_selfhost_edit.py`

### Semantic compiler

- [Graph construction](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_structured.py): `compiler/reference/xax_structured.py`
- [Compiler and store](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_compiler.py): `compiler/reference/xax_compiler.py`
- [Operation typing](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_typing.py): `compiler/src/xax_selfhost_typing.py`
- [Memory facts](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_facts.py): `compiler/src/xax_selfhost_facts.py`
- [Control flow](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_cfg.py): `compiler/src/xax_selfhost_cfg.py`
- [Store verifier](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_verify.py): `compiler/src/xax_selfhost_verify.py`
- [Diagnostics](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_diagnostics.py): `compiler/src/xax_selfhost_diagnostics.py`
- [Graph rendering](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_selfhost_render.py): `compiler/src/xax_selfhost_render.py`

### Native execution

- [Native image runner](https://github.com/mrxsin/xax/blob/main/compiler/src/xax_native.py): `compiler/src/xax_native.py`

### Build and artifacts

- [Build service](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_build.py): `compiler/reference/xax_build.py`
- [Artifact provenance](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_artifact.py): `compiler/reference/xax_artifact.py`

### Target backends

- [Linux backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_linux.py): `compiler/reference/xax_linux.py`
- [x86-64 backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_x86_64.py): `compiler/reference/xax_x86_64.py`
- [AArch64 backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_aarch64.py): `compiler/reference/xax_aarch64.py`
- [RISC-V backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_riscv64.py): `compiler/reference/xax_riscv64.py`
- [JVM backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_jvm.py): `compiler/reference/xax_jvm.py`
- [DEX backend](https://github.com/mrxsin/xax/blob/main/compiler/reference/xax_dex.py): `compiler/reference/xax_dex.py`

### Other components

- **AI agent**

## Connections

- AI agent → Semantic edits: submits edit (evidence: `README.md`)
- Semantic edits → Compiler and store: verifies store (evidence: `compiler/src/xax_selfhost_edit.py`)
- AI agent → Workspace queries: queries graph (evidence: `README.md`)
- Carrier reader → Carrier resolver: decodes carriers (evidence: `compiler/integration/construct/resolve.py`)
- Carrier resolver → Compiler and store: builds objects (evidence: `compiler/integration/construct/resolve.py`)
- Graph construction → Compiler and store: uses compiler (evidence: `compiler/reference/xax_structured.py`)
- Compiler and store → Operation typing: invokes typing (evidence: `compiler/reference/xax_compiler.py`)
- Compiler and store → Memory facts: uses facts (evidence: `compiler/reference/xax_compiler.py`)
- Compiler and store → Control flow: uses control flow (evidence: `compiler/reference/xax_compiler.py`)
- Compiler and store → Store verifier: verifies store (evidence: `compiler/reference/xax_compiler.py`)
- Compiler and store → Diagnostics: reports errors (evidence: `compiler/src/xax_selfhost_diagnostics.py`)
- Graph rendering → Memory facts: uses facts (evidence: `compiler/src/xax_selfhost_render.py`)
- Graph rendering → Store verifier: verifies input (evidence: `compiler/src/xax_selfhost_render.py`)
- Native image runner → Store verifier: runs image (evidence: `compiler/src/xax_native.py`)
- Build service → Compiler and store: compiles graph (evidence: `compiler/reference/xax_build.py`)
- Build service → Artifact provenance: records provenance (evidence: `compiler/reference/xax_artifact.py`)
- Workspace queries → Compiler and store: uses compiler (evidence: `compiler/reference/xax_workspace.py`)
- Workspace queries → Artifact provenance: uses provenance (evidence: `compiler/reference/xax_workspace.py`)
- Build service → Linux backend: builds target (evidence: `compiler/reference/xax_build.py`)
- Build service → x86-64 backend: builds target (evidence: `compiler/reference/xax_build.py`)
- Build service → AArch64 backend: builds target (evidence: `compiler/reference/xax_build.py`)
- Build service → RISC-V backend: builds target (evidence: `compiler/reference/xax_build.py`)
- Build service → JVM backend: builds target
- Build service → DEX backend: builds target (evidence: `compiler/reference/xax_build.py`)
