# solarmoff-afk/firework architecture

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

- Interactive diagram: https://gitdiagram.com/solarmoff-afk/firework
- Repository: https://github.com/solarmoff-afk/firework

## Overview

Firework is a Rust UI framework with a procedural compiler, runtime widgets and layout, adapter interfaces, and developer tooling. The principal workflow is Rust UI input through AST normalization, analysis, lowering and code generation, then generated UI behavior through runtime widgets and an adapter. The README provides no capability overview; the graph relies on the sampled compiler/runtime excerpts and SOURCE INDEX. Several modules are indexed but not sampled, so their internal calls and some integration links are omitted.

Main entry points: [`firework/src/lib.rs`](https://github.com/solarmoff-afk/firework/blob/main/firework/src/lib.rs) (Runtime API), [`crates/firework_compiler/src/compiler/mod.rs`](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/mod.rs) (Compiler entry), [`crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs) (Code builder), [`firework/src/std_widgets/mod.rs`](https://github.com/solarmoff-afk/firework/blob/main/firework/src/std_widgets/mod.rs) (Standard widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["UI compiler"]
  node_compiler_entry["Compiler entry<br/>[mod.rs]"]
  node_desugar["AST normalization<br/>[mod.rs]"]
  node_analyze["Semantic analysis"]
  node_lower["AST lowering"]
  node_transform["Code transforms"]
  node_ir["Compiler IR"]
  node_code_builder["Code builder<br/>[mod.rs]"]
  node_layout_codegen["Layout generation<br/>[arrage_gen.rs]"]
  node_static_gen["Static generation<br/>[static_gen.rs]"]
  node_bitmask_gen["Bitmask generation<br/>[bitmask_gen.rs]"]
end

subgraph group_runtime["UI runtime"]
  node_runtime_api["Runtime API<br/>[lib.rs]"]
  node_layout["Layout engine<br/>[layout.rs]"]
  node_widget_trait["Widget contract<br/>[widget.rs]"]
  node_std_widgets["Standard widgets<br/>[mod.rs]"]
  node_dyn_list["Dynamic lists<br/>[dyn_list.rs]"]
  node_async_spark["Async sparks<br/>[async_spark.rs]"]
end

subgraph group_adapters["Rendering adapters"]
  node_adapter_api["Adapter interface<br/>[lib.rs]"]
  node_null_adapter["Null adapter<br/>[null_adapter.rs]"]
end

subgraph group_tools["Developer tools"]
  node_visual_devtool["Visual devtool<br/>[visual_dt.rs]"]
  node_dev_client["Android render client<br/>[RenderView.java]"]
  node_dev_library["Development library<br/>[lib.rs]"]
end

node_author(("Rust UI author"))

node_author -->|"provides AST"| node_compiler_entry
node_compiler_entry -->|"normalizes AST"| node_desugar
node_compiler_entry -->|"analyzes tokens"| node_analyze
node_compiler_entry -->|"lowers AST"| node_lower
node_compiler_entry -->|"transforms AST"| node_transform
node_compiler_entry -.->|"passes IR"| node_ir
node_code_builder -->|"reads IR"| node_ir
node_layout_codegen -->|"reads widget data"| node_ir
node_code_builder -->|"delegates layout"| node_layout_codegen
node_code_builder -->|"invokes generator"| node_static_gen
node_code_builder -->|"invokes generator"| node_bitmask_gen
node_runtime_api -->|"exports module"| node_layout
node_runtime_api -->|"exports module"| node_std_widgets
node_runtime_api -->|"exports runtime"| node_async_spark
node_runtime_api -->|"exports runtime"| node_dyn_list
node_std_widgets -->|"implements contract"| node_widget_trait
node_std_widgets -->|"uses layout types"| node_layout
node_dyn_list -->|"manages widgets"| node_widget_trait
node_dyn_list -->|"uses layout types"| node_layout
node_runtime_api -.->|"dispatches commands"| node_adapter_api
node_runtime_api -.->|"provides fallback"| node_null_adapter
node_visual_devtool -->|"proxies commands"| node_adapter_api
node_dev_library -->|"exposes tooling"| node_visual_devtool
node_dev_client -.->|"integrates with"| node_dev_library

click node_compiler_entry "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/mod.rs"
click node_desugar "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/desugaring/mod.rs"
click node_analyze "https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/analyze"
click node_lower "https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/lower"
click node_transform "https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/transform"
click node_ir "https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/ir"
click node_code_builder "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs"
click node_layout_codegen "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/code_builder/layout/arrage_gen.rs"
click node_static_gen "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/generator/static_gen.rs"
click node_bitmask_gen "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/generator/bitmask_gen.rs"
click node_runtime_api "https://github.com/solarmoff-afk/firework/blob/main/firework/src/lib.rs"
click node_layout "https://github.com/solarmoff-afk/firework/blob/main/firework/src/layout.rs"
click node_widget_trait "https://github.com/solarmoff-afk/firework/blob/main/firework/src/std_widgets/widget.rs"
click node_std_widgets "https://github.com/solarmoff-afk/firework/blob/main/firework/src/std_widgets/mod.rs"
click node_dyn_list "https://github.com/solarmoff-afk/firework/blob/main/firework/src/runtime/dyn_list.rs"
click node_async_spark "https://github.com/solarmoff-afk/firework/blob/main/firework/src/runtime/async_spark.rs"
click node_adapter_api "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_adapter/src/lib.rs"
click node_null_adapter "https://github.com/solarmoff-afk/firework/blob/main/firework/src/null_adapter.rs"
click node_visual_devtool "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_devtools/src/visual_dt.rs"
click node_dev_client "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_dev/client/src/main/java/com/firework/devclient/RenderView.java"
click node_dev_library "https://github.com/solarmoff-afk/firework/blob/main/crates/firework_dev/src/lib.rs"

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_compiler_entry,node_desugar,node_analyze,node_lower,node_transform,node_ir,node_code_builder,node_layout_codegen,node_static_gen,node_bitmask_gen,node_author toneBlue
class node_runtime_api,node_layout,node_widget_trait,node_std_widgets,node_dyn_list,node_async_spark toneAmber
class node_adapter_api,node_null_adapter toneMint
class node_visual_devtool,node_dev_client,node_dev_library toneRose
```

## Components

### UI compiler

- [Compiler entry](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/mod.rs): `crates/firework_compiler/src/compiler/mod.rs`
- [AST normalization](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/desugaring/mod.rs): `crates/firework_compiler/src/compiler/desugaring/mod.rs`
- [Semantic analysis](https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/analyze): `crates/firework_compiler/src/compiler/analyze`
- [AST lowering](https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/lower): `crates/firework_compiler/src/compiler/codegen/lower`
- [Code transforms](https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/transform): `crates/firework_compiler/src/compiler/codegen/transform`
- [Compiler IR](https://github.com/solarmoff-afk/firework/tree/main/crates/firework_compiler/src/compiler/codegen/ir): `crates/firework_compiler/src/compiler/codegen/ir`
- [Code builder](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs): `crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`
- [Layout generation](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/code_builder/layout/arrage_gen.rs): `crates/firework_compiler/src/compiler/codegen/code_builder/layout/arrage_gen.rs`
- [Static generation](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/generator/static_gen.rs): `crates/firework_compiler/src/compiler/codegen/generator/static_gen.rs`
- [Bitmask generation](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_compiler/src/compiler/codegen/generator/bitmask_gen.rs): `crates/firework_compiler/src/compiler/codegen/generator/bitmask_gen.rs`

### UI runtime

- [Runtime API](https://github.com/solarmoff-afk/firework/blob/main/firework/src/lib.rs): `firework/src/lib.rs`
- [Layout engine](https://github.com/solarmoff-afk/firework/blob/main/firework/src/layout.rs): `firework/src/layout.rs`
- [Widget contract](https://github.com/solarmoff-afk/firework/blob/main/firework/src/std_widgets/widget.rs): `firework/src/std_widgets/widget.rs`
- [Standard widgets](https://github.com/solarmoff-afk/firework/blob/main/firework/src/std_widgets/mod.rs): `firework/src/std_widgets/mod.rs`
- [Dynamic lists](https://github.com/solarmoff-afk/firework/blob/main/firework/src/runtime/dyn_list.rs): `firework/src/runtime/dyn_list.rs`
- [Async sparks](https://github.com/solarmoff-afk/firework/blob/main/firework/src/runtime/async_spark.rs): `firework/src/runtime/async_spark.rs`

### Rendering adapters

- [Adapter interface](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_adapter/src/lib.rs): `crates/firework_adapter/src/lib.rs`
- [Null adapter](https://github.com/solarmoff-afk/firework/blob/main/firework/src/null_adapter.rs): `firework/src/null_adapter.rs`

### Developer tools

- [Visual devtool](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_devtools/src/visual_dt.rs): `crates/firework_devtools/src/visual_dt.rs`
- [Android render client](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_dev/client/src/main/java/com/firework/devclient/RenderView.java): `crates/firework_dev/client/src/main/java/com/firework/devclient/RenderView.java`
- [Development library](https://github.com/solarmoff-afk/firework/blob/main/crates/firework_dev/src/lib.rs): `crates/firework_dev/src/lib.rs`

### Other components

- **Rust UI author**

## Connections

- Rust UI author → Compiler entry: provides AST (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Compiler entry → AST normalization: normalizes AST (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Compiler entry → Semantic analysis: analyzes tokens (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Compiler entry → AST lowering: lowers AST (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Compiler entry → Code transforms: transforms AST (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Compiler entry → Compiler IR: passes IR (evidence: `crates/firework_compiler/src/compiler/mod.rs`)
- Code builder → Compiler IR: reads IR (evidence: `crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`)
- Layout generation → Compiler IR: reads widget data (evidence: `crates/firework_compiler/src/compiler/codegen/code_builder/layout/arrage_gen.rs`)
- Code builder → Layout generation: delegates layout (evidence: `crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`)
- Code builder → Static generation: invokes generator (evidence: `crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`)
- Code builder → Bitmask generation: invokes generator (evidence: `crates/firework_compiler/src/compiler/codegen/code_builder/mod.rs`)
- Runtime API → Layout engine: exports module (evidence: `firework/src/lib.rs`)
- Runtime API → Standard widgets: exports module (evidence: `firework/src/lib.rs`)
- Runtime API → Async sparks: exports runtime
- Runtime API → Dynamic lists: exports runtime
- Standard widgets → Widget contract: implements contract (evidence: `firework/src/std_widgets/widget.rs`)
- Standard widgets → Layout engine: uses layout types (evidence: `firework/src/std_widgets/mod.rs`)
- Dynamic lists → Widget contract: manages widgets (evidence: `firework/src/runtime/dyn_list.rs`)
- Dynamic lists → Layout engine: uses layout types (evidence: `firework/src/runtime/dyn_list.rs`)
- Runtime API → Adapter interface: dispatches commands
- Runtime API → Null adapter: provides fallback (evidence: `firework/src/lib.rs`)
- Visual devtool → Adapter interface: proxies commands (evidence: `crates/firework_devtools/src/visual_dt.rs`)
- Development library → Visual devtool: exposes tooling
- Android render client → Development library: integrates with