# contentauth/json-manifest-reference architecture

> Architecture diagram of the GitHub repository contentauth/json-manifest-reference, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/contentauth/json-manifest-reference
- Repository: https://github.com/contentauth/json-manifest-reference

## Overview

##### Project type and purpose
- This is a static documentation site built with Jekyll and Liquid.
- It renders a JSON-schema–based reference (“json-manifest-reference”) for the CAI/C2PA manifest store.
- The site is hosted via GitHub Pages; schema files are generated from a Rust library (c2pa-rs) and then transformed into HTML.

##### File structure
Top-level directories and files:
- `_data/` – holds the canonical and annotated JSON Schema files (`ManifestStore_schema.json`, etc.).
- `_includes/` and `_layouts/` – Liquid partials and layout templates used by Jekyll to assemble HTML pages.
- `pages/` – Markdown content files that become the individual reference pages.
- `css/`, `js/`, `images/`, `fonts/` – static assets served alongside HTML.
- `.github/workflows/` – GitHub Actions YAML for triggering site updates.
- `copy-html.sh`, `copy-schemas.sh` – helper scripts for copying schemas or static HTML.
- `_config.yml` – Jekyll configuration.

##### Key insights from the README
- The JSON schemas in `_data/` are generated from the Rust SDK via `make schema` or `cargo run --bin export_schema`.
- Changing `_data/ManifestStore_schema_edited.json` triggers a GitHub Action to rebuild and redeploy the site.
- Jekyll + Liquid combines `.md` pages, templates, and schemas into static HTML, CSS, and JS.
- The final site is published to GitHub Pages.

##### Main components and their interactions (
a. Developer workstation
– Runs `make schema` in the c2pa-rs repo → outputs JSON schema → copied into this repo’s `_data/`.
– Commits changes to GitHub.
b. GitHub repository
– Stores source Markdown, JSON schemas, templates, assets, and workflow definitions.
c. GitHub Actions CI/CD
– On push to `main` (or on change to schema file), triggers the Jekyll build workflow (`move-into-oss.yml`).
– Executes helper scripts (e.g., `copy-schemas.sh`) if needed, then runs `jekyll build`.
d. Jekyll build engine
– Reads `_config.yml`, `.md` pages, `_includes/`, `_layouts/`, and `_data/*.json`.
– Renders Liquid templates into static HTML, injecting schema content and navigation.
– Bundles CSS, JS, fonts, images into the output `_site/`.
e. Deployment (GitHub Pages)
– The workflow pushes `_site/` to the `gh-pages` branch (or `main`), making the site live at `https://contentauth.github.io/json-manifest-reference/`.
f. End users (browsers)
– Fetch static HTML/CSS/JS from GitHub Pages.

##### Important architectural patterns and design principles
- Static site generation – no backend server at runtime; all pages are pre-built.
- Template-driven – Liquid templates decouple content (`pages/`) from layout and styling (`_layouts/`, `css/`).
- Data-driven – JSON Schema files in `_data/` are authoritative inputs.
- CI/CD automation – GitHub Actions ensure every schema change triggers a rebuild/deploy.

##### Relevant technologies and libraries
- Ruby/Jekyll – static site generator
- Liquid – templating language
- Markdown – content format
- JSON Schema – data model definitions
- GitHub Actions – CI/CD
- GitHub Pages – hosting
- Shell scripts (`.sh`) – auxiliary build steps
- CSS/JS – styling and client-side interactivity (sticky headers, table of contents)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    Dev["Developer Workstation"]:::dev
    %% GitHub Repository with subcomponents
    subgraph "GitHub Repository" 
        direction TB
        RepoData["_data/"]:::repo
        RepoIncludes["_includes/"]:::repo
        RepoLayouts["_layouts/"]:::repo
        RepoPages["pages/"]:::repo
        RepoConfig["_config.yml, Gemfile, Gemfile.lock"]:::repo
        RepoWorkflows[".github/workflows/"]:::repo
        RepoScripts["copy-schemas.sh, copy-html.sh"]:::repo
        RepoAssets["css/, js/, images/, fonts/"]:::repo
    end
    %% CI/CD
    CI["GitHub Actions CI/CD"]:::ci
    %% Jekyll Build Engine
    Build["Jekyll Build Engine"]:::build
    %% Deployment
    Pages["GitHub Pages"]:::host
    %% End Users
    Browser["End Users (Browser)"]:::host

    %% Data Flow
    Dev -->|"push commit"| RepoData
    Dev --> RepoIncludes
    Dev --> RepoLayouts
    Dev --> RepoPages
    Dev --> RepoConfig
    Dev --> RepoWorkflows
    Dev --> RepoScripts
    Dev --> RepoAssets

    RepoData -->|"on push trigger"| CI
    RepoIncludes --> CI
    RepoLayouts --> CI
    RepoPages --> CI
    RepoConfig --> CI
    RepoWorkflows --> CI
    RepoScripts --> CI
    RepoAssets --> CI

    CI -->|"run copy-schemas.sh, copy-html.sh\nrun jekyll build"| Build
    Build -->|"static HTML/CSS/JS\n(uses _data JSON schemas,\nlayouts, includes, pages, assets)"| Pages
    Pages -->|"HTTP GET"| Browser

    %% Click Events
    click RepoData "https://github.com/contentauth/json-manifest-reference/tree/main/_data/"
    click RepoIncludes "https://github.com/contentauth/json-manifest-reference/tree/main/_includes/"
    click RepoLayouts "https://github.com/contentauth/json-manifest-reference/tree/main/_layouts/"
    click RepoPages "https://github.com/contentauth/json-manifest-reference/tree/main/pages/"
    click RepoConfig "https://github.com/contentauth/json-manifest-reference/blob/main/_config.yml"
    click RepoConfig "https://github.com/contentauth/json-manifest-reference/tree/main/Gemfile"
    click RepoConfig "https://github.com/contentauth/json-manifest-reference/blob/main/Gemfile.lock"
    click RepoWorkflows "https://github.com/contentauth/json-manifest-reference/blob/main/.github/workflows/move-into-oss.yml"
    click RepoScripts "https://github.com/contentauth/json-manifest-reference/blob/main/copy-schemas.sh"
    click RepoScripts "https://github.com/contentauth/json-manifest-reference/blob/main/copy-html.sh"

    %% Styles
    classDef dev fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef repo fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ci fill:#d4edda,stroke:#333,stroke-width:1px
    classDef build fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef host fill:#e2d6f3,stroke:#333,stroke-width:1px
```
