# c2pa-org/specifications architecture

> Architecture diagram of the GitHub repository c2pa-org/specifications, 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/c2pa-org/specifications
- Repository: https://github.com/c2pa-org/specifications

## Overview

##### Project type and purpose
- This is a documentation‐site project that uses Asciidoc sources and Antora to generate and publish the C2PA Specifications website. It is not a full‐stack application or service‐oriented microservice architecture, but a static‐site generator pipeline with CI/CD targeting a public spec site (https://c2pa.org/specifications).

##### File structure
- Top‐level files:
- antora-playbook.yml / antora-playbook-local.yml – Antora configuration that describes how to assemble the site from modules.
- docs/ – Asciidoc modules (ROOT) containing pages, nav.adoc, antora.yml for component metadata.
- buildsite.sh, buildsite-local.sh, makeAntoraPresentation.sh – helper scripts to invoke Antora and local previews.
- .github/workflows/publish.yml – CI workflow that runs on push to build and publish the static site.
- build/site/ – the generated HTML/CSS/JS output.
- package.json – Node.js dependency definitions (e.g. Antora, asciidoctor extensions).
- runLinkChecker.sh, runalex.sh – quality‐check scripts for links and spelling.

##### README for additional insights
- The README simply states that this repo holds the raw form of the C2PA specs and points to the published site. It confirms the purpose is documentation publication.

##### Detail without over‐splitting
- Logical step: source management, build orchestration, quality gating, and deployment.
- Avoid extraneous layers like network topology; focus on the documentation pipeline.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer and Source
    Developer["Developer"]:::actor
    GitRepo["Git Repository\n(Asciidoc Sources)"]:::source
    ModuleMeta["Module Metadata\n(antora.yml)"]:::source
    ModuleNav["Module Navigation\n(nav.adoc)"]:::source

    %% Local Preview Context
    subgraph "Local Preview" 
        direction TB
        LocalPlaybook["Antora Playbook\nLocal Preview"]:::build
        LocalBuild["Build Script\nbuildsite-local.sh"]:::build
        Presentation["Presentation Script\nmakeAntoraPresentation.sh"]:::build
    end

    %% Production Build
    subgraph "CI/CD Pipeline" 
        direction TB
        Workflow["GitHub Actions Workflow\npublish.yml"]:::ci
        ProdPlaybook["Antora Playbook\nProduction"]:::build
        BuildScript["Build Script\nbuildsite.sh"]:::build
        Package["Node.js Dependencies\npackage.json"]:::build
        LinkChecker["Link Checker\nrunLinkChecker.sh"]:::quality
        SpellChecker["Spelling Checker\nrunalex.sh"]:::quality
        Artifacts["Generated Site\n(build/site)"]:::artifact
    end

    %% Hosting and End Users
    Hosting["Static Hosting\n(GitHub Pages/S3)"]:::infra
    EndUser["End User\n(Web Browser)"]:::actor

    %% Flows
    Developer -->|commits code| GitRepo
    GitRepo --> ModuleMeta
    GitRepo --> ModuleNav

    Developer -->|runs preview| LocalBuild
    LocalBuild --> LocalPlaybook
    LocalPlaybook --> Presentation

    GitRepo -->|push triggers| Workflow
    Workflow --> Package
    Workflow --> ProdPlaybook
    ProdPlaybook --> BuildScript
    BuildScript --> Artifacts
    Artifacts --> LinkChecker
    Artifacts --> SpellChecker
    LinkChecker -->|if pass| Artifacts
    SpellChecker -->|if pass| Artifacts
    Artifacts -->|deploy| Hosting
    Hosting --> EndUser

    %% Click Events
    click GitRepo "https://github.com/c2pa-org/specifications/blob/main/docs/modules/ROOT/pages/index.adoc"
    click ModuleMeta "https://github.com/c2pa-org/specifications/blob/main/docs/antora.yml"
    click ModuleNav "https://github.com/c2pa-org/specifications/blob/main/docs/modules/nav.adoc"
    click LocalPlaybook "https://github.com/c2pa-org/specifications/blob/main/antora-playbook-local.yml"
    click ProdPlaybook "https://github.com/c2pa-org/specifications/blob/main/antora-playbook.yml"
    click BuildScript "https://github.com/c2pa-org/specifications/blob/main/buildsite.sh"
    click LocalBuild "https://github.com/c2pa-org/specifications/blob/main/buildsite-local.sh"
    click Presentation "https://github.com/c2pa-org/specifications/blob/main/makeAntoraPresentation.sh"
    click Package "https://github.com/c2pa-org/specifications/blob/main/package.json"
    click Workflow "https://github.com/c2pa-org/specifications/blob/main/.github/workflows/publish.yml"
    click Artifacts "https://github.com/c2pa-org/specifications/tree/main/build/site/"
    click LinkChecker "https://github.com/c2pa-org/specifications/blob/main/runLinkChecker.sh"
    click SpellChecker "https://github.com/c2pa-org/specifications/blob/main/runalex.sh"

    %% Styles
    classDef actor fill:#D5E8D4,stroke:#82B366
    classDef source fill:#FFF2CC,stroke:#D6B656
    classDef build fill:#DAE8FC,stroke:#6C8EBF
    classDef ci fill:#F8CECC,stroke:#B85450
    classDef quality fill:#E1D5E7,stroke:#9673A6
    classDef artifact fill:#F5DEB3,stroke:#C49C31
    classDef infra fill:#E2E7F0,stroke:#5A6C8F
```
