# astra-void/vela-rbxts architecture

> Architecture diagram of the GitHub repository astra-void/vela-rbxts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astra-void/vela-rbxts
- Repository: https://github.com/astra-void/vela-rbxts

## Overview

Vela is a Tailwind-style className compiler and runtime for Roblox UI projects, with React and Vide targets. The main workflow is project configuration plus TSX className input, lowered by either the roblox-ts transformer or the standalone CLI, then evaluated by the matching runtime host. A separate editor workflow exposes compiler services through a Rust LSP server and VS Code client. Compiler internals and relationships are grounded in the supplied excerpts and SOURCE INDEX; broader package relationships follow the README. Unsampled implementation details are not inferred.

Main entry points: [`packages/compiler/src/transform/jsx.rs`](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/jsx.rs) (JSX lowering), [`packages/lsp/src/server.rs`](https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/server.rs) (Rust LSP server), [`packages/compiler/src/api/mod.rs`](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/api/mod.rs) (Compiler API), [`packages/compiler/src/transform/runtime.rs`](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/runtime.rs) (Runtime emission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Project integration"]
  node_rbxts_transformer["rbxtsc transformer<br/>[transformer.ts]"]
  node_host_bridge["Compiler bridge<br/>[bridge.ts]"]
  node_vela_cli["vela CLI<br/>[run.ts]"]
end

subgraph group_compiler["Compiler"]
  node_compiler_api["Compiler API<br/>[mod.rs]"]
  node_class_values["Class value collapse<br/>[collapse.rs]"]
  node_config_model["Compiler config model<br/>[model.rs]"]
  node_utility_semantics["Utility resolution<br/>[utility.rs]"]
  node_compiler_diagnostics["Compiler diagnostics<br/>[compiler.rs]"]
  node_jsx_transform["JSX lowering<br/>[jsx.rs]"]
  node_transform_context["Transform context<br/>[context.rs]"]
  node_module_transform["Module transform<br/>[module.rs]"]
  node_branch_transform["Branch lowering<br/>[branch.rs]"]
  node_runtime_transform["Runtime emission<br/>[runtime.rs]"]
end

subgraph group_config["Configuration"]
  node_css_config["CSS config loader<br/>[css.ts]"]
  node_config_plugins["Config plugins<br/>[plugin.ts]"]
  node_config_variants["Custom variants<br/>[variants.ts]"]
end

subgraph group_runtime["Runtime"]
  node_runtime_core["Runtime core<br/>[apply.ts]"]
  node_react_runtime["React host runtime<br/>[index.ts]"]
  node_vide_runtime["Vide host runtime<br/>[index.ts]"]
end

subgraph group_editor["Editor tooling"]
  node_lsp_server["Rust LSP server<br/>[server.rs]"]
  node_lsp_documents["Document state<br/>[documents.rs]"]
  node_lsp_translate["Protocol translation<br/>[translate.rs]"]
  node_vscode_client["VS Code client<br/>[extension.ts]"]
end

node_developer(("Roblox developer"))

node_developer -->|"registers plugin"| node_rbxts_transformer
node_developer -->|"runs CLI"| node_vela_cli
node_rbxts_transformer -->|"delegates"| node_host_bridge
node_host_bridge -.->|"calls compiler"| node_compiler_api
node_vela_cli -->|"uses host"| node_host_bridge
node_compiler_api -.->|"lowers TSX"| node_jsx_transform
node_compiler_api -.->|"accepts config"| node_config_model
node_transform_context -->|"collapses values"| node_class_values
node_transform_context -->|"visits JSX"| node_jsx_transform
node_jsx_transform -->|"collapses values"| node_class_values
node_jsx_transform -->|"lowers branches"| node_branch_transform
node_jsx_transform -->|"emits runtime needs"| node_runtime_transform
node_jsx_transform -->|"reads config"| node_config_model
node_utility_semantics -->|"resolves theme"| node_config_model
node_utility_semantics -->|"reports issues"| node_compiler_diagnostics
node_module_transform -->|"adds runtime host"| node_runtime_transform
node_developer -->|"writes CSS config"| node_css_config
node_css_config -->|"registers plugins"| node_config_plugins
node_css_config -->|"registers variants"| node_config_variants
node_developer -->|"uses editor"| node_lsp_server
node_lsp_server -->|"updates documents"| node_lsp_documents
node_lsp_server -->|"translates requests"| node_lsp_translate
node_lsp_server -.->|"requests editor services"| node_compiler_api
node_vscode_client -->|"connects LSP"| node_lsp_server
node_runtime_core -.->|"supports host"| node_react_runtime
node_runtime_core -.->|"supports host"| node_vide_runtime
node_runtime_transform -.->|"imports host"| node_react_runtime
node_runtime_transform -.->|"imports Vide host"| node_vide_runtime

click node_rbxts_transformer "https://github.com/astra-void/vela-rbxts/blob/main/packages/rbxtsc-host/src/transformer.ts"
click node_host_bridge "https://github.com/astra-void/vela-rbxts/blob/main/packages/rbxtsc-host/src/bridge.ts"
click node_vela_cli "https://github.com/astra-void/vela-rbxts/blob/main/packages/vela-rbxts/src/cli/run.ts"
click node_compiler_api "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/api/mod.rs"
click node_class_values "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/class_value/collapse.rs"
click node_config_model "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/config/model.rs"
click node_utility_semantics "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/semantic/utility.rs"
click node_compiler_diagnostics "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/diagnostics/compiler.rs"
click node_jsx_transform "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/jsx.rs"
click node_transform_context "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/context.rs"
click node_module_transform "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/module.rs"
click node_branch_transform "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/branch.rs"
click node_runtime_transform "https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/runtime.rs"
click node_css_config "https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/css.ts"
click node_config_plugins "https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/plugin.ts"
click node_config_variants "https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/variants.ts"
click node_runtime_core "https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime-core/src/apply.ts"
click node_react_runtime "https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime/src/index.ts"
click node_vide_runtime "https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime-vide/src/index.ts"
click node_lsp_server "https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/server.rs"
click node_lsp_documents "https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/documents.rs"
click node_lsp_translate "https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/translate.rs"
click node_vscode_client "https://github.com/astra-void/vela-rbxts/blob/main/packages/vscode-extension/src/extension.ts"

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_rbxts_transformer,node_host_bridge,node_vela_cli toneBlue
class node_compiler_api,node_class_values,node_config_model,node_utility_semantics,node_compiler_diagnostics,node_jsx_transform,node_transform_context,node_module_transform,node_branch_transform,node_runtime_transform toneAmber
class node_css_config,node_config_plugins,node_config_variants toneMint
class node_runtime_core,node_react_runtime,node_vide_runtime toneRose
class node_lsp_server,node_lsp_documents,node_lsp_translate,node_vscode_client,node_developer toneIndigo
```

## Components

### Project integration

- [rbxtsc transformer](https://github.com/astra-void/vela-rbxts/blob/main/packages/rbxtsc-host/src/transformer.ts): `packages/rbxtsc-host/src/transformer.ts`
- [Compiler bridge](https://github.com/astra-void/vela-rbxts/blob/main/packages/rbxtsc-host/src/bridge.ts): `packages/rbxtsc-host/src/bridge.ts`
- [vela CLI](https://github.com/astra-void/vela-rbxts/blob/main/packages/vela-rbxts/src/cli/run.ts): `packages/vela-rbxts/src/cli/run.ts`

### Compiler

- [Compiler API](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/api/mod.rs): `packages/compiler/src/api/mod.rs`
- [Class value collapse](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/class_value/collapse.rs): `packages/compiler/src/class_value/collapse.rs`
- [Compiler config model](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/config/model.rs): `packages/compiler/src/config/model.rs`
- [Utility resolution](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/semantic/utility.rs): `packages/compiler/src/semantic/utility.rs`
- [Compiler diagnostics](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/diagnostics/compiler.rs): `packages/compiler/src/diagnostics/compiler.rs`
- [JSX lowering](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/jsx.rs): `packages/compiler/src/transform/jsx.rs`
- [Transform context](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/context.rs): `packages/compiler/src/transform/context.rs`
- [Module transform](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/module.rs): `packages/compiler/src/transform/module.rs`
- [Branch lowering](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/branch.rs): `packages/compiler/src/transform/branch.rs`
- [Runtime emission](https://github.com/astra-void/vela-rbxts/blob/main/packages/compiler/src/transform/runtime.rs): `packages/compiler/src/transform/runtime.rs`

### Configuration

- [CSS config loader](https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/css.ts): `packages/config/src/css.ts`
- [Config plugins](https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/plugin.ts): `packages/config/src/plugin.ts`
- [Custom variants](https://github.com/astra-void/vela-rbxts/blob/main/packages/config/src/variants.ts): `packages/config/src/variants.ts`

### Runtime

- [Runtime core](https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime-core/src/apply.ts): `packages/runtime-core/src/apply.ts`
- [React host runtime](https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime/src/index.ts): `packages/runtime/src/index.ts`
- [Vide host runtime](https://github.com/astra-void/vela-rbxts/blob/main/packages/runtime-vide/src/index.ts): `packages/runtime-vide/src/index.ts`

### Editor tooling

- [Rust LSP server](https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/server.rs): `packages/lsp/src/server.rs`
- [Document state](https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/documents.rs): `packages/lsp/src/documents.rs`
- [Protocol translation](https://github.com/astra-void/vela-rbxts/blob/main/packages/lsp/src/translate.rs): `packages/lsp/src/translate.rs`
- [VS Code client](https://github.com/astra-void/vela-rbxts/blob/main/packages/vscode-extension/src/extension.ts): `packages/vscode-extension/src/extension.ts`

### Other components

- **Roblox developer**

## Connections

- Roblox developer → rbxtsc transformer: registers plugin (evidence: `README.md`)
- Roblox developer → vela CLI: runs CLI (evidence: `README.md`)
- rbxtsc transformer → Compiler bridge: delegates (evidence: `packages/rbxtsc-host/src/transformer.ts`)
- Compiler bridge → Compiler API: calls compiler (evidence: `README.md`)
- vela CLI → Compiler bridge: uses host (evidence: `packages/vela-rbxts/src/cli/run.ts`)
- Compiler API → JSX lowering: lowers TSX (evidence: `README.md`)
- Compiler API → Compiler config model: accepts config (evidence: `README.md`)
- Transform context → Class value collapse: collapses values (evidence: `packages/compiler/src/transform/context.rs`)
- Transform context → JSX lowering: visits JSX (evidence: `packages/compiler/src/transform/context.rs`)
- JSX lowering → Class value collapse: collapses values (evidence: `packages/compiler/src/transform/jsx.rs`)
- JSX lowering → Branch lowering: lowers branches (evidence: `packages/compiler/src/transform/jsx.rs`)
- JSX lowering → Runtime emission: emits runtime needs (evidence: `packages/compiler/src/transform/jsx.rs`)
- JSX lowering → Compiler config model: reads config (evidence: `packages/compiler/src/transform/jsx.rs`)
- Utility resolution → Compiler config model: resolves theme (evidence: `packages/compiler/src/semantic/utility.rs`)
- Utility resolution → Compiler diagnostics: reports issues (evidence: `packages/compiler/src/semantic/utility.rs`)
- Module transform → Runtime emission: adds runtime host (evidence: `packages/compiler/src/transform/module.rs`)
- Roblox developer → CSS config loader: writes CSS config (evidence: `README.md`)
- CSS config loader → Config plugins: registers plugins (evidence: `packages/config/src/css.ts`)
- CSS config loader → Custom variants: registers variants (evidence: `packages/config/src/css.ts`)
- Roblox developer → Rust LSP server: uses editor (evidence: `README.md`)
- Rust LSP server → Document state: updates documents (evidence: `packages/lsp/src/server.rs`)
- Rust LSP server → Protocol translation: translates requests (evidence: `packages/lsp/src/main.rs`)
- Rust LSP server → Compiler API: requests editor services (evidence: `README.md`)
- VS Code client → Rust LSP server: connects LSP (evidence: `README.md`)
- Runtime core → React host runtime: supports host (evidence: `README.md`)
- Runtime core → Vide host runtime: supports host (evidence: `README.md`)
- Runtime emission → React host runtime: imports host (evidence: `README.md`)
- Runtime emission → Vide host runtime: imports Vide host (evidence: `README.md`)