# luxlang/lux architecture

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

- Interactive diagram: https://gitdiagram.com/luxlang/lux
- Repository: https://github.com/luxlang/lux

## Overview

1. This repository is a Lux language monorepo, not a single app. The main product is the language implementation itself, plus its standard library, compiler backends, packaging tool, docs, and tests.

2. The core language/runtime lives under `stdlib/source/library/lux/**` and `stdlib/source/documentation/lux/**`. This is where the reusable foundation is organized: data structures, control abstractions, math, concurrency, I/O, FFI, web, security, and the compiler/runtime APIs.

3. The compiler pipeline is explicit in `stdlib/source/library/lux/compiler/**`, especially the nested `language/lux` phases. The major stages are analysis, synthesis, and translation, with separate modules for each stage and for compiler metadata, caches, archives, and references.

4. Target backends are a first-class boundary. Lux can translate to JVM, JavaScript, Lua, Python, Ruby, PHP, R, Common Lisp, and C++ via `stdlib/source/library/lux/compiler/language/lux/phase/translation/**` and `stdlib/source/library/lux/target/**`. Each target has its own runtime and translation rules, so architecture diagrams should show a shared frontend feeding multiple backend-specific emitters.

5. The platform entrypoints are split into host-specific projects such as `lux-jvm`, `lux-js`, `lux-python`, `lux-lua`, `lux-ruby`, `lux-c++`, `lux-php`, `lux-cl`, and `lux-r`. These are thin wrappers with their own `project.*` files and `source/program.lux`, used to build or launch Lux on each host platform.

6. `aedifex/` is a separate Lux application in the same repo. It appears to be the build/package/dependency toolchain, with commands for build, clean, deploy, deps, install, versioning, APKs, and POM generation. Its internal boundaries are `command`, `dependency`, `repository`, `metadata`, `artifact`, `project`, `profile`, and `runtime`.

7. The `aedifex` data flow is repository-oriented: project input and metadata are normalized into artifacts, resolved through local/remote/origin repositories, then deployed or installed. Supporting code covers dependency status, resolution, versioning, hashing, zipping, and path handling.

8. Tests mirror the production module layout. `stdlib/source/test/**` and `aedifex/source/test/**` largely replicate the package structure of the main code, which makes the test boundary obvious: each compiler, type, repository, command, and runtime subsystem has a matching validation suite.

9. Documentation is a separate subsystem, not just comments. The repo includes the language book in `documentation/book/the_lux_programming_language/**`, module docs under `stdlib/source/documentation/**`, and a broad bookmark/knowledge-base tree under `documentation/bookmark/**`. These are part of the developer experience and language specification surface.

10. The repository also contains editor/tooling integration and bootstrap scripts. `lux-mode/` is the Emacs mode, and `shell/lux.sh` / `shell/lux.bat` are the cross-platform launch wrappers. These are auxiliary, but they matter for how users interact with the compiler and tools.

11. CI is GitHub Actions based. `.github/workflows/test.yml` runs the test workflow, and `.github/workflows/setup_aedifex/action.yml` suggests the build pipeline provisions the `aedifex` tool as part of setup. So the repo’s automation boundary is centered on compiling/testing Lux code and exercising the package tool.

12. Overall architecture: Lux source is written in `.lux`, parsed by compiler entrypoints, processed through a multi-phase compiler core, then emitted to one of several target runtimes. Around that core sit the standard library, the package/dependency manager (`aedifex`), platform-specific launchers, tests, and documentation.

