# pavaram/devbox architecture

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

- Interactive diagram: https://gitdiagram.com/pavaram/devbox
- Repository: https://github.com/pavaram/devbox

## Overview

DevBox is a Bash infrastructure-provisioning tool. An operator invokes the CLI to detect the Linux distribution and load configuration, then selects installation, Docker setup, hardening, diagnostics, or profile and hook operations. The documented architecture maps configuration and package mapping into those capabilities, with diagnostic reporting and structured logs as outputs. The README supplies the relationships shown here; source excerpts were unavailable, so relationships for other listed library modules are not inferred.

Main entry points: [`devbox.sh`](https://github.com/pavaram/devbox/blob/main/devbox.sh) (CLI entrypoint), [`lib/config.sh`](https://github.com/pavaram/devbox/blob/main/lib/config.sh) (Config loader), [`lib/packages.sh`](https://github.com/pavaram/devbox/blob/main/lib/packages.sh) (Package management), [`lib/security.sh`](https://github.com/pavaram/devbox/blob/main/lib/security.sh) (SSH and firewall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and setup"]
  node_cli["CLI entrypoint<br/>[devbox.sh]"]
  node_distro["Distro detection<br/>[distro.sh]"]
  node_pkgmap["Package mapping<br/>[pkgmap.sh]"]
  node_configloader["Config loader<br/>[config.sh]"]
  node_state["State tracking<br/>[state.sh]"]
  node_version["Version management<br/>[version-manager.sh]"]
end

subgraph group_configuration["Configuration"]
  node_pkgconfig["Package settings<br/>[pkg.conf]"]
  node_securityconfig["Security settings<br/>[security.conf]"]
  node_loggerconfig["Logger settings<br/>[logger.conf]"]
  node_profileconfigs["Profile definitions"]
  node_hookconfigs["Lifecycle scripts"]
end

subgraph group_provisioning["Provisioning"]
  node_profiles["Profile engine<br/>[profiles.sh]"]
  node_packages["Package management<br/>[packages.sh]"]
  node_packagehost[("System packages")]
  node_hooks["Hook runner<br/>[hooks.sh]"]
  node_docker["Docker setup<br/>[docker.sh]"]
  node_dockerhost[("Docker engine")]
end

subgraph group_security["Security"]
  node_security["SSH and firewall<br/>[security.sh]"]
  node_securehost[("Hardened host")]
end

subgraph group_operations["Operations and observability"]
  node_diagnostics["Health checks<br/>[diagnostics.sh]"]
  node_reporting["Report generation<br/>[reporting.sh]"]
  node_reports[("Diagnostic reports")]
  node_logging["Structured logging<br/>[logging.sh]"]
  node_logfiles[("Execution logs")]
  node_diagnosticconfig["Diagnostics settings<br/>[diagnostics.sh]"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_cli -->|"detects distro"| node_distro
node_distro -->|"maps packages"| node_pkgmap
node_cli -->|"loads config"| node_configloader
node_configloader -->|"loads"| node_pkgconfig
node_configloader -->|"loads"| node_securityconfig
node_configloader -->|"loads"| node_loggerconfig
node_configloader -->|"loads"| node_profileconfigs
node_configloader -->|"loads"| node_hookconfigs
node_cli -->|"installs"| node_packages
node_cli -->|"sets up Docker"| node_docker
node_cli -->|"hardens"| node_security
node_cli -->|"runs checks"| node_diagnostics
node_cli -->|"manages profiles"| node_profiles
node_cli -->|"runs hooks"| node_hooks
node_pkgconfig -->|"configures"| node_packages
node_securityconfig -->|"configures"| node_security
node_loggerconfig -->|"configures"| node_logging
node_profileconfigs -->|"defines profiles"| node_profiles
node_hookconfigs -->|"provides scripts"| node_hooks
node_pkgmap -->|"maps names"| node_packages
node_packages -->|"installs"| node_packagehost
node_docker -->|"configures"| node_dockerhost
node_security -->|"hardens"| node_securehost
node_diagnostics -->|"generates reports"| node_reporting
node_reporting -->|"writes"| node_reports
node_logging -->|"writes"| node_logfiles

click node_cli "https://github.com/pavaram/devbox/blob/main/devbox.sh"
click node_distro "https://github.com/pavaram/devbox/blob/main/lib/distro.sh"
click node_pkgmap "https://github.com/pavaram/devbox/blob/main/lib/pkgmap.sh"
click node_configloader "https://github.com/pavaram/devbox/blob/main/lib/config.sh"
click node_state "https://github.com/pavaram/devbox/blob/main/lib/state.sh"
click node_version "https://github.com/pavaram/devbox/blob/main/lib/version-manager.sh"
click node_pkgconfig "https://github.com/pavaram/devbox/blob/main/conf/pkg.conf"
click node_securityconfig "https://github.com/pavaram/devbox/blob/main/conf/security.conf"
click node_loggerconfig "https://github.com/pavaram/devbox/blob/main/conf/logger.conf"
click node_profileconfigs "https://github.com/pavaram/devbox/tree/main/conf/profiles"
click node_hookconfigs "https://github.com/pavaram/devbox/tree/main/conf/hooks"
click node_profiles "https://github.com/pavaram/devbox/blob/main/lib/profiles.sh"
click node_packages "https://github.com/pavaram/devbox/blob/main/lib/packages.sh"
click node_hooks "https://github.com/pavaram/devbox/blob/main/lib/hooks.sh"
click node_docker "https://github.com/pavaram/devbox/blob/main/lib/docker.sh"
click node_security "https://github.com/pavaram/devbox/blob/main/lib/security.sh"
click node_diagnostics "https://github.com/pavaram/devbox/blob/main/lib/diagnostics.sh"
click node_reporting "https://github.com/pavaram/devbox/blob/main/lib/reporting.sh"
click node_logging "https://github.com/pavaram/devbox/blob/main/lib/logging.sh"
click node_diagnosticconfig "https://github.com/pavaram/devbox/blob/main/lib/diagnostics.sh"

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_cli,node_distro,node_pkgmap,node_configloader,node_state,node_version toneBlue
class node_pkgconfig,node_securityconfig,node_loggerconfig,node_profileconfigs,node_hookconfigs toneAmber
class node_profiles,node_packages,node_packagehost,node_hooks,node_docker,node_dockerhost toneMint
class node_security,node_securehost toneRose
class node_diagnostics,node_reporting,node_reports,node_logging,node_logfiles,node_diagnosticconfig,node_operator toneIndigo
```

## Components

### Entry and setup

- [CLI entrypoint](https://github.com/pavaram/devbox/blob/main/devbox.sh): `devbox.sh`
- [Distro detection](https://github.com/pavaram/devbox/blob/main/lib/distro.sh): `lib/distro.sh`
- [Package mapping](https://github.com/pavaram/devbox/blob/main/lib/pkgmap.sh): `lib/pkgmap.sh`
- [Config loader](https://github.com/pavaram/devbox/blob/main/lib/config.sh): `lib/config.sh`
- [State tracking](https://github.com/pavaram/devbox/blob/main/lib/state.sh): `lib/state.sh`
- [Version management](https://github.com/pavaram/devbox/blob/main/lib/version-manager.sh): `lib/version-manager.sh`

### Configuration

- [Package settings](https://github.com/pavaram/devbox/blob/main/conf/pkg.conf): `conf/pkg.conf`
- [Security settings](https://github.com/pavaram/devbox/blob/main/conf/security.conf): `conf/security.conf`
- [Logger settings](https://github.com/pavaram/devbox/blob/main/conf/logger.conf): `conf/logger.conf`
- [Profile definitions](https://github.com/pavaram/devbox/tree/main/conf/profiles): `conf/profiles`
- [Lifecycle scripts](https://github.com/pavaram/devbox/tree/main/conf/hooks): `conf/hooks`

### Provisioning

- [Profile engine](https://github.com/pavaram/devbox/blob/main/lib/profiles.sh): `lib/profiles.sh`
- [Package management](https://github.com/pavaram/devbox/blob/main/lib/packages.sh): `lib/packages.sh`
- **System packages**
- [Hook runner](https://github.com/pavaram/devbox/blob/main/lib/hooks.sh): `lib/hooks.sh`
- [Docker setup](https://github.com/pavaram/devbox/blob/main/lib/docker.sh): `lib/docker.sh`
- **Docker engine**

### Security

- [SSH and firewall](https://github.com/pavaram/devbox/blob/main/lib/security.sh): `lib/security.sh`
- **Hardened host**

### Operations and observability

- [Health checks](https://github.com/pavaram/devbox/blob/main/lib/diagnostics.sh): `lib/diagnostics.sh`
- [Report generation](https://github.com/pavaram/devbox/blob/main/lib/reporting.sh): `lib/reporting.sh`
- **Diagnostic reports**
- [Structured logging](https://github.com/pavaram/devbox/blob/main/lib/logging.sh): `lib/logging.sh`
- **Execution logs**
- [Diagnostics settings](https://github.com/pavaram/devbox/blob/main/lib/diagnostics.sh): `lib/diagnostics.sh`

### Other components

- **Operator**

## Connections

- Operator → CLI entrypoint: invokes (evidence: `README.md`)
- CLI entrypoint → Distro detection: detects distro (evidence: `README.md`)
- Distro detection → Package mapping: maps packages (evidence: `README.md`)
- CLI entrypoint → Config loader: loads config (evidence: `README.md`)
- Config loader → Package settings: loads (evidence: `README.md`)
- Config loader → Security settings: loads (evidence: `README.md`)
- Config loader → Logger settings: loads (evidence: `README.md`)
- Config loader → Profile definitions: loads (evidence: `README.md`)
- Config loader → Lifecycle scripts: loads (evidence: `README.md`)
- CLI entrypoint → Package management: installs (evidence: `README.md`)
- CLI entrypoint → Docker setup: sets up Docker (evidence: `README.md`)
- CLI entrypoint → SSH and firewall: hardens (evidence: `README.md`)
- CLI entrypoint → Health checks: runs checks (evidence: `README.md`)
- CLI entrypoint → Profile engine: manages profiles (evidence: `README.md`)
- CLI entrypoint → Hook runner: runs hooks (evidence: `README.md`)
- Package settings → Package management: configures (evidence: `README.md`)
- Security settings → SSH and firewall: configures (evidence: `README.md`)
- Logger settings → Structured logging: configures (evidence: `README.md`)
- Profile definitions → Profile engine: defines profiles (evidence: `README.md`)
- Lifecycle scripts → Hook runner: provides scripts (evidence: `README.md`)
- Package mapping → Package management: maps names (evidence: `README.md`)
- Package management → System packages: installs (evidence: `README.md`)
- Docker setup → Docker engine: configures (evidence: `README.md`)
- SSH and firewall → Hardened host: hardens (evidence: `README.md`)
- Health checks → Report generation: generates reports (evidence: `README.md`)
- Report generation → Diagnostic reports: writes (evidence: `README.md`)
- Structured logging → Execution logs: writes (evidence: `README.md`)
