# chesscom/ccc-configs architecture

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

- Interactive diagram: https://gitdiagram.com/chesscom/ccc-configs
- Repository: https://github.com/chesscom/ccc-configs

## Overview

This repository publishes transparent Docker build definitions and configuration for public CCC chess engines. Its main workflow builds selected engine images, probes a successful image for its UCI version, and can publish that version; generated wrappers provide a separate way to run images. The audit utility independently discovers events and retrieves game logs or PGNs. The sampled source supports those flows, but does not establish how engine configs or opening-book files are consumed.

Main entry points: [`scripts/build_engine.py`](https://github.com/chesscom/ccc-configs/blob/master/scripts/build_engine.py) (Build and update), [`scripts/audit.py`](https://github.com/chesscom/ccc-configs/blob/master/scripts/audit.py) (Audit utility), [`wrappers`](https://github.com/chesscom/ccc-configs/tree/master/wrappers) (Run wrappers), [`dockers`](https://github.com/chesscom/ccc-configs/tree/master/dockers) (Docker definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Engine Builds"]
  node_builder["Build and update<br/>[build_engine.py]"]
  node_definitions["Docker definitions"]
  node_engine_config["Engine configs"]
  node_secrets["Build secrets"]
  node_docker["Docker engine"]
  node_webhook["Version API"]
end

subgraph group_run["Engine Runtime"]
  node_image["Engine image"]
  node_wrappers["Run wrappers"]
  node_books["Opening books"]
end

subgraph group_audit["Event Auditing"]
  node_auditor["Audit utility<br/>[audit.py]"]
  node_ccc_socket["CCC WebSocket"]
  node_log_store["Game-log storage"]
  node_audit_files[("Downloaded logs and PGNs")]
end

node_maintainer(("Maintainer"))
node_operator(("Engine operator"))

node_maintainer -->|"selects engines"| node_builder
node_builder -->|"builds from"| node_definitions
node_builder -->|"reads secrets"| node_secrets
node_builder -->|"runs build"| node_docker
node_docker -->|"creates image"| node_image
node_builder -->|"runs image"| node_docker
node_docker -->|"probes UCI"| node_image
node_builder -.->|"posts version"| node_webhook
node_operator -->|"runs engine"| node_wrappers
node_wrappers -->|"launches image"| node_image
node_auditor -->|"requests events"| node_ccc_socket
node_ccc_socket -->|"returns event data"| node_auditor
node_auditor -->|"downloads logs"| node_log_store
node_log_store -->|"returns log data"| node_auditor
node_auditor -->|"saves logs and PGNs"| node_audit_files
node_auditor -->|"requests game PGNs"| node_ccc_socket

click node_builder "https://github.com/chesscom/ccc-configs/blob/master/scripts/build_engine.py"
click node_definitions "https://github.com/chesscom/ccc-configs/tree/master/dockers"
click node_engine_config "https://github.com/chesscom/ccc-configs/tree/master/configs"
click node_secrets "https://github.com/chesscom/ccc-configs/tree/master/secrets"
click node_wrappers "https://github.com/chesscom/ccc-configs/tree/master/wrappers"
click node_books "https://github.com/chesscom/ccc-configs/tree/master/books"
click node_auditor "https://github.com/chesscom/ccc-configs/blob/master/scripts/audit.py"

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_builder,node_definitions,node_engine_config,node_secrets,node_docker,node_webhook toneBlue
class node_image,node_wrappers,node_books toneAmber
class node_auditor,node_ccc_socket,node_log_store,node_audit_files toneMint
class node_maintainer,node_operator toneIndigo
```

## Components

### Engine Builds

- [Build and update](https://github.com/chesscom/ccc-configs/blob/master/scripts/build_engine.py): `scripts/build_engine.py`
- [Docker definitions](https://github.com/chesscom/ccc-configs/tree/master/dockers): `dockers`
- [Engine configs](https://github.com/chesscom/ccc-configs/tree/master/configs): `configs`
- [Build secrets](https://github.com/chesscom/ccc-configs/tree/master/secrets): `secrets`
- **Docker engine**
- **Version API**

### Engine Runtime

- **Engine image**
- [Run wrappers](https://github.com/chesscom/ccc-configs/tree/master/wrappers): `wrappers`
- [Opening books](https://github.com/chesscom/ccc-configs/tree/master/books): `books`

### Event Auditing

- [Audit utility](https://github.com/chesscom/ccc-configs/blob/master/scripts/audit.py): `scripts/audit.py`
- **CCC WebSocket**
- **Game-log storage**
- **Downloaded logs and PGNs**

### Other components

- **Maintainer**
- **Engine operator**

## Connections

- Maintainer → Build and update: selects engines
- Build and update → Docker definitions: builds from
- Build and update → Build secrets: reads secrets
- Build and update → Docker engine: runs build
- Docker engine → Engine image: creates image
- Build and update → Docker engine: runs image
- Docker engine → Engine image: probes UCI
- Build and update → Version API: posts version
- Engine operator → Run wrappers: runs engine
- Run wrappers → Engine image: launches image
- Audit utility → CCC WebSocket: requests events
- CCC WebSocket → Audit utility: returns event data
- Audit utility → Game-log storage: downloads logs
- Game-log storage → Audit utility: returns log data
- Audit utility → Downloaded logs and PGNs: saves logs and PGNs
- Audit utility → CCC WebSocket: requests game PGNs