Main entry points: [`stdlib/source/library/lux/target.lux`](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target.lux) (Targets), [`stdlib/source/library/lux/compiler.lux`](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler.lux) (Compiler), [`stdlib/source/library/lux.lux`](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux.lux) (Stdlib), [`aedifex/source/program/aedifex.lux`](https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex.lux) (Aedifex)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Lux core"]
  node_stdlib_library["Stdlib<br/>[lux.lux]"]
  node_stdlib_control["Control<br/>stdlib subsystem<br/>[io.lux]"]
  node_stdlib_data["Data<br/>stdlib subsystem<br/>[text.lux]"]
  node_stdlib_meta["Meta<br/>stdlib subsystem<br/>[meta.lux]"]
  node_stdlib_compiler["Compiler<br/>[compiler.lux]"]
  node_compiler_analysis["Analysis<br/>compiler phase<br/>[analysis.lux]"]
  node_compiler_synthesis["Synthesis<br/>compiler phase<br/>[synthesis.lux]"]
  node_compiler_translation["Translation<br/>compiler phase<br/>[translation.lux]"]
  node_compiler_meta["Compiler meta<br/>compiler services<br/>[meta.lux]"]
  node_target_runtime["Targets<br/>backend boundary<br/>[target.lux]"]
  node_target_jvm["JVM<br/>backend target<br/>[bytecode.lux]"]
  node_target_js["JavaScript<br/>backend target<br/>[js.lux]"]
  node_target_python["Python<br/>backend target<br/>[python.lux]"]
  node_target_lua["Lua<br/>backend target<br/>[lua.lux]"]
  node_target_ruby["Ruby<br/>backend target<br/>[ruby.lux]"]
  node_target_php["PHP<br/>backend target<br/>[php.lux]"]
  node_target_r["R<br/>[r.lux]"]
  node_target_cl["Common Lisp<br/>backend target<br/>[common_lisp.lux]"]
  node_target_cpp["C++<br/>backend target<br/>[c++.lux]"]
end

subgraph group_tooling["Tooling"]
  node_aedifex["Aedifex<br/>package tool<br/>[aedifex.lux]"]
  node_aedifex_command["Commands<br/>aedifex subsystem<br/>[command.lux]"]
  node_aedifex_dependency["Dependencies<br/>aedifex subsystem<br/>[dependency.lux]"]
  node_aedifex_repository["Repositories<br/>aedifex subsystem<br/>[repository.lux]"]
  node_platform_hosts["Hosts<br/>host wrappers<br/>[program.lux]"]
  node_ci["CI<br/>automation<br/>[test.yml]"]
end

subgraph group_docs["Docs"]
  node_docs_book["Language book<br/>documentation<br/>[index.md]"]
  node_docs_stdlib["Module docs<br/>documentation<br/>[lux.lux]"]
  node_docs_bookmarks["Bookmarks<br/>knowledge base<br/>[bookmark.md]"]
end

subgraph group_tests["Tests"]
  node_stdlib_tests["Stdlib tests<br/>test suite<br/>[lux.lux]"]
  node_aedifex_tests["Aedifex tests<br/>test suite<br/>[aedifex.lux]"]
  node_host_tests["Host tests<br/>test suite<br/>[program.lux]"]
end

node_stdlib_library -->|"exports"| node_stdlib_control
node_stdlib_library -->|"exports"| node_stdlib_data
node_stdlib_library -->|"exports"| node_stdlib_meta
node_stdlib_library -->|"contains"| node_stdlib_compiler
node_stdlib_compiler -->|"phase"| node_compiler_analysis
node_stdlib_compiler -->|"phase"| node_compiler_synthesis
node_stdlib_compiler -->|"phase"| node_compiler_translation
node_stdlib_compiler -->|"services"| node_compiler_meta
node_compiler_analysis -->|"feeds"| node_compiler_synthesis
node_compiler_synthesis -->|"feeds"| node_compiler_translation
node_compiler_translation -->|"emits to"| node_target_runtime
node_target_runtime -->|"backend"| node_target_jvm
node_target_runtime -->|"backend"| node_target_js
node_target_runtime -->|"backend"| node_target_python
node_target_runtime -->|"backend"| node_target_lua
node_target_runtime -->|"backend"| node_target_ruby
node_target_runtime -->|"backend"| node_target_php
node_target_runtime -->|"backend"| node_target_r
node_target_runtime -->|"backend"| node_target_cl
node_target_runtime -->|"backend"| node_target_cpp
node_aedifex -->|"orchestrates"| node_aedifex_command
node_aedifex -->|"orchestrates"| node_aedifex_dependency
node_aedifex -->|"orchestrates"| node_aedifex_repository
node_aedifex_dependency -->|"resolves through"| node_aedifex_repository
node_aedifex_repository -->|"used by"| node_aedifex_command
node_platform_hosts -->|"boots"| node_stdlib_compiler
node_platform_hosts -->|"selects"| node_target_runtime
node_docs_book -->|"documents"| node_stdlib_library
node_docs_stdlib -->|"documents"| node_stdlib_library
node_docs_bookmarks -->|"supports"| node_docs_book
node_stdlib_tests -->|"validates"| node_stdlib_compiler
node_aedifex_tests -->|"validates"| node_aedifex
node_host_tests -->|"validates"| node_platform_hosts
node_ci -->|"runs"| node_stdlib_tests
node_ci -->|"runs"| node_aedifex_tests
node_ci -->|"builds"| node_platform_hosts

