# ceos-org/interoperability-handbook architecture

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

- Interactive diagram: https://gitdiagram.com/ceos-org/interoperability-handbook
- Repository: https://github.com/ceos-org/interoperability-handbook

## Overview

##### What this project is (type + purpose)
This repository is **not an application runtime**; it’s a **documentation product** (a handbook) with:
- **Source content** in Markdown chapters (`Introduction.md`, `Architecture.md`, etc.)
- **Publishing automation** that generates a **release PDF** (see `publishing/generate_pdf.py` and `.github/workflows/pdf-on-release.yml`)
- **Quality gates** for formatting/spelling/content checks (see `.markdownlint.json`, `.spellcheck.yml`, `.github/workflows/check-contents.yaml`)

##### How to read the file tree as architecture signals
From the tree:

##### Content layer (the “product”)
- `README.md` (entry point + TOC + release link)
- Chapter files: `Introduction.md`, `Framework.md`, `Vocabulary.md`, `Architecture.md`, `Interface.md`, `Quality.md`, `Policy.md`, `Conclusion.md`
- `images/` (embedded assets like the CEOS logo)
- `LICENSE` (CC-BY 4.0)

##### Publishing layer (build system)
- `publishing/generate_pdf.py` (the build pipeline implementation; likely concatenation, markdown-to-pdf conversion, styling, etc.)
- `publishing/readme.md` (build instructions/notes for publishing subsystem)

##### Governance / automation / CI
- `.github/workflows/check-contents.yaml` (continuous checks: lint/spell/structure)
- `.github/workflows/pdf-on-release.yml` (release-time workflow: build PDF + attach to GitHub Release)
- `.markdownlint.json` (markdown style rules)
- `.spellcheck.yml` + `.wordlist.txt` (spellchecking config + allowlist)

##### Distribution (GitHub Releases → PDF download)

This layout mirrors the real lifecycle described in the README (release PDF link) and the presence of CI/CD workflow files.

##### Concrete components and labels to use (use the actual file names)

- `Introduction.md`
- `Framework.md`
- `Vocabulary.md`
- `Architecture.md`
- `Interface.md`
- `Quality.md`
- `Policy.md`
- `Conclusion.md`
- `images/`

- `.github/workflows/check-contents.yaml`
- `.markdownlint.json`
- `.spellcheck.yml`
- `wordlist.txt`

- `.github/workflows/pdf-on-release.yml`
- `publishing/generate_pdf.py`
- Output: `interoperability-handbook.pdf`

- GitHub Releases (e.g., `v2.0.0`)
- Link from `README.md` to release asset

##### Clear labels
- Name each workflow by filename and trigger (e.g., “check-contents.yaml (on push/PR)” and “pdf-on-release.yml (on release/tag)”).

- **Control/event**: “push/PR”, “release/tag”
- **Data/artifact**: “PDF”, “lint results”, “spellcheck report”

##### Boundaries
- A big boundary for **GitHub** (Repo + Actions + Releases)
- Optional boundary for **Local dev** (contributors editing files before pushing)

##### Don’t overthink it: “separate into as many components as possible”
For this repository, “more components” mainly means:
- Split **content** into “chapters” vs “assets”
- Split **automation** into “checks” vs “release build”

