# goss-org/goss architecture

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

- Interactive diagram: https://gitdiagram.com/goss-org/goss
- Repository: https://github.com/goss-org/goss

## Overview

Goss is a YAML-based server-configuration validator. Users can generate resource checks from the current machine, edit or template the resulting Goss files, then validate them once or with retries, or expose validation as a health endpoint. The core stages are CLI dispatch, configuration/resource loading, resource validation against system probes, and formatted results; service checks illustrate the resource-to-system boundary. README documents render, templates, add/autoadd, retry, and serving. Some orchestration links are based on documented behavior because those source excerpts were not supplied.

Main entry points: [`cmd/goss/goss.go`](https://github.com/goss-org/goss/blob/master/cmd/goss/goss.go) (Goss CLI), [`validate.go`](https://github.com/goss-org/goss/blob/master/validate.go) (Validate command), [`goss_config.go`](https://github.com/goss-org/goss/blob/master/goss_config.go) (Goss configuration), [`system/system.go`](https://github.com/goss-org/goss/blob/master/system/system.go) (System abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and workflows"]
  node_cli["Goss CLI<br/>[goss.go]"]
  node_add["Add resources<br/>[add.go]"]
  node_validate["Validate command<br/>[validate.go]"]
  node_serve["Health server<br/>[serve.go]"]
end

subgraph group_config["Goss files"]
  node_configfile["Goss configuration<br/>[goss_config.go]"]
  node_templates["Template rendering<br/>[template.go]"]
  node_store["Configuration store<br/>[store.go]"]
end

subgraph group_validation["Validation engine"]
  node_resource_list["Resource collection<br/>[resource_list.go]"]
  node_resource_service["Service checks<br/>[service.go]"]
  node_matchers["Matchers<br/>[matchers.go]"]
end

subgraph group_probes["System probes"]
  node_system["System abstraction<br/>[system.go]"]
  node_service_probe["Service probes<br/>[service_systemd.go]"]
  node_command["Command runner<br/>[command.go]"]
end

subgraph group_results["Results and serving"]
  node_outputs["Output formats<br/>[outputs.go]"]
  node_json_output["JSON output<br/>[json.go]"]
  node_retry["Validation retry<br/>[retry.go]"]
end

node_user(("Operator"))
node_http_client(("Health endpoint client"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches add"| node_add
node_cli -->|"dispatches validate"| node_validate
node_cli -->|"dispatches serve"| node_serve
node_cli -->|"dispatches render"| node_templates
node_add -->|"detects resources"| node_system
node_add -->|"writes checks"| node_configfile
node_validate -->|"loads checks"| node_configfile
node_templates -->|"renders imports"| node_configfile
node_configfile -->|"loads configuration"| node_store
node_store -->|"builds resources"| node_resource_list
node_resource_list -->|"creates probes"| node_system
node_resource_service -->|"requests service"| node_system
node_resource_service -->|"checks values"| node_matchers
node_system -->|"selects implementation"| node_service_probe
node_service_probe -->|"runs commands"| node_command
node_validate -->|"retries checks"| node_retry
node_validate -->|"formats results"| node_outputs
node_serve -->|"formats response"| node_outputs
node_http_client -->|"requests health"| node_serve
node_outputs -->|"selects format"| node_json_output

click node_cli "https://github.com/goss-org/goss/blob/master/cmd/goss/goss.go"
click node_add "https://github.com/goss-org/goss/blob/master/add.go"
click node_validate "https://github.com/goss-org/goss/blob/master/validate.go"
click node_serve "https://github.com/goss-org/goss/blob/master/serve.go"
click node_configfile "https://github.com/goss-org/goss/blob/master/goss_config.go"
click node_templates "https://github.com/goss-org/goss/blob/master/template.go"
click node_store "https://github.com/goss-org/goss/blob/master/store.go"
click node_resource_list "https://github.com/goss-org/goss/blob/master/resource/resource_list.go"
click node_resource_service "https://github.com/goss-org/goss/blob/master/resource/service.go"
click node_matchers "https://github.com/goss-org/goss/blob/master/matchers/matchers.go"
click node_system "https://github.com/goss-org/goss/blob/master/system/system.go"
click node_service_probe "https://github.com/goss-org/goss/blob/master/system/service_systemd.go"
click node_command "https://github.com/goss-org/goss/blob/master/util/command.go"
click node_outputs "https://github.com/goss-org/goss/blob/master/outputs/outputs.go"
click node_json_output "https://github.com/goss-org/goss/blob/master/outputs/json.go"
click node_retry "https://github.com/goss-org/goss/blob/master/resource/retry.go"

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_add,node_validate,node_serve,node_http_client toneBlue
class node_configfile,node_templates,node_store toneAmber
class node_resource_list,node_resource_service,node_matchers toneMint
class node_system,node_service_probe,node_command toneRose
class node_outputs,node_json_output,node_retry,node_user toneIndigo
```

## Components

### CLI and workflows

- [Goss CLI](https://github.com/goss-org/goss/blob/master/cmd/goss/goss.go): `cmd/goss/goss.go`
- [Add resources](https://github.com/goss-org/goss/blob/master/add.go): `add.go`
- [Validate command](https://github.com/goss-org/goss/blob/master/validate.go): `validate.go`
- [Health server](https://github.com/goss-org/goss/blob/master/serve.go): `serve.go`

### Goss files

- [Goss configuration](https://github.com/goss-org/goss/blob/master/goss_config.go): `goss_config.go`
- [Template rendering](https://github.com/goss-org/goss/blob/master/template.go): `template.go`
- [Configuration store](https://github.com/goss-org/goss/blob/master/store.go): `store.go`

### Validation engine

- [Resource collection](https://github.com/goss-org/goss/blob/master/resource/resource_list.go): `resource/resource_list.go`
- [Service checks](https://github.com/goss-org/goss/blob/master/resource/service.go): `resource/service.go`
- [Matchers](https://github.com/goss-org/goss/blob/master/matchers/matchers.go): `matchers/matchers.go`

### System probes

- [System abstraction](https://github.com/goss-org/goss/blob/master/system/system.go): `system/system.go`
- [Service probes](https://github.com/goss-org/goss/blob/master/system/service_systemd.go): `system/service_systemd.go`
- [Command runner](https://github.com/goss-org/goss/blob/master/util/command.go): `util/command.go`

### Results and serving

- [Output formats](https://github.com/goss-org/goss/blob/master/outputs/outputs.go): `outputs/outputs.go`
- [JSON output](https://github.com/goss-org/goss/blob/master/outputs/json.go): `outputs/json.go`
- [Validation retry](https://github.com/goss-org/goss/blob/master/resource/retry.go): `resource/retry.go`

### Other components

- **Operator**
- **Health endpoint client**

## Connections

- Operator → Goss CLI: invokes
- Goss CLI → Add resources: dispatches add
- Goss CLI → Validate command: dispatches validate
- Goss CLI → Health server: dispatches serve
- Goss CLI → Template rendering: dispatches render
- Add resources → System abstraction: detects resources
- Add resources → Goss configuration: writes checks
- Validate command → Goss configuration: loads checks
- Template rendering → Goss configuration: renders imports
- Goss configuration → Configuration store: loads configuration
- Configuration store → Resource collection: builds resources
- Resource collection → System abstraction: creates probes
- Service checks → System abstraction: requests service
- Service checks → Matchers: checks values
- System abstraction → Service probes: selects implementation
- Service probes → Command runner: runs commands
- Validate command → Validation retry: retries checks
- Validate command → Output formats: formats results
- Health server → Output formats: formats response
- Health endpoint client → Health server: requests health
- Output formats → JSON output: selects format
