# samirkoirala/devops-doctor architecture

> Architecture diagram of the GitHub repository samirkoirala/devops-doctor, 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/samirkoirala/devops-doctor
- Repository: https://github.com/samirkoirala/devops-doctor

## Overview

devops-doctor is a Go CLI for diagnosing a local machine and its DevOps toolchain. A user selects a full or targeted check; the CLI delegates selection and optional-suite detection to the runner, which invokes the relevant diagnostic suites. Suites inspect system health, nginx, Docker, Compose, and Kubernetes, then return findings for human or JSON formatting. The README documents these capabilities; sampled source confirms the principal calls and command execution layer.

Main entry points: [`internal/output/result.go`](https://github.com/samirkoirala/devops-doctor/blob/main/internal/output/result.go) (Result model), [`internal/runner/runner.go`](https://github.com/samirkoirala/devops-doctor/blob/main/internal/runner/runner.go) (Check runner), [`pkg/utils/exec.go`](https://github.com/samirkoirala/devops-doctor/blob/main/pkg/utils/exec.go) (Command executor), [`internal/system/checks.go`](https://github.com/samirkoirala/devops-doctor/blob/main/internal/system/checks.go) (System checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI entrypoint<br/>[main.go]"]
  node_runner["Check runner<br/>[runner.go]"]
end

subgraph group_diagnostics["Diagnostic suites"]
  node_system["System checks<br/>[checks.go]"]
  node_disk["Disk checks<br/>[disk.go]"]
  node_nginx["nginx checks<br/>[checks.go]"]
  node_docker["Docker checks<br/>[checks.go]"]
  node_compose["Compose checks<br/>[checks.go]"]
  node_k8s["Kubernetes checks<br/>[checks.go]"]
  node_ports["Port checks<br/>[ports.go]"]
end

subgraph group_reporting["Results and reporting"]
  node_result["Result model<br/>[result.go]"]
  node_formatter["Output formatter<br/>[formatter.go]"]
end

subgraph group_execution["Command execution"]
  node_exec["Command executor<br/>[exec.go]"]
end

node_user(("User"))
node_host["Host tools and OS"]
node_kubecluster{{"Kubernetes cluster"}}
node_terminal["Terminal or JSON consumer"]

node_user -->|"invokes"| node_cli
node_cli -->|"selects checks"| node_runner
node_cli -->|"configures and calls"| node_formatter
node_runner -->|"runs"| node_system
node_runner -->|"runs"| node_nginx
node_runner -->|"runs"| node_docker
node_runner -->|"discovers and runs"| node_compose
node_runner -->|"detects and runs"| node_k8s
node_system -->|"calls disk check"| node_disk
node_docker -->|"calls port check"| node_ports
node_system -->|"runs commands"| node_exec
node_disk -->|"runs df"| node_exec
node_nginx -->|"runs commands"| node_exec
node_docker -->|"runs commands"| node_exec
node_compose -->|"runs commands"| node_exec
node_k8s -->|"runs commands"| node_exec
node_ports -->|"checks listeners"| node_exec
node_exec -->|"executes commands and reads OS"| node_host
node_k8s -->|"queries via kubectl"| node_kubecluster
node_system -->|"creates findings"| node_result
node_disk -->|"creates findings"| node_result
node_nginx -->|"creates findings"| node_result
node_docker -->|"creates findings"| node_result
node_compose -->|"creates findings"| node_result
node_k8s -->|"creates findings"| node_result
node_ports -->|"creates findings"| node_result
node_runner -->|"orders findings"| node_result
node_formatter -->|"renders findings"| node_result
node_formatter -->|"prints output"| node_terminal

click node_cli "https://github.com/samirkoirala/devops-doctor/blob/main/cmd/devops-doctor/main.go"
click node_runner "https://github.com/samirkoirala/devops-doctor/blob/main/internal/runner/runner.go"
click node_system "https://github.com/samirkoirala/devops-doctor/blob/main/internal/system/checks.go"
click node_disk "https://github.com/samirkoirala/devops-doctor/blob/main/internal/system/disk.go"
click node_nginx "https://github.com/samirkoirala/devops-doctor/blob/main/internal/nginx/checks.go"
click node_docker "https://github.com/samirkoirala/devops-doctor/blob/main/internal/docker/checks.go"
click node_compose "https://github.com/samirkoirala/devops-doctor/blob/main/internal/compose/checks.go"
click node_k8s "https://github.com/samirkoirala/devops-doctor/blob/main/internal/k8s/checks.go"
click node_ports "https://github.com/samirkoirala/devops-doctor/blob/main/internal/network/ports.go"
click node_result "https://github.com/samirkoirala/devops-doctor/blob/main/internal/output/result.go"
click node_formatter "https://github.com/samirkoirala/devops-doctor/blob/main/internal/output/formatter.go"
click node_exec "https://github.com/samirkoirala/devops-doctor/blob/main/pkg/utils/exec.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_runner,node_user toneBlue
class node_system,node_disk,node_nginx,node_docker,node_compose,node_k8s,node_ports toneAmber
class node_result,node_formatter toneMint
class node_exec toneRose
class node_host,node_kubecluster,node_terminal toneIndigo
```

## Components

### CLI and orchestration

- [CLI entrypoint](https://github.com/samirkoirala/devops-doctor/blob/main/cmd/devops-doctor/main.go): `cmd/devops-doctor/main.go`
- [Check runner](https://github.com/samirkoirala/devops-doctor/blob/main/internal/runner/runner.go): `internal/runner/runner.go`

### Diagnostic suites

- [System checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/system/checks.go): `internal/system/checks.go`
- [Disk checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/system/disk.go): `internal/system/disk.go`
- [nginx checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/nginx/checks.go): `internal/nginx/checks.go`
- [Docker checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/docker/checks.go): `internal/docker/checks.go`
- [Compose checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/compose/checks.go): `internal/compose/checks.go`
- [Kubernetes checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/k8s/checks.go): `internal/k8s/checks.go`
- [Port checks](https://github.com/samirkoirala/devops-doctor/blob/main/internal/network/ports.go): `internal/network/ports.go`

### Results and reporting

- [Result model](https://github.com/samirkoirala/devops-doctor/blob/main/internal/output/result.go): `internal/output/result.go`
- [Output formatter](https://github.com/samirkoirala/devops-doctor/blob/main/internal/output/formatter.go): `internal/output/formatter.go`

### Command execution

- [Command executor](https://github.com/samirkoirala/devops-doctor/blob/main/pkg/utils/exec.go): `pkg/utils/exec.go`

### Other components

- **User**
- **Host tools and OS**
- **Kubernetes cluster**
- **Terminal or JSON consumer**

## Connections

- User → CLI entrypoint: invokes
- CLI entrypoint → Check runner: selects checks
- CLI entrypoint → Output formatter: configures and calls
- Check runner → System checks: runs
- Check runner → nginx checks: runs
- Check runner → Docker checks: runs
- Check runner → Compose checks: discovers and runs
- Check runner → Kubernetes checks: detects and runs
- System checks → Disk checks: calls disk check
- Docker checks → Port checks: calls port check
- System checks → Command executor: runs commands
- Disk checks → Command executor: runs df
- nginx checks → Command executor: runs commands
- Docker checks → Command executor: runs commands
- Compose checks → Command executor: runs commands
- Kubernetes checks → Command executor: runs commands
- Port checks → Command executor: checks listeners
- Command executor → Host tools and OS: executes commands and reads OS
- Kubernetes checks → Kubernetes cluster: queries via kubectl
- System checks → Result model: creates findings
- Disk checks → Result model: creates findings
- nginx checks → Result model: creates findings
- Docker checks → Result model: creates findings
- Compose checks → Result model: creates findings
- Kubernetes checks → Result model: creates findings
- Port checks → Result model: creates findings
- Check runner → Result model: orders findings
- Output formatter → Result model: renders findings
- Output formatter → Terminal or JSON consumer: prints output