All three can be derived directly from the file tree and README, and together they form the “best and most accurate” architectural representation for a docs/publishing project.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Actors (Local/External)
  %% =========================
  subgraph "Actors"
    direction TB
    Contributor["Contributors / Editors"]:::actor
    Reviewer["Reviewers / Maintainers"]:::actor
    Reader["Readers / Stakeholders"]:::actor
  end

  %% =========================
  %% GitHub Boundary
  %% =========================
  subgraph "GitHub (Source + Automation + Distribution)"
    direction TB

    %% -------------------------
    %% Repository (Docs-as-code)
    %% -------------------------
    subgraph "Repository (Docs-as-Code)"
      direction TB

      Readme["README.md (Entry point + TOC + Release link)"]:::content

      subgraph "Handbook Content (Markdown Chapters)"
        direction TB
        Intro["Introduction.md"]:::content
        Framework["Framework.md"]:::content
        Vocab["Vocabulary.md"]:::content
        Arch["Architecture.md"]:::content
        Interface["Interface.md"]:::content
        Quality["Quality.md"]:::content
        Policy["Policy.md"]:::content
        Conclusion["Conclusion.md"]:::content
      end

      Images["images/ (Embedded assets)"]:::content

      subgraph "Governance / Quality Configuration"
        direction TB
        Markdownlint[".markdownlint.json"]:::config
        SpellCfg[".spellcheck.yml"]:::config
        Wordlist[".wordlist.txt"]:::config
        License["LICENSE (CC-BY 4.0)"]:::config
      end

      subgraph "Publishing Subsystem (Build Implementation + Notes)"
        direction TB
        PubReadme["publishing/readme.md"]:::publishing
        PdfGen["publishing/generate_pdf.py"]:::publishing
      end
    end

    %% -------------------------
    %% GitHub Actions (CI/CD)
    %% -------------------------
    subgraph "GitHub Actions (Automation)"
      direction TB

      subgraph "CI Quality Gates"
        direction TB
        ChecksWF["check-contents.yaml (on push/PR)"]:::ci
        LintJob["Markdown lint job"]:::ci
        SpellJob["Spellcheck job"]:::ci
        StructureJob["Structure/content checks job"]:::ci
        ChecksResult["Checks result (pass/fail)"]:::artifact
      end

      subgraph "Release Publishing"
        direction TB
        ReleaseWF["pdf-on-release.yml (on release/tag)"]:::cd
        BuildStep["Run PDF build (call generate_pdf.py)"]:::cd
        PdfArtifact["interoperability-handbook.pdf"]:::artifact
        UploadAsset["Upload PDF as release asset"]:::cd
      end
    end

    %% -------------------------
    %% Distribution
    %% -------------------------
    subgraph "Distribution"
      direction TB
      Releases["GitHub Releases (tagged versions)"]:::distribution
    end
  end

  %% =========================
  %% Flows (vertical emphasis)
  %% =========================
  Contributor -->|"edit_files"| Readme
  Contributor -->|"edit_files"| Intro
  Contributor -->|"edit_files"| Framework
  Contributor -->|"edit_files"| Vocab
  Contributor -->|"edit_files"| Arch
  Contributor -->|"edit_files"| Interface
  Contributor -->|"edit_files"| Quality
  Contributor -->|"edit_files"| Policy
  Contributor -->|"edit_files"| Conclusion
  Contributor -->|"add_assets"| Images
  Contributor -->|"update_rules"| Markdownlint
  Contributor -->|"update_rules"| SpellCfg
  Contributor -->|"maintain_allowlist"| Wordlist
  Contributor -->|"maintain_publishing"| PdfGen
  Contributor -->|"maintain_publishing"| PubReadme
  Reviewer -->|"review_merge"| Readme

  %% CI triggers + checks
  Readme -->|"push/PR_triggers"| ChecksWF
  Intro -->|"push/PR_triggers"| ChecksWF
  Framework -->|"push/PR_triggers"| ChecksWF
  Vocab -->|"push/PR_triggers"| ChecksWF
  Arch -->|"push/PR_triggers"| ChecksWF
  Interface -->|"push/PR_triggers"| ChecksWF
  Quality -->|"push/PR_triggers"| ChecksWF
  Policy -->|"push/PR_triggers"| ChecksWF
  Conclusion -->|"push/PR_triggers"| ChecksWF
  Images -->|"push/PR_triggers"| ChecksWF

  ChecksWF -->|"runs"| LintJob
  ChecksWF -->|"runs"| SpellJob
  ChecksWF -->|"runs"| StructureJob

  Markdownlint -->|"configures"| LintJob
  SpellCfg -->|"configures"| SpellJob
  Wordlist -->|"allowlist"| SpellJob

  LintJob -->|"reports"| ChecksResult
  SpellJob -->|"reports"| ChecksResult
  StructureJob -->|"reports"| ChecksResult

  %% Release build trigger + artifact flow
  Releases -->|"release/tag_triggers"| ReleaseWF
  ReleaseWF -->|"executes"| BuildStep
  BuildStep -->|"calls"| PdfGen

  Intro -->|"input_md"| PdfGen
  Framework -->|"input_md"| PdfGen
  Vocab -->|"input_md"| PdfGen
  Arch -->|"input_md"| PdfGen
  Interface -->|"input_md"| PdfGen
  Quality -->|"input_md"| PdfGen
  Policy -->|"input_md"| PdfGen
  Conclusion -->|"input_md"| PdfGen
  Images -->|"input_assets"| PdfGen

  PdfGen -->|"produces"| PdfArtifact
  ReleaseWF -->|"publishes"| UploadAsset
  UploadAsset -->|"attaches_asset"| Releases
  PdfArtifact -->|"is_asset_of"| Releases

  %% Reader consumption + README linkage
  Readme -->|"links_to"| Releases
  Reader -->|"download_pdf"| Releases

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click Intro "https://github.com/ceos-org/interoperability-handbook/blob/main//Introduction.md"
  click Framework "https://github.com/ceos-org/interoperability-handbook/blob/main//Framework.md"
  click Vocab "https://github.com/ceos-org/interoperability-handbook/blob/main//Vocabulary.md"
  click Arch "https://github.com/ceos-org/interoperability-handbook/blob/main//Architecture.md"
  click Interface "https://github.com/ceos-org/interoperability-handbook/blob/main//Interface.md"
  click Quality "https://github.com/ceos-org/interoperability-handbook/blob/main//Quality.md"
  click Policy "https://github.com/ceos-org/interoperability-handbook/blob/main//Policy.md"
  click Conclusion "https://github.com/ceos-org/interoperability-handbook/blob/main//Conclusion.md"
  click Readme "https://github.com/ceos-org/interoperability-handbook/blob/main//README.md"
  click Images "https://github.com/ceos-org/interoperability-handbook/tree/main//images/"
  click PdfGen "https://github.com/ceos-org/interoperability-handbook/blob/main//publishing/generate_pdf.py"
  click PubReadme "https://github.com/ceos-org/interoperability-handbook/blob/main//publishing/readme.md"
  click ChecksWF "https://github.com/ceos-org/interoperability-handbook/blob/main//.github/workflows/check-contents.yaml"
  click ReleaseWF "https://github.com/ceos-org/interoperability-handbook/blob/main//.github/workflows/pdf-on-release.yml"
  click Markdownlint "https://github.com/ceos-org/interoperability-handbook/blob/main//.markdownlint.json"
  click SpellCfg "https://github.com/ceos-org/interoperability-handbook/blob/main//.spellcheck.yml"
  click Wordlist "https://github.com/ceos-org/interoperability-handbook/blob/main//.wordlist.txt"
  click License "https://github.com/ceos-org/interoperability-handbook/tree/main//LICENSE"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#0b172a,stroke:#5aa9ff,stroke-width:2px,color:#eaf2ff
  classDef content fill:#0b2a3b,stroke:#35b6ff,stroke-width:1.5px,color:#e9f7ff
  classDef config fill:#2b2b2b,stroke:#9aa0a6,stroke-width:1.5px,color:#f3f4f6
  classDef ci fill:#22124d,stroke:#b18cff,stroke-width:1.5px,color:#f3ecff
  classDef cd fill:#2a0f45,stroke:#ff7bd1,stroke-width:1.5px,color:#ffeefe
  classDef publishing fill:#2a1a00,stroke:#ffb020,stroke-width:1.5px,color:#fff4dd
  classDef artifact fill:#0f3d2e,stroke:#4ade80,stroke-width:1.5px,color:#eafff2
  classDef distribution fill:#0f3d1f,stroke:#22c55e,stroke-width:2px,color:#eafff2
```