click node_stdlib_library "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux.lux"
click node_stdlib_control "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/control/io.lux"
click node_stdlib_data "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/data/text.lux"
click node_stdlib_meta "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/meta.lux"
click node_stdlib_compiler "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler.lux"
click node_compiler_analysis "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/analysis.lux"
click node_compiler_synthesis "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/synthesis.lux"
click node_compiler_translation "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/translation.lux"
click node_compiler_meta "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/meta.lux"
click node_target_runtime "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target.lux"
click node_target_jvm "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/jvm/bytecode.lux"
click node_target_js "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/js.lux"
click node_target_python "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/python.lux"
click node_target_lua "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/lua.lux"
click node_target_ruby "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/ruby.lux"
click node_target_php "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/php.lux"
click node_target_r "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/r.lux"
click node_target_cl "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/common_lisp.lux"
click node_target_cpp "https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/c++.lux"
click node_aedifex "https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex.lux"
click node_aedifex_command "https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/command.lux"
click node_aedifex_dependency "https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/dependency.lux"
click node_aedifex_repository "https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/repository.lux"
click node_platform_hosts "https://github.com/luxlang/lux/blob/master/lux-jvm/source/program.lux"
click node_docs_book "https://github.com/luxlang/lux/blob/master/documentation/book/the_lux_programming_language/index.md"
click node_docs_stdlib "https://github.com/luxlang/lux/blob/master/stdlib/source/documentation/lux.lux"
click node_docs_bookmarks "https://github.com/luxlang/lux/blob/master/documentation/bookmark.md"
click node_stdlib_tests "https://github.com/luxlang/lux/blob/master/stdlib/source/test/lux.lux"
click node_aedifex_tests "https://github.com/luxlang/lux/blob/master/aedifex/source/test/aedifex.lux"
click node_host_tests "https://github.com/luxlang/lux/blob/master/lux-r/source/test/program.lux"
click node_ci "https://github.com/luxlang/lux/blob/master/.github/workflows/test.yml"

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_stdlib_library,node_stdlib_control,node_stdlib_data,node_stdlib_meta,node_stdlib_compiler,node_compiler_analysis,node_compiler_synthesis,node_compiler_translation,node_compiler_meta,node_target_runtime,node_target_jvm,node_target_js,node_target_python,node_target_lua,node_target_ruby,node_target_php,node_target_r,node_target_cl,node_target_cpp toneBlue
class node_aedifex,node_aedifex_command,node_aedifex_dependency,node_aedifex_repository,node_platform_hosts,node_ci toneAmber
class node_docs_book,node_docs_stdlib,node_docs_bookmarks toneMint
class node_stdlib_tests,node_aedifex_tests,node_host_tests toneRose
```

## Components

### Lux core

Standard library, language APIs, and compiler internals.

- [Stdlib](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux.lux): language stdlib · Main Lux standard library and reusable language foundation. · `stdlib/source/library/lux.lux`
- [Control](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/control/io.lux): stdlib subsystem · Control abstractions such as IO, lazy, state, region, and scope. · `stdlib/source/library/lux/control/io.lux`
- [Data](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/data/text.lux): stdlib subsystem · Collections, text, format, and other foundational data types. · `stdlib/source/library/lux/data/text.lux`
- [Meta](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/meta.lux): stdlib subsystem · Language reflection, code, module, and provenance APIs. · `stdlib/source/library/lux/meta.lux`
- [Compiler](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler.lux): compiler core · Shared compiler core and language-specific compilation pipeline. · `stdlib/source/library/lux/compiler.lux`
- [Analysis](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/analysis.lux): compiler phase · Semantic analysis and type-driven program understanding. · `stdlib/source/library/lux/compiler/language/lux/analysis.lux`
- [Synthesis](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/synthesis.lux): compiler phase · Intermediate representation construction before backend translation. · `stdlib/source/library/lux/compiler/language/lux/synthesis.lux`
- [Translation](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/language/lux/translation.lux): compiler phase · Backend emission stage that lowers Lux to target runtimes. · `stdlib/source/library/lux/compiler/language/lux/translation.lux`
- [Compiler meta](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/compiler/meta.lux): compiler services · Archives, caches, CLI, I/O, and packager support for builds. · `stdlib/source/library/lux/compiler/meta.lux`
- [Targets](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target.lux): backend boundary · Target-specific runtime definitions used by the compiler backends. · `stdlib/source/library/lux/target.lux`
- [JVM](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/jvm/bytecode.lux): backend target · JVM target data structures, bytecode, and runtime support. · `stdlib/source/library/lux/target/jvm/bytecode.lux`
- [JavaScript](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/js.lux): backend target · JavaScript target runtime and code generation helpers. · `stdlib/source/library/lux/target/js.lux`
- [Python](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/python.lux): backend target · Python target runtime and code generation helpers. · `stdlib/source/library/lux/target/python.lux`
- [Lua](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/lua.lux): backend target · Lua target runtime and code generation helpers. · `stdlib/source/library/lux/target/lua.lux`
- [Ruby](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/ruby.lux): backend target · Ruby target runtime and code generation helpers. · `stdlib/source/library/lux/target/ruby.lux`
- [PHP](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/php.lux): backend target · PHP target runtime and code generation helpers. · `stdlib/source/library/lux/target/php.lux`
- [R](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/r.lux): backend target · R target runtime and code generation helpers. · `stdlib/source/library/lux/target/r.lux`
- [Common Lisp](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/common_lisp.lux): backend target · Common Lisp target runtime and code generation helpers. · `stdlib/source/library/lux/target/common_lisp.lux`
- [C++](https://github.com/luxlang/lux/blob/master/stdlib/source/library/lux/target/c++.lux): backend target · C++ target runtime and code generation helpers. · `stdlib/source/library/lux/target/c++.lux`

### Tooling

Package manager, launchers, editor integration, and CI.

- [Aedifex](https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex.lux): package tool · Build, dependency, deployment, and packaging application. · `aedifex/source/program/aedifex.lux`
- [Commands](https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/command.lux): aedifex subsystem · CLI commands for build, clean, deps, install, deploy, test, and versioning. · `aedifex/source/program/aedifex/command.lux`
- [Dependencies](https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/dependency.lux): aedifex subsystem · Dependency resolution, status, and deployment flow. · `aedifex/source/program/aedifex/dependency.lux`
- [Repositories](https://github.com/luxlang/lux/blob/master/aedifex/source/program/aedifex/repository.lux): aedifex subsystem · Local, origin, and remote repository boundaries. · `aedifex/source/program/aedifex/repository.lux`
- [Hosts](https://github.com/luxlang/lux/blob/master/lux-jvm/source/program.lux): host wrappers · Thin platform-specific entrypoints for launching or building Lux. · `lux-jvm/source/program.lux`
- [CI](https://github.com/luxlang/lux/blob/master/.github/workflows/test.yml): automation · GitHub Actions workflows that run tests and provision Aedifex. · `.github/workflows/test.yml`

### Docs

Language book, module docs, and knowledge base.

- [Language book](https://github.com/luxlang/lux/blob/master/documentation/book/the_lux_programming_language/index.md): documentation · The Lux programming language book and specification narrative. · `documentation/book/the_lux_programming_language/index.md`
- [Module docs](https://github.com/luxlang/lux/blob/master/stdlib/source/documentation/lux.lux): documentation · Reference documentation generated from stdlib modules. · `stdlib/source/documentation/lux.lux`
- [Bookmarks](https://github.com/luxlang/lux/blob/master/documentation/bookmark.md): knowledge base · Broad curated documentation and research tree. · `documentation/bookmark.md`

### Tests

Validation suites mirroring the production layout.

- [Stdlib tests](https://github.com/luxlang/lux/blob/master/stdlib/source/test/lux.lux): test suite · Production-mirroring tests for the Lux standard library and compiler. · `stdlib/source/test/lux.lux`
- [Aedifex tests](https://github.com/luxlang/lux/blob/master/aedifex/source/test/aedifex.lux): test suite · Validation suites for the package tool and repository workflow. · `aedifex/source/test/aedifex.lux`
- [Host tests](https://github.com/luxlang/lux/blob/master/lux-r/source/test/program.lux): test suite · Platform wrapper and host-specific validation coverage. · `lux-r/source/test/program.lux`

## Connections

- Stdlib → Control: exports · Core library includes control abstractions.
- Stdlib → Data: exports · Core library includes data foundations.
- Stdlib → Meta: exports · Core library includes meta and reflection APIs.
- Stdlib → Compiler: contains · The stdlib also hosts compiler-facing APIs and internals.
- Compiler → Analysis: phase · Frontend semantic analysis.
- Compiler → Synthesis: phase · Intermediate synthesis stage.
- Compiler → Translation: phase · Backend translation stage.
- Compiler → Compiler meta: services · Compiler metadata, archives, caches, and packager support.
- Analysis → Synthesis: feeds · Analysis produces input for synthesis.
- Synthesis → Translation: feeds · Synthesis produces input for translation.
- Translation → Targets: emits to · Translation lowers into target runtimes.
- Targets → JVM: backend · JVM backend boundary.
- Targets → JavaScript: backend · JavaScript backend boundary.
- Targets → Python: backend · Python backend boundary.
- Targets → Lua: backend · Lua backend boundary.
- Targets → Ruby: backend · Ruby backend boundary.
- Targets → PHP: backend · PHP backend boundary.
- Targets → R: backend · R backend boundary.
- Targets → Common Lisp: backend · Common Lisp backend boundary.
- Targets → C++: backend · C++ backend boundary.
- Aedifex → Commands: orchestrates · CLI command layer drives tool behavior.
- Aedifex → Dependencies: orchestrates · Dependency resolution and deployment pipeline.
- Aedifex → Repositories: orchestrates · Repository abstractions support resolution and publishing.
- Dependencies → Repositories: resolves through · Dependencies are resolved via repository boundaries.
- Repositories → Commands: used by · Commands trigger repository operations.
- Hosts → Compiler: boots · Host entrypoints bootstrap Lux compilation and execution.
- Hosts → Targets: selects · Each host wraps a specific runtime/target combination.
- Language book → Stdlib: documents · The book explains the language and its standard library.
- Module docs → Stdlib: documents · Module-level documentation mirrors stdlib structure.
- Bookmarks → Language book: supports · Reference bookmarks complement the book and specification.
- Stdlib tests → Compiler: validates · Tests mirror compiler and stdlib modules.
- Aedifex tests → Aedifex: validates · Tests cover tool commands, dependency flow, and repositories.
- Host tests → Hosts: validates · Host wrapper tests check launch/build entrypoints.
- CI → Stdlib tests: runs · CI executes the stdlib and compiler test suite.
- CI → Aedifex tests: runs · CI executes Aedifex validation.
- CI → Hosts: builds · CI also exercises host-specific packaging and setup.