# chef/chef-server architecture

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

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

## Overview

- Omnibus – the build and packaging layer that ties everything together and produces deployable packages.
- Chef Expeditor – the internal CI/CD orchestration tool that, while not a runtime service, coordinates actions in the ecosystem.
- Client/Test Tools – oc-chef-pedant is the comprehensive API test suite, along with utility scripts.
– oc_erchef: The core REST API server that serves as the main entry-point for Chef Infra Server operations.
– oc_bifrost: The service responsible for authorization and access control logic.
– oc-id: The OAuth2-based identity provider, used by extensions (like Supermarket) to authenticate clients.
– Bookshelf: An S3-compatible storage engine for managing and storing cookbook data.
– chef-server-ctl: The command-line management utility for operational controls.
– Nginx (or OpenResty): Acting as the reverse proxy and load-balancer, with its Lua-based routing that dispatches requests to the backend services.

##### Interactions and data flows
– Requests destined for API handling should flow to oc_erchef.
– Authentication and token-related flows go to oc-id.
– Authorization decisions are routed to oc_bifrost.
– Operations requiring cookbook data are linked to Bookshelf.
- That data stores (PostgreSQL, Redis, Elasticsearch) are behind these services:
– For example, oc_erchef interacts with PostgreSQL (for application data), Redis (for caching/session management), and Elasticsearch (for search indexing).

##### Architectural patterns and technologies
- A micro‐services style architecture—even as these services may run as Habitat packages or within a runit-managed environment.
- Separate the build/CI layer (Omnibus and Chef Expeditor) from the runtime layer.
- That the project is written primarily in Erlang (for oc_erchef, oc_bifrost, Bookshelf, etc.), with additional components in Ruby (chef-server-ctl, oc-chef-pedant, omnibus) and Lua for routing in Nginx.
- Internal service supervision (via runit and Habitat) although it may be abstracted as “Service Supervision.”

##### Final touches
- How the build pipeline (Omnibus and related scripts in the repo) packages the Chef Infra Server with its integrated components.
- Annotations for key technologies such as Erlang, PostgreSQL, Redis, Elasticsearch, and the use of Habitat for package deployment.
- Do not over-complicate: aim for clarity by breaking down the architecture into primary clusters/components with explicit connections.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    EC("External Clients"):::client

    %% Build/CI Layer
    subgraph "Build/CI Layer"
        OM("Omnibus"):::build
        CE("Chef Expeditor"):::build
    end

    %% Runtime Components
    subgraph "Runtime Components"
        PROXY("Nginx/OpenResty"):::proxy
        OE("oc_erchef – Core REST API"):::runtime
        OB("oc_bifrost – Authorization"):::runtime
        OID("oc-id – OAuth2 Identity Provider"):::runtime
        BS("Bookshelf – Cookbook Storage"):::runtime
        CSCTL("chef-server-ctl – Management CLI"):::runtime
        OCT("oc-chef-pedant – API Test Suite"):::client
        SS("Service Supervision"):::runtime
    end

    %% Data Stores
    subgraph "Data Stores"
        PG("PostgreSQL"):::persistence
        RD("Redis"):::persistence
        ES("Elasticsearch"):::persistence
    end
    
    %% Connections - Ingress & Flows
    EC -->|"web/CLI_requests"| PROXY
    PROXY -->|"API_calls"| OE
    PROXY -->|"authentication"| OID
    PROXY -->|"authorization"| OB
    PROXY -->|"cookbook_management"| BS

    %% Internal service interactions
    OE -->|"data_operations"| PG
    OE -->|"cache_session"| RD
    OE -->|"search_indexing"| ES
    OE -->|"authorization_check"| OB
    OE -->|"token_validation"| OID

    %% Client/Test Tools interaction
    OCT -->|"test_requests"| PROXY

    %% Management utility connection
    CSCTL -->|"management"| SS

    %% Click Events for Component Mapping
    click OM "https://github.com/chef/chef-server/tree/main/omnibus/"
    click CE "https://github.com/chef/chef-server/tree/main/.expeditor/"
    click OCT "https://github.com/chef/chef-server/tree/main/oc-chef-pedant/"
    click OE "https://github.com/chef/chef-server/tree/main/src/oc_erchef/"
    click OB "https://github.com/chef/chef-server/tree/main/src/oc_bifrost/"
    click OID "https://github.com/chef/chef-server/tree/main/src/oc-id/"
    click BS "https://github.com/chef/chef-server/tree/main/src/bookshelf/"
    click CSCTL "https://github.com/chef/chef-server/tree/main/src/chef-server-ctl/"
    click PROXY "https://github.com/chef/chef-server/tree/main/src/nginx/"

    %% Style Definitions
    classDef build fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef runtime fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef client fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef persistence fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef proxy fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
