# c2pa-org/c2pa-docs-ui architecture

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

## Overview

##### Project type and purpose
- This is a front‐end UI project: a “theme” and interaction layer for an Antora/AsciiDoctor‐based documentation site.
- The project bundles Handlebars templates (layouts, partials, helpers), CSS, JavaScript, fonts, and images into a zip that Antora consumes as its UI.
- It provides both local preview capabilities (via a Gulp‐powered dev server) and a CI/CD pipeline for automated releases to GitHub.

##### File structure
- Top‐level:
- Configuration files (.eslintrc, .stylelintrc, .gitignore, netlify.toml, package.json, gulpfile.js)
- build/ (output artifacts: ui‐bundle.zip)
- gulp.d/ (modular Gulp tasks: build, preview, bundle, lint, release)
- preview-src/ (sample AsciiDoc pages for local preview)
- src/
– css/ (site and component styles, vendor files, typeface definitions)
– js/ (site interactivity modules, vendor libs)
– layouts/ (Handlebars page layouts)
– partials/ (HTML fragments injected into layouts)
– helpers/ (JavaScript helpers for templates)
– img/, font/
- CI:
- .github/workflows/release.yml triggers `gulp release` on pushes to master.
- package.json scripts (npm start, etc.)

##### Key insights from README
- Local development: `npm install` → `gulp preview` / `npm start` (watch + live‐reload).
- Bundling: `gulp bundle` (or `bundle:pack`) produces build/ui‐bundle.zip.
- Releases: `gulp release` is CI‐driven, tags the repo, publishes a GitHub Release with the bundle asset.
- Antora integration: users reference the zip in their playbook to apply the UI.

##### Main components and their interactions
a. Source Repository (GitHub)
- Contains all source files, Gulp tasks, configs.
b. Developer Local Environment
- Node.js + npm dependencies → Gulp CLI → preview server → browser live‐reload.
- Build tasks: compile CSS/JS, copy assets, assemble templates.
c. Build & Packaging Layer (Gulp)
- Tasks: build, lint, preview:build, bundle, pack, release.
- Outputs: site.css, site.js, source maps, ui‐bundle.zip.
d. CI/CD Pipeline (GitHub Actions)
- On push to master: runs `gulp release`, creates Git tag, GitHub Release, attaches bundle.
e. Artifact Store (GitHub Releases)
- UI bundle ZIP is stored as a release asset.
f. Consumer (Antora)
- Antora playbook references the bundle URL to render the docs site.
g. (Optional) Deployment/Preview Host (Netlify)
- netlify.toml suggests readiness for hosting preview builds.

##### Architectural patterns and design principles
- Modular Gulp tasks (in gulp.d/) for separation of concerns: build vs. lint vs. release vs. preview.
- Clear separation of source (src/, preview-src/) and build output (build/).
- Template‐driven UI: Handlebars with JavaScript helpers for dynamic content.
- Asset bundling and minification for lean production bundles.
- CI as code: release process automated via GitHub Actions + Gulp.

