# labpics-team/lab-colors architecture

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

- Interactive diagram: https://gitdiagram.com/labpics-team/lab-colors
- Repository: https://github.com/labpics-team/lab-colors

## Overview

Lab Colors is a color-contract compiler and runtime: an application declares a physical color graph and constraints, then the runtime evaluates it against observed conditions and returns allowed outputs. The main path is the JavaScript package’s compile/update/read workflow, backed by Rust/WASM; a Rust evaluation CLI is an alternate entry point. Core internals cover graph compilation, color-space and constraint evaluation, and revision-bound observations. The README documents the public workflow; internal links below rely on sampled references, so unsampled wiring is omitted.

Main entry points: [`crates/labcolors-core/src/program_session.rs`](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program_session.rs) (Program evaluation), [`crates/labcolors-core/src/program.rs`](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program.rs) (Program compiler), [`packages/colors/index.js`](https://github.com/labpics-team/lab-colors/blob/main/packages/colors/index.js) (JS package API), [`crates/labcolors-wasm/src/lib.rs`](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-wasm/src/lib.rs) (WASM API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client interfaces"]
  node_js_api["JS package API<br/>[index.js]"]
  node_wire_abi["Program wire ABI<br/>[abi-v1.js]"]
  node_wasm_api["WASM API<br/>[lib.rs]"]
  node_evaluate_cli["Evaluation CLI<br/>[app.rs]"]
  node_transport_cli["Transport CLI<br/>[app.rs]"]
  node_transport["Transport envelopes<br/>[certificate.rs]"]
end

subgraph group_runtime["Program runtime"]
  node_program["Program compiler<br/>[program.rs]"]
  node_program_runtime["Program evaluation<br/>[program_session.rs]"]
  node_attachment["Output attachment<br/>[attachment.rs]"]
  node_certificate["Certificates<br/>[certificate.rs]"]
end

subgraph group_evaluation["Color evaluation"]
  node_composition["Color composition<br/>[composition.rs]"]
  node_render_graph["Render graph<br/>[appearance.rs]"]
  node_constraints["Constraint evaluation<br/>[mod.rs]"]
  node_wcag["WCAG 2.2<br/>[wcag22.rs]"]
  node_color_spaces["Color-space math<br/>[lcs_occurrence.rs]"]
  node_family["Color families<br/>[family.rs]"]
  node_family_artifact["Family artifacts<br/>[family_artifact.rs]"]
end

subgraph group_observations["Observation lifecycle"]
  node_observation["Observation admission<br/>[observation.rs]"]
  node_session["Session lifecycle<br/>[session.rs]"]
  node_field_effect["Field effects<br/>[field_effect.rs]"]
end

node_application(("Application"))

node_application -->|"declares program"| node_js_api
node_js_api -.->|"encodes wire"| node_wire_abi
node_js_api -->|"calls runtime"| node_wasm_api
node_application -->|"submits request"| node_evaluate_cli
node_application -->|"inspects envelope"| node_transport_cli
node_wasm_api -.->|"compiles program"| node_program
node_wasm_api -.->|"updates observations"| node_program_runtime
node_evaluate_cli -.->|"evaluates request"| node_program_runtime
node_program_runtime -->|"uses compiler model"| node_program
node_program -->|"uses render graph"| node_render_graph
node_program -->|"uses composition"| node_composition
node_program -->|"uses evaluators"| node_constraints
node_program_runtime -->|"assesses constraints"| node_constraints
node_program_runtime -->|"evaluates WCAG"| node_wcag
node_program_runtime -->|"checks family"| node_family
node_program_runtime -->|"loads artifacts"| node_family_artifact
node_program_runtime -->|"derives occurrences"| node_color_spaces
node_program_runtime -->|"runs session"| node_session
node_session -->|"admits updates"| node_observation
node_program_runtime -->|"binds observations"| node_observation
node_program_runtime -->|"evaluates effects"| node_field_effect
node_program_runtime -->|"attaches outputs"| node_attachment
node_attachment -->|"owns lifecycle"| node_session
node_program_runtime -.->|"produces evidence"| node_certificate
node_transport_cli -->|"parses envelopes"| node_transport

click node_js_api "https://github.com/labpics-team/lab-colors/blob/main/packages/colors/index.js"
click node_wire_abi "https://github.com/labpics-team/lab-colors/blob/main/packages/colors/program-wire/abi-v1.js"
click node_wasm_api "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-wasm/src/lib.rs"
click node_evaluate_cli "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-evaluate-cli/src/app.rs"
click node_transport_cli "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-transport-cli/src/app.rs"
click node_program "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program.rs"
click node_program_runtime "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program_session.rs"
click node_attachment "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program/attachment.rs"
click node_composition "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/composition.rs"
click node_render_graph "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/appearance.rs"
click node_constraints "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/constraints/mod.rs"
click node_wcag "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/wcag22.rs"
click node_color_spaces "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/lcs_occurrence.rs"
click node_family "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/family.rs"
click node_family_artifact "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/family_artifact.rs"
click node_observation "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/observation.rs"
click node_session "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/session.rs"
click node_field_effect "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/field_effect.rs"
click node_certificate "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/certificate.rs"
click node_transport "https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/certificate.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_js_api,node_wire_abi,node_wasm_api,node_evaluate_cli,node_transport_cli,node_transport toneBlue
class node_program,node_program_runtime,node_attachment,node_certificate toneAmber
class node_composition,node_render_graph,node_constraints,node_wcag,node_color_spaces,node_family,node_family_artifact toneMint
class node_observation,node_session,node_field_effect toneRose
class node_application toneIndigo
```

## Components

### Client interfaces

- [JS package API](https://github.com/labpics-team/lab-colors/blob/main/packages/colors/index.js): `packages/colors/index.js`
- [Program wire ABI](https://github.com/labpics-team/lab-colors/blob/main/packages/colors/program-wire/abi-v1.js): `packages/colors/program-wire/abi-v1.js`
- [WASM API](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-wasm/src/lib.rs): `crates/labcolors-wasm/src/lib.rs`
- [Evaluation CLI](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-evaluate-cli/src/app.rs): `crates/labcolors-evaluate-cli/src/app.rs`
- [Transport CLI](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-transport-cli/src/app.rs): `crates/labcolors-transport-cli/src/app.rs`
- [Transport envelopes](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/certificate.rs): `crates/labcolors-core/src/certificate.rs`

### Program runtime

- [Program compiler](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program.rs): `crates/labcolors-core/src/program.rs`
- [Program evaluation](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program_session.rs): `crates/labcolors-core/src/program_session.rs`
- [Output attachment](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/program/attachment.rs): `crates/labcolors-core/src/program/attachment.rs`
- [Certificates](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/certificate.rs): `crates/labcolors-core/src/certificate.rs`

### Color evaluation

- [Color composition](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/composition.rs): `crates/labcolors-core/src/composition.rs`
- [Render graph](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/appearance.rs): `crates/labcolors-core/src/appearance.rs`
- [Constraint evaluation](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/constraints/mod.rs): `crates/labcolors-core/src/constraints/mod.rs`
- [WCAG 2.2](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/wcag22.rs): `crates/labcolors-core/src/wcag22.rs`
- [Color-space math](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/lcs_occurrence.rs): `crates/labcolors-core/src/lcs_occurrence.rs`
- [Color families](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/family.rs): `crates/labcolors-core/src/family.rs`
- [Family artifacts](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/family_artifact.rs): `crates/labcolors-core/src/family_artifact.rs`

### Observation lifecycle

- [Observation admission](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/observation.rs): `crates/labcolors-core/src/observation.rs`
- [Session lifecycle](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/session.rs): `crates/labcolors-core/src/session.rs`
- [Field effects](https://github.com/labpics-team/lab-colors/blob/main/crates/labcolors-core/src/field_effect.rs): `crates/labcolors-core/src/field_effect.rs`

### Other components

- **Application**

## Connections

- Application → JS package API: declares program (evidence: `README.md`)
- JS package API → Program wire ABI: encodes wire
- JS package API → WASM API: calls runtime (evidence: `README.md`)
- Application → Evaluation CLI: submits request (evidence: `README.md`)
- Application → Transport CLI: inspects envelope (evidence: `README.md`)
- WASM API → Program compiler: compiles program
- WASM API → Program evaluation: updates observations
- Evaluation CLI → Program evaluation: evaluates request
- Program evaluation → Program compiler: uses compiler model (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program compiler → Render graph: uses render graph (evidence: `crates/labcolors-core/src/program.rs`)
- Program compiler → Color composition: uses composition (evidence: `crates/labcolors-core/src/program.rs`)
- Program compiler → Constraint evaluation: uses evaluators (evidence: `crates/labcolors-core/src/program.rs`)
- Program evaluation → Constraint evaluation: assesses constraints (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → WCAG 2.2: evaluates WCAG (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Color families: checks family (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Family artifacts: loads artifacts (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Color-space math: derives occurrences (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Session lifecycle: runs session (evidence: `crates/labcolors-core/src/program_session.rs`)
- Session lifecycle → Observation admission: admits updates (evidence: `crates/labcolors-core/src/session.rs`)
- Program evaluation → Observation admission: binds observations (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Field effects: evaluates effects (evidence: `crates/labcolors-core/src/program_session.rs`)
- Program evaluation → Output attachment: attaches outputs (evidence: `crates/labcolors-core/src/program_session.rs`)
- Output attachment → Session lifecycle: owns lifecycle (evidence: `crates/labcolors-core/src/program/attachment.rs`)
- Program evaluation → Certificates: produces evidence
- Transport CLI → Transport envelopes: parses envelopes (evidence: `crates/labcolors-transport-cli/src/app.rs`)
