# chef/cheffish architecture

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

- Interactive diagram: https://gitdiagram.com/chef/cheffish
- Repository: https://github.com/chef/cheffish

## Overview

Cheffish is a Ruby library for convergent Chef Server resources, with an additional recipe-based RSpec testing framework. The principal workflow is a recipe author declaring server changes, then Chef resources reconciling those changes against the server. The graph also shows the shared resource machinery and the separate RSpec execution path. Some resource implementations were not sampled; their capabilities are included from the README, but uncertain implementation links are omitted.

Main entry points: [`lib/cheffish.rb`](https://github.com/chef/cheffish/blob/main/lib/cheffish.rb) (Cheffish entry), [`lib/cheffish/recipe_dsl.rb`](https://github.com/chef/cheffish/blob/main/lib/cheffish/recipe_dsl.rb) (Recipe DSL), [`lib/cheffish/chef_actor_base.rb`](https://github.com/chef/cheffish/blob/main/lib/cheffish/chef_actor_base.rb) (Actors and keys), [`lib/chef/resource/chef_acl.rb`](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_acl.rb) (ACL management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_resources["Server resources"]
  node_acl["ACL management<br/>[chef_acl.rb]"]
  node_identity["Actors and keys<br/>[chef_actor_base.rb]"]
  node_data["Data bags"]
  node_environment["Environments"]
  node_mirror["Server mirroring<br/>[chef_mirror.rb]"]
  node_organization["Organizations"]
  node_role["Roles<br/>[chef_role.rb]"]
  node_otherresources["Other resources"]
  node_publickey["Public keys<br/>[public_key.rb]"]
end

subgraph group_runtime["Convergence runtime"]
  node_base["Resource base<br/>[base_resource.rb]"]
  node_properties["Shared properties<br/>[base_properties.rb]"]
  node_client["Basic Chef client"]
  node_run["Chef run<br/>[chef_run.rb]"]
  node_serverapi["Server API helpers<br/>[server_api.rb]"]
  node_entry["Cheffish entry<br/>[cheffish.rb]"]
end

subgraph group_recipe["Recipe integration"]
  node_dsl["Recipe DSL<br/>[recipe_dsl.rb]"]
  node_nodeprops["Node properties<br/>[node_properties.rb]"]
end

subgraph group_rspec["RSpec support"]
  node_rspecsupport["RSpec run support"]
  node_wrapper["Recipe run wrapper"]
  node_matchers["Run matchers"]
end

node_author(("Recipe author"))
node_server[("Chef Server")]

node_author -->|"writes recipe"| node_dsl
node_author -->|"declares changes"| node_acl
node_author -->|"declares changes"| node_identity
node_author -->|"declares changes"| node_data
node_author -->|"declares changes"| node_environment
node_author -->|"declares changes"| node_mirror
node_author -->|"declares changes"| node_organization
node_author -->|"declares changes"| node_role
node_author -->|"declares changes"| node_otherresources
node_author -->|"declares changes"| node_publickey
node_acl -->|"reads and writes"| node_server
node_identity -->|"reads and writes"| node_server
node_data -->|"reads and writes"| node_server
node_mirror -->|"copies files"| node_server
node_environment -.->|"reconciles"| node_server
node_organization -.->|"reconciles"| node_server
node_role -.->|"reconciles"| node_server
node_otherresources -.->|"reconciles"| node_server
node_base -->|"uses"| node_properties
node_identity -->|"inherits"| node_base
node_entry -->|"loads"| node_client
node_entry -->|"loads"| node_serverapi
node_entry -->|"loads"| node_dsl
node_entry -->|"loads"| node_nodeprops
node_dsl -->|"registers"| node_acl
node_dsl -->|"registers"| node_otherresources
node_rspecsupport -->|"uses"| node_wrapper
node_wrapper -->|"extends"| node_run
node_run -->|"uses"| node_client
node_rspecsupport -->|"loads"| node_matchers

click node_acl "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_acl.rb"
click node_identity "https://github.com/chef/cheffish/blob/main/lib/cheffish/chef_actor_base.rb"
click node_data "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_data_bag_item.rb"
click node_environment "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_environment.rb"
click node_mirror "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_mirror.rb"
click node_organization "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_organization.rb"
click node_role "https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_role.rb"
click node_otherresources "https://github.com/chef/cheffish/tree/main/lib/chef/resource"
click node_publickey "https://github.com/chef/cheffish/blob/main/lib/chef/resource/public_key.rb"
click node_base "https://github.com/chef/cheffish/blob/main/lib/cheffish/base_resource.rb"
click node_properties "https://github.com/chef/cheffish/blob/main/lib/cheffish/base_properties.rb"
click node_client "https://github.com/chef/cheffish/blob/main/lib/cheffish/basic_chef_client.rb"
click node_run "https://github.com/chef/cheffish/blob/main/lib/cheffish/chef_run.rb"
click node_serverapi "https://github.com/chef/cheffish/blob/main/lib/cheffish/server_api.rb"
click node_entry "https://github.com/chef/cheffish/blob/main/lib/cheffish.rb"
click node_dsl "https://github.com/chef/cheffish/blob/main/lib/cheffish/recipe_dsl.rb"
click node_nodeprops "https://github.com/chef/cheffish/blob/main/lib/cheffish/node_properties.rb"
click node_rspecsupport "https://github.com/chef/cheffish/blob/main/lib/cheffish/rspec/chef_run_support.rb"
click node_wrapper "https://github.com/chef/cheffish/blob/main/lib/cheffish/rspec/recipe_run_wrapper.rb"
click node_matchers "https://github.com/chef/cheffish/tree/main/lib/cheffish/rspec/matchers"

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_acl,node_identity,node_data,node_environment,node_mirror,node_organization,node_role,node_otherresources,node_publickey toneBlue
class node_base,node_properties,node_client,node_run,node_serverapi,node_entry,node_server toneAmber
class node_dsl,node_nodeprops toneMint
class node_rspecsupport,node_wrapper,node_matchers toneRose
class node_author toneIndigo
```

## Components

### Server resources

- [ACL management](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_acl.rb): `lib/chef/resource/chef_acl.rb`
- [Actors and keys](https://github.com/chef/cheffish/blob/main/lib/cheffish/chef_actor_base.rb): `lib/cheffish/chef_actor_base.rb`
- [Data bags](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_data_bag_item.rb): `lib/chef/resource/chef_data_bag_item.rb`
- [Environments](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_environment.rb): `lib/chef/resource/chef_environment.rb`
- [Server mirroring](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_mirror.rb): `lib/chef/resource/chef_mirror.rb`
- [Organizations](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_organization.rb): `lib/chef/resource/chef_organization.rb`
- [Roles](https://github.com/chef/cheffish/blob/main/lib/chef/resource/chef_role.rb): `lib/chef/resource/chef_role.rb`
- [Other resources](https://github.com/chef/cheffish/tree/main/lib/chef/resource): `lib/chef/resource`
- [Public keys](https://github.com/chef/cheffish/blob/main/lib/chef/resource/public_key.rb): `lib/chef/resource/public_key.rb`

### Convergence runtime

- [Resource base](https://github.com/chef/cheffish/blob/main/lib/cheffish/base_resource.rb): `lib/cheffish/base_resource.rb`
- [Shared properties](https://github.com/chef/cheffish/blob/main/lib/cheffish/base_properties.rb): `lib/cheffish/base_properties.rb`
- [Basic Chef client](https://github.com/chef/cheffish/blob/main/lib/cheffish/basic_chef_client.rb): `lib/cheffish/basic_chef_client.rb`
- [Chef run](https://github.com/chef/cheffish/blob/main/lib/cheffish/chef_run.rb): `lib/cheffish/chef_run.rb`
- [Server API helpers](https://github.com/chef/cheffish/blob/main/lib/cheffish/server_api.rb): `lib/cheffish/server_api.rb`
- [Cheffish entry](https://github.com/chef/cheffish/blob/main/lib/cheffish.rb): `lib/cheffish.rb`

### Recipe integration

- [Recipe DSL](https://github.com/chef/cheffish/blob/main/lib/cheffish/recipe_dsl.rb): `lib/cheffish/recipe_dsl.rb`
- [Node properties](https://github.com/chef/cheffish/blob/main/lib/cheffish/node_properties.rb): `lib/cheffish/node_properties.rb`

### RSpec support

- [RSpec run support](https://github.com/chef/cheffish/blob/main/lib/cheffish/rspec/chef_run_support.rb): `lib/cheffish/rspec/chef_run_support.rb`
- [Recipe run wrapper](https://github.com/chef/cheffish/blob/main/lib/cheffish/rspec/recipe_run_wrapper.rb): `lib/cheffish/rspec/recipe_run_wrapper.rb`
- [Run matchers](https://github.com/chef/cheffish/tree/main/lib/cheffish/rspec/matchers): `lib/cheffish/rspec/matchers`

### Other components

- **Recipe author**
- **Chef Server**

## Connections

- Recipe author → Recipe DSL: writes recipe
- Recipe author → ACL management: declares changes
- Recipe author → Actors and keys: declares changes
- Recipe author → Data bags: declares changes
- Recipe author → Environments: declares changes
- Recipe author → Server mirroring: declares changes
- Recipe author → Organizations: declares changes
- Recipe author → Roles: declares changes
- Recipe author → Other resources: declares changes
- Recipe author → Public keys: declares changes
- ACL management → Chef Server: reads and writes (evidence: `lib/chef/resource/chef_acl.rb`)
- Actors and keys → Chef Server: reads and writes (evidence: `lib/cheffish/chef_actor_base.rb`)
- Data bags → Chef Server: reads and writes (evidence: `lib/chef/resource/chef_data_bag_item.rb`)
- Server mirroring → Chef Server: copies files (evidence: `lib/chef/resource/chef_mirror.rb`)
- Environments → Chef Server: reconciles
- Organizations → Chef Server: reconciles
- Roles → Chef Server: reconciles
- Other resources → Chef Server: reconciles
- Resource base → Shared properties: uses (evidence: `lib/cheffish/base_resource.rb`)
- Actors and keys → Resource base: inherits (evidence: `lib/cheffish/chef_actor_base.rb`)
- Cheffish entry → Basic Chef client: loads (evidence: `lib/cheffish.rb`)
- Cheffish entry → Server API helpers: loads (evidence: `lib/cheffish.rb`)
- Cheffish entry → Recipe DSL: loads (evidence: `lib/cheffish.rb`)
- Cheffish entry → Node properties: loads (evidence: `lib/cheffish.rb`)
- Recipe DSL → ACL management: registers (evidence: `lib/cheffish/recipe_dsl.rb`)
- Recipe DSL → Other resources: registers (evidence: `lib/cheffish/recipe_dsl.rb`)
- RSpec run support → Recipe run wrapper: uses (evidence: `lib/cheffish/rspec/chef_run_support.rb`)
- Recipe run wrapper → Chef run: extends (evidence: `lib/cheffish/rspec/recipe_run_wrapper.rb`)
- Chef run → Basic Chef client: uses (evidence: `lib/cheffish/chef_run.rb`)
- RSpec run support → Run matchers: loads (evidence: `lib/cheffish/rspec/chef_run_support.rb`)