# theforeman/foreman architecture

> Architecture diagram of the GitHub repository theforeman/foreman, 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/theforeman/foreman
- Repository: https://github.com/theforeman/foreman
- Video tour (about a minute): https://gitdiagram.com/theforeman/foreman/video

## Overview

Foreman is an infrastructure lifecycle management server: operators or automation clients discover and manage hosts, provision bare-metal and cloud systems, apply configuration, and monitor reported status. Its Rails web and REST/GraphQL interfaces expose host and infrastructure operations; host orchestration connects provisioning to compute, network, and configuration integrations. The README also documents bulk host management, auditing, LDAP/RBAC, image building, and plugins. The graph uses tree-supported paths for these capabilities; integration wiring beyond the sampled host actions is shown only where documented or represented by orchestration modules.

Main entry points: [`app/models/host.rb`](https://github.com/theforeman/foreman/blob/develop/app/models/host.rb) (Host Domain), [`app/controllers/hosts_controller.rb`](https://github.com/theforeman/foreman/blob/develop/app/controllers/hosts_controller.rb) (Host Operations), [`app/models/application_record.rb`](https://github.com/theforeman/foreman/blob/develop/app/models/application_record.rb) (Application Records), [`app/models/concerns/orchestration.rb`](https://github.com/theforeman/foreman/blob/develop/app/models/concerns/orchestration.rb) (Host Orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web["Web Controllers"]
  node_rest["REST API"]
  node_graphql["GraphQL API"]
  node_routes["Unattended Endpoints<br/>[routes.rb]"]
end

subgraph group_lifecycle["Host Lifecycle"]
  node_host_controller["Host Operations"]
  node_bulk_manager["Bulk Host Actions"]
  node_registration["Host Registration"]
  node_templates["Provisioning Templates"]
end

subgraph group_integration["Infrastructure Integrations"]
  node_orchestration["Host Orchestration<br/>[orchestration.rb]"]
  node_compute["Compute Providers"]
  node_proxy["Smart Proxies<br/>[feature.rb]"]
  node_configuration["Configuration Tools<br/>[config_report.rb]"]
end

subgraph group_management["Operations and Governance"]
  node_reports["Reports and Status"]
  node_auditing["Audit History"]
  node_auth["Authentication and RBAC"]
  node_plugins["Plugin Extensions<br/>[manager.rb]"]
end

subgraph group_core["Domain Core"]
  node_host["Host Domain<br/>[host.rb]"]
  node_hostgroup["Host Groups<br/>[hostgroup.rb]"]
  node_persistence[("Application Records")]
end

node_operator(("Operator"))
node_automation(("API Client"))
node_provider_service{{"Compute Infrastructure"}}
node_smart_proxy_service{{"Smart Proxy Service"}}
node_config_system{{"Configuration Systems"}}

node_operator -->|"uses"| node_web
node_automation -->|"requests"| node_rest
node_automation -->|"queries"| node_graphql
node_web -->|"dispatches"| node_host_controller
node_rest -->|"dispatches"| node_host_controller
node_graphql -->|"resolves"| node_host
node_host_controller -->|"manages"| node_host
node_host_controller -->|"invokes"| node_bulk_manager
node_bulk_manager -->|"updates"| node_host
node_host_controller -->|"assigns"| node_hostgroup
node_host -->|"persists through"| node_persistence
node_registration -->|"loads"| node_host
node_registration -->|"renders"| node_templates
node_routes -->|"routes requests"| node_registration
node_host -->|"includes"| node_orchestration
node_orchestration -->|"coordinates"| node_compute
node_compute -.->|"manages instances"| node_provider_service
node_orchestration -->|"coordinates"| node_proxy
node_proxy -.->|"integrates"| node_smart_proxy_service
node_configuration -.->|"integrates"| node_config_system
node_reports -->|"reads reports"| node_persistence
node_auditing -->|"records changes"| node_persistence
node_auth -->|"manages identities"| node_persistence
node_plugins -.->|"extends interface"| node_web
node_host -->|"receives reports"| node_configuration

click node_web "https://github.com/theforeman/foreman/tree/develop/app/controllers"
click node_rest "https://github.com/theforeman/foreman/tree/develop/app/controllers/api/v2"
click node_graphql "https://github.com/theforeman/foreman/tree/develop/app/graphql"
click node_routes "https://github.com/theforeman/foreman/blob/develop/config/routes.rb"
click node_host_controller "https://github.com/theforeman/foreman/blob/develop/app/controllers/hosts_controller.rb"
click node_bulk_manager "https://github.com/theforeman/foreman/blob/develop/app/services/bulk_hosts_manager.rb"
click node_registration "https://github.com/theforeman/foreman/blob/develop/app/controllers/foreman_register/hosts_controller.rb"
click node_templates "https://github.com/theforeman/foreman/blob/develop/app/controllers/provisioning_templates_controller.rb"
click node_host "https://github.com/theforeman/foreman/blob/develop/app/models/host.rb"
click node_hostgroup "https://github.com/theforeman/foreman/blob/develop/app/models/hostgroup.rb"
click node_persistence "https://github.com/theforeman/foreman/blob/develop/app/models/application_record.rb"
click node_orchestration "https://github.com/theforeman/foreman/blob/develop/app/models/concerns/orchestration.rb"
click node_compute "https://github.com/theforeman/foreman/tree/develop/app/models/compute_resources"
click node_proxy "https://github.com/theforeman/foreman/blob/develop/app/models/feature.rb"
click node_configuration "https://github.com/theforeman/foreman/blob/develop/app/models/config_report.rb"
click node_reports "https://github.com/theforeman/foreman/blob/develop/app/controllers/config_reports_controller.rb"
click node_auditing "https://github.com/theforeman/foreman/blob/develop/app/controllers/audits_controller.rb"
click node_auth "https://github.com/theforeman/foreman/blob/develop/app/controllers/auth_sources_controller.rb"
click node_plugins "https://github.com/theforeman/foreman/blob/develop/app/registries/menu/manager.rb"

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_web,node_rest,node_graphql,node_routes,node_automation toneBlue
class node_host_controller,node_bulk_manager,node_registration,node_templates toneAmber
class node_orchestration,node_compute,node_proxy,node_configuration toneMint
class node_reports,node_auditing,node_auth,node_plugins toneRose
class node_host,node_hostgroup,node_persistence,node_operator,node_provider_service,node_smart_proxy_service,node_config_system toneIndigo
```

## Components

### User Interfaces

- [Web Controllers](https://github.com/theforeman/foreman/tree/develop/app/controllers): `app/controllers`
- [REST API](https://github.com/theforeman/foreman/tree/develop/app/controllers/api/v2): `app/controllers/api/v2`
- [GraphQL API](https://github.com/theforeman/foreman/tree/develop/app/graphql): `app/graphql`
- [Unattended Endpoints](https://github.com/theforeman/foreman/blob/develop/config/routes.rb): `config/routes.rb`

### Host Lifecycle

- [Host Operations](https://github.com/theforeman/foreman/blob/develop/app/controllers/hosts_controller.rb): `app/controllers/hosts_controller.rb`
- [Bulk Host Actions](https://github.com/theforeman/foreman/blob/develop/app/services/bulk_hosts_manager.rb): `app/services/bulk_hosts_manager.rb`
- [Host Registration](https://github.com/theforeman/foreman/blob/develop/app/controllers/foreman_register/hosts_controller.rb): `app/controllers/foreman_register/hosts_controller.rb`
- [Provisioning Templates](https://github.com/theforeman/foreman/blob/develop/app/controllers/provisioning_templates_controller.rb): `app/controllers/provisioning_templates_controller.rb`

### Infrastructure Integrations

- [Host Orchestration](https://github.com/theforeman/foreman/blob/develop/app/models/concerns/orchestration.rb): `app/models/concerns/orchestration.rb`
- [Compute Providers](https://github.com/theforeman/foreman/tree/develop/app/models/compute_resources): `app/models/compute_resources`
- [Smart Proxies](https://github.com/theforeman/foreman/blob/develop/app/models/feature.rb): `app/models/feature.rb`
- [Configuration Tools](https://github.com/theforeman/foreman/blob/develop/app/models/config_report.rb): `app/models/config_report.rb`

### Operations and Governance

- [Reports and Status](https://github.com/theforeman/foreman/blob/develop/app/controllers/config_reports_controller.rb): `app/controllers/config_reports_controller.rb`
- [Audit History](https://github.com/theforeman/foreman/blob/develop/app/controllers/audits_controller.rb): `app/controllers/audits_controller.rb`
- [Authentication and RBAC](https://github.com/theforeman/foreman/blob/develop/app/controllers/auth_sources_controller.rb): `app/controllers/auth_sources_controller.rb`
- [Plugin Extensions](https://github.com/theforeman/foreman/blob/develop/app/registries/menu/manager.rb): `app/registries/menu/manager.rb`

### Domain Core

- [Host Domain](https://github.com/theforeman/foreman/blob/develop/app/models/host.rb): `app/models/host.rb`
- [Host Groups](https://github.com/theforeman/foreman/blob/develop/app/models/hostgroup.rb): `app/models/hostgroup.rb`
- [Application Records](https://github.com/theforeman/foreman/blob/develop/app/models/application_record.rb): `app/models/application_record.rb`

### Other components

- **Operator**
- **API Client**
- **Compute Infrastructure**
- **Smart Proxy Service**
- **Configuration Systems**

## Connections

- Operator → Web Controllers: uses
- API Client → REST API: requests
- API Client → GraphQL API: queries
- Web Controllers → Host Operations: dispatches
- REST API → Host Operations: dispatches
- GraphQL API → Host Domain: resolves
- Host Operations → Host Domain: manages
- Host Operations → Bulk Host Actions: invokes
- Bulk Host Actions → Host Domain: updates
- Host Operations → Host Groups: assigns
- Host Domain → Application Records: persists through
- Host Registration → Host Domain: loads
- Host Registration → Provisioning Templates: renders
- Unattended Endpoints → Host Registration: routes requests
- Host Domain → Host Orchestration: includes
- Host Orchestration → Compute Providers: coordinates
- Compute Providers → Compute Infrastructure: manages instances
- Host Orchestration → Smart Proxies: coordinates
- Smart Proxies → Smart Proxy Service: integrates
- Configuration Tools → Configuration Systems: integrates
- Reports and Status → Application Records: reads reports
- Audit History → Application Records: records changes
- Authentication and RBAC → Application Records: manages identities
- Plugin Extensions → Web Controllers: extends interface
- Host Domain → Configuration Tools: receives reports