Architecture and Flows

Architecture and Flows

sw-MLPL is a cellular Rust monorepo. Each top-level component is a small Cargo workspace containing narrow crates; there is intentionally no single root Cargo.toml controlling everything.

Layered view

flowchart BT
    Types[Types and evaluation contracts] --> Array[Array substrate and operations]
    Types --> Syntax[Tokens, lexer, parser, AST]
    Array --> Runtime[Runtime math, data, layers, reducers]
    Syntax --> Eval[Evaluator, environment, models]
    Runtime --> Eval
    Eval --> Autograd[Autograd tape and trace]
    Eval --> Viz[Visualization and model IR]
    Eval --> Devices[CPU, MLX, CUDA adapters]
    Eval --> Wasm[WASM evaluator]
    Eval --> Serve[Session server]
    Wasm --> Web[Web UI, tutorials, demos, glossary]
    Serve --> Clients[Connected web and terminal clients]

Loading

Major component families

Family	Responsibility
syntax-*	Tokens, lexical decomposition, parser/AST, Rust lowering, macro
types, eval-types	Shared values, errors, tags, model/value contracts
array, array-element, array-compose	Dense arrays, element/shape ops, matmul, reductions, composition
runtime-*	Builtin execution for math, arrays, ML layers, data, and dimensionality reduction
eval	Environment, evaluation, model application, training routing, functions, fetch/data paths
autograd	Tape, reverse-mode differentiation, structured trace
models-*, ml-helpers, engram, games	Model inspection/mutation/tuning, ML helpers, Engram and game domains
native-rt, mlx-model, mlx-eval	CPU/MLX runtime and MLX model/evaluator integration
cuda-rt, cuda-model, cuda-eval	CUDA operations, traceable models, and CUDA training dispatch
viz, web-viz-*	Visualization values, marks, model IR, 3-D rendering
wasm, web-*	Browser evaluator, UI, tutorials, paths, demos, glossary, rendering
cli	REPL, build tool, embedding facade, lab/client tools
serve, session-infra	REST/SSE sessions, persistence, device peer routing, shared session infrastructure
monitoring	macOS/Linux resource and device telemetry
dev-tools	Benchmarks, parity tests, repository utilities

Evaluation flow

sequenceDiagram
    participant P as Parser
    participant E as Evaluator
    participant N as Environment
    participant R as Runtime operation
    participant T as Autograd tape
    P->>E: AST
    E->>N: Resolve bindings and scopes
    E->>R: Execute operation for active device
    R-->>E: Value with shape, labels, tags, device
    E->>T: Record differentiable node
    E->>N: Store resulting binding
    E-->>P: Result or structured error

Loading

Training flow and backend seam

The evaluator owns language semantics and identifies active device scopes. CPU uses dense host arrays and the general tape. MLX uses persistent device handles throughout the general tape and optimizer. CUDA dispatches forward operations and recognized LoRA or two-linear MLP training shapes to Candle; other training shapes use the CPU tape.

Design properties

• Narrow public APIs and component-level ownership.
• Contract-first behavior and structured errors.
• Traceability and introspection as core language features.
• Same language surface across execution backends.
• Optional platform dependencies remain target/feature gated.
• Browser, server, and native clients share evaluator semantics without sharing the same deployment constraints.

Read the source repository's architecture, repository structure, and loose-coupling notes.