##### Detailed layering (top‐down)
1. Developer Workstation
- Clone repo (Git)
- npm install → node_modules
- Run `gulp preview` → preview server
2. Build Layer (Gulp)
- Tasks read src/ and preview‐src/
- Lint CSS/JS → compile & bundle → build/ui‐bundle.zip
3. CI/CD Layer
- GitHub Actions triggers `gulp release`
- Creates Git tag & Release → attaches UI bundle
4. Consumption Layer
- Antora playbook references release asset URL
- Docs site generation & deployment (Netlify/Antora host)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository
    subgraph "Source Repository"
        GI[".gitignore"]:::code
        ESL[".eslintrc"]:::code
        STLint[".stylelintrc"]:::code
        NETCFG["netlify.toml"]:::code
        PKG["package.json"]:::code
        GULPFILE["gulpfile.js"]:::code
        README["README.adoc"]:::code
        LIC["LICENSE"]:::code
    end

    %% Developer Workstation
    subgraph "Developer Workstation"
        NPM["npm install"]:::process
        BUILDPREV["build-preview-pages.js"]:::process
        SERVE["serve.js"]:::process
        BROWS["Browser (live-reload)"]:::external
    end

    %% Build Layer (Gulp)
    subgraph "Build Layer (Gulp)"
        GULPINDEX["index.js"]:::process
        BUILD["build.js"]:::process
        PACK["pack.js"]:::process
        REMOVE["remove.js"]:::process
        LINTJS["lint-js.js"]:::process
        LINTCSS["lint-css.js"]:::process
        FORMAT["format.js"]:::process
        LIB1["create-task.js"]:::process
        LIB2["export-tasks.js"]:::process
        LIB3["gulp-prettier-eslint.js"]:::process
    end

    %% CI/CD Layer
    subgraph "CI/CD (GitHub Actions)"
        GHWF["release.yml"]:::process
        GHTAG["GitHub Actions"]:::process
        GHREL["GitHub Release"]:::artifact
    end

    %% Templates & Helpers
    subgraph "Templates & Helpers"
        LAYOUTS["layouts/"]:::code
        PARTIALS["partials/"]:::code
        HELPERS["helpers/"]:::code
    end

    %% Static Assets
    subgraph "Static Assets"
        CSS["css/"]:::code
        JS["js/"]:::code
        FONT["font/"]:::code
        IMG["img/"]:::code
    end

    %% Artifact
    ARTZIP["ui-bundle.zip"]:::artifact

    %% Consumption Layer
    subgraph "Consumption"
        ANTORA["Antora Docs Generator"]:::external
        NETLIFY["Netlify (preview host)"]:::external
    end

    %% External Services
    NPMREG["npm registry"]:::external

    %% Connections
    GI & ESL & STLint & NETCFG & PKG & GULPFILE & README & LIC -->|"clone/push"| GHTAG
    GHTAG -->|"runs"| GHWF
    GHWF -->|"build release"| GHTAG
    GHTAG -->|"creates"| GHREL
    GHREL -->|"download"| ANTORA

    %% Developer flows
    GI -->|"clone repo"| NPM
    NPM -->|"fetch deps"| NPMREG
    NPM -->|"install"| BUILDPREV
    BEAUTIPvaga--- SERVE
    BUILDPREV -->|"generate pages"| SERVE
    SERVE -->|"serve"| BROWS

    %% Build flows
    NPM -->|"run tasks"| GULPINDEX
    GULPINDEX --> BUILD
    GULPINDEX --> PACK
    GULPINDEX --> REMOVE
    GULPINDEX --> LINTJS
    GULPINDEX --> LINTCSS
    GULPINDEX --> FORMAT
    GULPINDEX --> LIB1
    GULPINDEX --> LIB2
    GULPINDEX --> LIB3

    BUILD --> CSS
    BUILD --> JS
    BUILD --> LAYOUTS
    BUILD --> PARTIALS
    BUILD --> HELPERS
    BUILD --> FONT
    BUILD --> IMG
    PACK --> ARTZIP

    %% Consumption
    ARTZIP --> GHREL
    ARTZIP --> ANTORA
    ANTORA --> NETLIFY

    %% Click events
    click GI "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/.gitignore"
    click ESL "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/.eslintrc"
    click STLint "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/.stylelintrc"
    click NETCFG "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/netlify.toml"
    click PKG "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/package.json"
    click GULPFILE "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulpfile.js"
    click README "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/README.adoc"
    click LIC "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/LICENSE"
    click BUILDPREV "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/build-preview-pages.js"
    click SERVE "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/serve.js"
    click BUILD "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/build.js"
    click PACK "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/pack.js"
    click REMOVE "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/remove.js"
    click LINTJS "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/lint-js.js"
    click LINTCSS "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/lint-css.js"
    click FORMAT "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/format.js"
    click GULPINDEX "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/tasks/index.js"
    click LIB1 "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/lib/create-task.js"
    click LIB2 "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/lib/export-tasks.js"
    click LIB3 "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/gulp.d/lib/gulp-prettier-eslint.js"
    click GHWF "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/.github/workflows/release.yml"
    click ARTZIP "https://github.com/c2pa-org/c2pa-docs-ui/blob/main/build/ui-bundle.zip"
    click LAYOUTS "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/layouts/"
    click PARTIALS "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/partials/"
    click HELPERS "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/helpers/"
    click CSS "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/css/"
    click JS "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/js/"
    click FONT "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/font/"
    click IMG "https://github.com/c2pa-org/c2pa-docs-ui/tree/main/src/img/"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#4C8BF5,color:#000
    classDef process fill:#DFF5D0,stroke:#57A621,color:#000
    classDef artifact fill:#FFE6B3,stroke:#FFA500,color:#000
    classDef external fill:#F0F0F0,stroke:#AAAAAA,color:#000
```
