# vx-lang/vx architecture

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

- Interactive diagram: https://gitdiagram.com/vx-lang/vx
- Repository: https://github.com/vx-lang/vx

## Overview

Vx is a heterogeneous-systems language and compiler: users submit Vx programs and receive diagnostics, generated code, or JIT execution. The documented path runs through parsing, hardware-aware semantic checks, and code generation; the source index supports the compiler’s internal handoffs. Major language capabilities include placement and capacity checking, transfer reachability and routing, seam contracts, and borrow checking. The tree also shows a runtime for local and remote dispatch. Some implementation details are unsampled, so uncertain runtime connections are omitted.

Main entry points: [`src/pipeline.rs`](https://github.com/vx-lang/vx/blob/main/src/pipeline.rs) (Compile pipeline), [`src/parser/mod.rs`](https://github.com/vx-lang/vx/blob/main/src/parser/mod.rs) (Parser), [`src/main.rs`](https://github.com/vx-lang/vx/blob/main/src/main.rs) (Compiler CLI), [`src/codegen/flat.rs`](https://github.com/vx-lang/vx/blob/main/src/codegen/flat.rs) (Code generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language Front End"]
  node_cli["Compiler CLI<br/>[main.rs]"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["Parser<br/>[mod.rs]"]
  node_ast["Syntax AST<br/>[expr.rs]"]
  node_resolver["Name resolver<br/>[resolver.rs]"]
end

subgraph group_semantic["Hardware Semantics"]
  node_topology["Topology model<br/>[arch.rs]"]
  node_typecheck["HIR checks<br/>[calls.rs]"]
  node_capacity["Capacity admission<br/>[capacity_fold.rs]"]
  node_transfers["Transfer checks<br/>[transfer.rs]"]
  node_seams["Seam contracts<br/>[seam.rs]"]
  node_borrow["Borrow checker<br/>[borrow.rs]"]
end

subgraph group_compile["Compilation"]
  node_pipeline["Compile pipeline<br/>[pipeline.rs]"]
  node_flatten["HIR flattening<br/>[flatten.rs]"]
  node_registry[("Type registry<br/>[registry.rs]")]
  node_codegen["Code generation<br/>[flat.rs]"]
  node_mlir["MLIR lowering<br/>[VxLowering.cpp]"]
end

subgraph group_runtime["Execution Runtime"]
  node_jit["JIT execution<br/>[jit.rs]"]
  node_dispatch["Device dispatch<br/>[cuda_dispatch.cpp]"]
  node_worker["Remote worker<br/>[vx_worker_main.cpp]"]
  node_remote["Remote client<br/>[vx_remote_client.h]"]
  node_wire["Wire protocol<br/>[vx_wire.h]"]
end

node_user(("Vx programmer"))

node_user -->|"submits program"| node_cli
node_cli -->|"compiles"| node_pipeline
node_pipeline -->|"parses modules"| node_parser
node_parser -->|"consumes tokens"| node_lexer
node_parser -->|"builds AST"| node_ast
node_pipeline -->|"resolves names"| node_resolver
node_pipeline -->|"uses topology"| node_topology
node_pipeline -->|"checks program"| node_typecheck
node_pipeline -->|"checks capacity"| node_capacity
node_pipeline -->|"checks transfers"| node_transfers
node_pipeline -->|"checks contracts"| node_seams
node_pipeline -->|"checks ownership"| node_borrow
node_pipeline -->|"flattens HIR"| node_flatten
node_pipeline -->|"builds registry"| node_registry
node_pipeline -->|"generates code"| node_codegen
node_codegen -.->|"lowers to MLIR"| node_mlir
node_user -->|"runs program"| node_jit
node_worker -->|"uses client"| node_remote
node_remote -->|"uses protocol"| node_wire

click node_cli "https://github.com/vx-lang/vx/blob/main/src/main.rs"
click node_lexer "https://github.com/vx-lang/vx/blob/main/src/lexer.rs"
click node_parser "https://github.com/vx-lang/vx/blob/main/src/parser/mod.rs"
click node_ast "https://github.com/vx-lang/vx/blob/main/src/syntax/expr.rs"
click node_pipeline "https://github.com/vx-lang/vx/blob/main/src/pipeline.rs"
click node_resolver "https://github.com/vx-lang/vx/blob/main/src/resolver.rs"
click node_topology "https://github.com/vx-lang/vx/blob/main/src/arch.rs"
click node_typecheck "https://github.com/vx-lang/vx/blob/main/src/hir/check/calls.rs"
click node_capacity "https://github.com/vx-lang/vx/blob/main/src/hir/check/capacity_fold.rs"
click node_transfers "https://github.com/vx-lang/vx/blob/main/src/hir/check/transfer.rs"
click node_seams "https://github.com/vx-lang/vx/blob/main/src/hir/seam.rs"
click node_borrow "https://github.com/vx-lang/vx/blob/main/src/borrow.rs"
click node_flatten "https://github.com/vx-lang/vx/blob/main/src/hir/flatten.rs"
click node_registry "https://github.com/vx-lang/vx/blob/main/src/registry.rs"
click node_codegen "https://github.com/vx-lang/vx/blob/main/src/codegen/flat.rs"
click node_mlir "https://github.com/vx-lang/vx/blob/main/src/dialect/VxLowering.cpp"
click node_jit "https://github.com/vx-lang/vx/blob/main/src/jit.rs"
click node_dispatch "https://github.com/vx-lang/vx/blob/main/runtime/cuda_dispatch.cpp"
click node_worker "https://github.com/vx-lang/vx/blob/main/runtime/vx_worker_main.cpp"
click node_remote "https://github.com/vx-lang/vx/blob/main/runtime/vx_remote_client.h"
click node_wire "https://github.com/vx-lang/vx/blob/main/runtime/vx_wire.h"

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_cli,node_lexer,node_parser,node_ast,node_resolver toneBlue
class node_topology,node_typecheck,node_capacity,node_transfers,node_seams,node_borrow toneAmber
class node_pipeline,node_flatten,node_registry,node_codegen,node_mlir toneMint
class node_jit,node_dispatch,node_worker,node_remote,node_wire toneRose
class node_user toneIndigo
```

## Components

### Language Front End

- [Compiler CLI](https://github.com/vx-lang/vx/blob/main/src/main.rs): `src/main.rs`
- [Lexer](https://github.com/vx-lang/vx/blob/main/src/lexer.rs): `src/lexer.rs`
- [Parser](https://github.com/vx-lang/vx/blob/main/src/parser/mod.rs): `src/parser/mod.rs`
- [Syntax AST](https://github.com/vx-lang/vx/blob/main/src/syntax/expr.rs): `src/syntax/expr.rs`
- [Name resolver](https://github.com/vx-lang/vx/blob/main/src/resolver.rs): `src/resolver.rs`

### Hardware Semantics

- [Topology model](https://github.com/vx-lang/vx/blob/main/src/arch.rs): `src/arch.rs`
- [HIR checks](https://github.com/vx-lang/vx/blob/main/src/hir/check/calls.rs): `src/hir/check/calls.rs`
- [Capacity admission](https://github.com/vx-lang/vx/blob/main/src/hir/check/capacity_fold.rs): `src/hir/check/capacity_fold.rs`
- [Transfer checks](https://github.com/vx-lang/vx/blob/main/src/hir/check/transfer.rs): `src/hir/check/transfer.rs`
- [Seam contracts](https://github.com/vx-lang/vx/blob/main/src/hir/seam.rs): `src/hir/seam.rs`
- [Borrow checker](https://github.com/vx-lang/vx/blob/main/src/borrow.rs): `src/borrow.rs`

### Compilation

- [Compile pipeline](https://github.com/vx-lang/vx/blob/main/src/pipeline.rs): `src/pipeline.rs`
- [HIR flattening](https://github.com/vx-lang/vx/blob/main/src/hir/flatten.rs): `src/hir/flatten.rs`
- [Type registry](https://github.com/vx-lang/vx/blob/main/src/registry.rs): `src/registry.rs`
- [Code generation](https://github.com/vx-lang/vx/blob/main/src/codegen/flat.rs): `src/codegen/flat.rs`
- [MLIR lowering](https://github.com/vx-lang/vx/blob/main/src/dialect/VxLowering.cpp): `src/dialect/VxLowering.cpp`

### Execution Runtime

- [JIT execution](https://github.com/vx-lang/vx/blob/main/src/jit.rs): `src/jit.rs`
- [Device dispatch](https://github.com/vx-lang/vx/blob/main/runtime/cuda_dispatch.cpp): `runtime/cuda_dispatch.cpp`
- [Remote worker](https://github.com/vx-lang/vx/blob/main/runtime/vx_worker_main.cpp): `runtime/vx_worker_main.cpp`
- [Remote client](https://github.com/vx-lang/vx/blob/main/runtime/vx_remote_client.h): `runtime/vx_remote_client.h`
- [Wire protocol](https://github.com/vx-lang/vx/blob/main/runtime/vx_wire.h): `runtime/vx_wire.h`

### Other components

- **Vx programmer**

## Connections

- Vx programmer → Compiler CLI: submits program
- Compiler CLI → Compile pipeline: compiles
- Compile pipeline → Parser: parses modules (evidence: `src/pipeline.rs`)
- Parser → Lexer: consumes tokens (evidence: `src/parser/mod.rs`)
- Parser → Syntax AST: builds AST (evidence: `src/parser/mod.rs`)
- Compile pipeline → Name resolver: resolves names (evidence: `src/pipeline.rs`)
- Compile pipeline → Topology model: uses topology (evidence: `src/pipeline.rs`)
- Compile pipeline → HIR checks: checks program (evidence: `src/pipeline.rs`)
- Compile pipeline → Capacity admission: checks capacity (evidence: `src/pipeline.rs`)
- Compile pipeline → Transfer checks: checks transfers (evidence: `src/pipeline.rs`)
- Compile pipeline → Seam contracts: checks contracts
- Compile pipeline → Borrow checker: checks ownership
- Compile pipeline → HIR flattening: flattens HIR (evidence: `src/pipeline.rs`)
- Compile pipeline → Type registry: builds registry (evidence: `src/pipeline.rs`)
- Compile pipeline → Code generation: generates code (evidence: `src/pipeline.rs`)
- Code generation → MLIR lowering: lowers to MLIR
- Vx programmer → JIT execution: runs program
- Remote worker → Remote client: uses client (evidence: `runtime/vx_worker_main.cpp`)
- Remote client → Wire protocol: uses protocol (evidence: `runtime/vx_remote_client.h`)
