# aerynos/os-tools architecture

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

- Interactive diagram: https://gitdiagram.com/aerynos/os-tools
- Repository: https://github.com/aerynos/os-tools

## Overview

This workspace provides moss, a package and system-state manager; boulder, a sandboxed package builder; and the shared .stone package-format implementation. The principal moss workflow is a user command through the CLI and client, which resolves packages from repositories and plugins, then changes or queries installation state. Boulder turns YAML recipes and upstream sources into analyzed, split packages and emits .stone artifacts. README capabilities are represented, but unsampled module wiring is shown only where documented or supported by the available excerpts.

Main entry points: [`moss/src/client/mod.rs`](https://github.com/aerynos/os-tools/blob/main/moss/src/client/mod.rs) (Package client), [`boulder/src/build.rs`](https://github.com/aerynos/os-tools/blob/main/boulder/src/build.rs) (Sandboxed build), [`moss/src/cli/mod.rs`](https://github.com/aerynos/os-tools/blob/main/moss/src/cli/mod.rs) (Moss commands), [`moss/src/repository/manager.rs`](https://github.com/aerynos/os-tools/blob/main/moss/src/repository/manager.rs) (Repository manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_moss["Moss manager"]
  node_moss_cli["Moss commands<br/>[mod.rs]"]
  node_moss_client["Package client<br/>[mod.rs]"]
  node_repo_manager["Repository manager<br/>[manager.rs]"]
  node_repository_index["Repository indexes<br/>[root_index.rs]"]
  node_registry["Package registry<br/>[mod.rs]"]
  node_repo_plugin["Repository plugin<br/>[repository.rs]"]
  node_package["Package metadata<br/>[mod.rs]"]
  node_installation["Installation<br/>[installation.rs]"]
  node_state_db[("State database<br/>[mod.rs]")]
  node_meta_db[("Metadata database<br/>[mod.rs]")]
  node_system_model["System model<br/>[system_model.rs]"]
end

subgraph group_boulder["Boulder builder"]
  node_boulder_cli["Boulder commands<br/>[cli.rs]"]
  node_recipe["Build recipe<br/>[recipe.rs]"]
  node_upstream["Upstream sources<br/>[upstream.rs]"]
  node_build["Sandboxed build<br/>[build.rs]"]
  node_container["Build container<br/>[container.rs]"]
  node_draft["Package draft<br/>[draft.rs]"]
  node_analysis["Package analysis<br/>[analysis.rs]"]
  node_collect["Package collection<br/>[collect.rs]"]
  node_emit["Package emission<br/>[emit.rs]"]
end

subgraph group_stone["Stone format"]
  node_stone["Stone format<br/>[lib.rs]"]
  node_artifact["Stone package"]
end

subgraph group_shared["Shared capabilities"]
  node_triggers["Transaction triggers<br/>[lib.rs]"]
end

node_user(("User"))
node_repo_service(("Package repository"))

node_user -->|"invokes"| node_moss_cli
node_moss_cli -->|"dispatches"| node_moss_client
node_moss_client -->|"queries"| node_registry
node_registry -->|"dispatches"| node_repo_plugin
node_repo_plugin -->|"queries"| node_meta_db
node_repo_plugin -->|"returns metadata"| node_package
node_moss_client -->|"manages state"| node_installation
node_moss_client -->|"reads and writes"| node_state_db
node_moss_client -->|"executes"| node_triggers
node_moss_client -->|"exports model"| node_system_model
node_moss_cli -->|"manages repositories"| node_repo_manager
node_repo_manager -.->|"fetches indexes"| node_repo_service
node_repo_manager -->|"updates metadata"| node_repository_index
node_user -->|"invokes"| node_boulder_cli
node_boulder_cli -->|"loads recipe"| node_recipe
node_boulder_cli -->|"starts build"| node_build
node_build -->|"runs sandbox"| node_container
node_build -->|"fetches sources"| node_upstream
node_build -->|"creates draft"| node_draft
node_draft -->|"analyzes files"| node_analysis
node_draft -->|"collects packages"| node_collect
node_collect -->|"emits packages"| node_emit
node_emit -->|"encodes format"| node_stone
node_stone -->|"writes package"| node_artifact
node_moss_client -->|"reads packages"| node_stone

click node_moss_cli "https://github.com/aerynos/os-tools/blob/main/moss/src/cli/mod.rs"
click node_moss_client "https://github.com/aerynos/os-tools/blob/main/moss/src/client/mod.rs"
click node_repo_manager "https://github.com/aerynos/os-tools/blob/main/moss/src/repository/manager.rs"
click node_repository_index "https://github.com/aerynos/os-tools/blob/main/moss/src/repository/format/root_index.rs"
click node_registry "https://github.com/aerynos/os-tools/blob/main/moss/src/registry/mod.rs"
click node_repo_plugin "https://github.com/aerynos/os-tools/blob/main/moss/src/registry/plugin/repository.rs"
click node_package "https://github.com/aerynos/os-tools/blob/main/moss/src/package/mod.rs"
click node_installation "https://github.com/aerynos/os-tools/blob/main/moss/src/installation.rs"
click node_state_db "https://github.com/aerynos/os-tools/blob/main/moss/src/db/state/mod.rs"
click node_meta_db "https://github.com/aerynos/os-tools/blob/main/moss/src/db/meta/mod.rs"
click node_system_model "https://github.com/aerynos/os-tools/blob/main/moss/src/system_model.rs"
click node_triggers "https://github.com/aerynos/os-tools/blob/main/crates/triggers/src/lib.rs"
click node_boulder_cli "https://github.com/aerynos/os-tools/blob/main/boulder/src/cli.rs"
click node_recipe "https://github.com/aerynos/os-tools/blob/main/boulder/src/recipe.rs"
click node_upstream "https://github.com/aerynos/os-tools/blob/main/boulder/src/upstream.rs"
click node_build "https://github.com/aerynos/os-tools/blob/main/boulder/src/build.rs"
click node_container "https://github.com/aerynos/os-tools/blob/main/boulder/src/container.rs"
click node_draft "https://github.com/aerynos/os-tools/blob/main/boulder/src/draft.rs"
click node_analysis "https://github.com/aerynos/os-tools/blob/main/boulder/src/package/analysis.rs"
click node_collect "https://github.com/aerynos/os-tools/blob/main/boulder/src/package/collect.rs"
click node_emit "https://github.com/aerynos/os-tools/blob/main/boulder/src/package/emit.rs"
click node_stone "https://github.com/aerynos/os-tools/blob/main/crates/stone/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_moss_cli,node_moss_client,node_repo_manager,node_repository_index,node_registry,node_repo_plugin,node_package,node_installation,node_state_db,node_meta_db,node_system_model,node_user toneBlue
class node_boulder_cli,node_recipe,node_upstream,node_build,node_container,node_draft,node_analysis,node_collect,node_emit toneAmber
class node_stone,node_artifact toneMint
class node_triggers toneRose
class node_repo_service toneIndigo
```

## Components

### Moss manager

- [Moss commands](https://github.com/aerynos/os-tools/blob/main/moss/src/cli/mod.rs): `moss/src/cli/mod.rs`
- [Package client](https://github.com/aerynos/os-tools/blob/main/moss/src/client/mod.rs): `moss/src/client/mod.rs`
- [Repository manager](https://github.com/aerynos/os-tools/blob/main/moss/src/repository/manager.rs): `moss/src/repository/manager.rs`
- [Repository indexes](https://github.com/aerynos/os-tools/blob/main/moss/src/repository/format/root_index.rs): `moss/src/repository/format/root_index.rs`
- [Package registry](https://github.com/aerynos/os-tools/blob/main/moss/src/registry/mod.rs): `moss/src/registry/mod.rs`
- [Repository plugin](https://github.com/aerynos/os-tools/blob/main/moss/src/registry/plugin/repository.rs): `moss/src/registry/plugin/repository.rs`
- [Package metadata](https://github.com/aerynos/os-tools/blob/main/moss/src/package/mod.rs): `moss/src/package/mod.rs`
- [Installation](https://github.com/aerynos/os-tools/blob/main/moss/src/installation.rs): `moss/src/installation.rs`
- [State database](https://github.com/aerynos/os-tools/blob/main/moss/src/db/state/mod.rs): `moss/src/db/state/mod.rs`
- [Metadata database](https://github.com/aerynos/os-tools/blob/main/moss/src/db/meta/mod.rs): `moss/src/db/meta/mod.rs`
- [System model](https://github.com/aerynos/os-tools/blob/main/moss/src/system_model.rs): `moss/src/system_model.rs`

### Boulder builder

- [Boulder commands](https://github.com/aerynos/os-tools/blob/main/boulder/src/cli.rs): `boulder/src/cli.rs`
- [Build recipe](https://github.com/aerynos/os-tools/blob/main/boulder/src/recipe.rs): `boulder/src/recipe.rs`
- [Upstream sources](https://github.com/aerynos/os-tools/blob/main/boulder/src/upstream.rs): `boulder/src/upstream.rs`
- [Sandboxed build](https://github.com/aerynos/os-tools/blob/main/boulder/src/build.rs): `boulder/src/build.rs`
- [Build container](https://github.com/aerynos/os-tools/blob/main/boulder/src/container.rs): `boulder/src/container.rs`
- [Package draft](https://github.com/aerynos/os-tools/blob/main/boulder/src/draft.rs): `boulder/src/draft.rs`
- [Package analysis](https://github.com/aerynos/os-tools/blob/main/boulder/src/package/analysis.rs): `boulder/src/package/analysis.rs`
- [Package collection](https://github.com/aerynos/os-tools/blob/main/boulder/src/package/collect.rs): `boulder/src/package/collect.rs`
- [Package emission](https://github.com/aerynos/os-tools/blob/main/boulder/src/package/emit.rs): `boulder/src/package/emit.rs`

### Stone format

- [Stone format](https://github.com/aerynos/os-tools/blob/main/crates/stone/src/lib.rs): `crates/stone/src/lib.rs`
- **Stone package**

### Shared capabilities

- [Transaction triggers](https://github.com/aerynos/os-tools/blob/main/crates/triggers/src/lib.rs): `crates/triggers/src/lib.rs`

### Other components

- **User**
- **Package repository**

## Connections

- User → Moss commands: invokes
- Moss commands → Package client: dispatches
- Package client → Package registry: queries
- Package registry → Repository plugin: dispatches
- Repository plugin → Metadata database: queries
- Repository plugin → Package metadata: returns metadata
- Package client → Installation: manages state
- Package client → State database: reads and writes
- Package client → Transaction triggers: executes
- Package client → System model: exports model
- Moss commands → Repository manager: manages repositories
- Repository manager → Package repository: fetches indexes
- Repository manager → Repository indexes: updates metadata
- User → Boulder commands: invokes
- Boulder commands → Build recipe: loads recipe
- Boulder commands → Sandboxed build: starts build
- Sandboxed build → Build container: runs sandbox
- Sandboxed build → Upstream sources: fetches sources
- Sandboxed build → Package draft: creates draft
- Package draft → Package analysis: analyzes files
- Package draft → Package collection: collects packages
- Package collection → Package emission: emits packages
- Package emission → Stone format: encodes format
- Stone format → Stone package: writes package
- Package client → Stone format: reads packages