# opensimulationinterface/osi-documentation architecture

> Architecture diagram of the GitHub repository opensimulationinterface/osi-documentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensimulationinterface/osi-documentation
- Repository: https://github.com/opensimulationinterface/osi-documentation

## Overview

##### Project type and purpose
- This is a documentation-focused repository. It uses AsciiDoc source files, an Antora site generator, and Docker/Asciidoctor for local builds. Its main goal is to assemble, render, and publish the ASAM OSI specification documentation by combining local content and external submodules.

##### File structure
- Top-level directories:
- .antora – Antora playbook and module skeleton (antora.yml, modules/specification).
- content – AsciiDoc chapters, appendices, release notes, contributing guides.
- local_build_tools – helper scripts and Docker Compose snippets for local Asciidoctor builds.
- .github/workflows – CI pipelines for Antora site builds and legacy Asciidoc builds.
- docker-compose.yml – definition of a containerized Asciidoctor service.
- .gitmodules – references two submodule repositories (open-simulation-interface, osi-sensor-model-packaging).

##### README for additional insights
- Explains two build pipelines:
- Asciidoctor (local or legacy CI) – containerized via Docker Compose, renders index.adoc to HTML.
- Antora (current CI) – orchestrated in a separate repo (osi-antora-generator), pulls this repo plus submodules, builds the full site, and publishes to GitHub Pages.

a. Main components
1. Source Content:
– Local AsciiDoc files under content/ and .antora/modules.
– External modules via Git submodules (OSI spec, sensor-model content).
2. Configuration:
– antora.yml (site layout, module mapping).
– Docker Compose YAML and local_build_tools scripts.
– GitHub Actions workflow YAMLs.
3. Build Engines:
– Antora site generator (CI pipeline).
– Asciidoctor container (local/legacy pipeline).
4. CI/CD Platform:
– GitHub Actions (triggers on push to main).
5. Output & Deployment:
– Static HTML site.
– Hosted on GitHub Pages via osi-antora-generator.
b. Relationships & data flow
– Content repositories (this repo + submodules) feed into Antora Playbook.
– antora.yml and module descriptors tell Antora how to assemble pages.
– GitHub Actions invokes Antora, producing HTML.
– Docker Compose or local_build_tools scripts invoke Asciidoctor for local preview builds.
– Final site artifacts are deployed to GitHub Pages.
c. Architectural patterns & principles
– Modular documentation (Antora modules pattern).
– Pipeline-as-code (GitHub Actions YAML).
– Containerized local builds for reproducibility.
– External content integration via Git submodules.
d. Key technologies & frameworks
– AsciiDoc / Antora / Asciidoctor
– Docker & Docker Compose
– GitHub Actions / Git submodules

##### Key details
– Labels for all repos, modules, and workflows.
– The dual-pipeline nature (CI vs local).
– The role of antora.yml in orchestrating module assembly.
– Deployment path to GitHub Pages.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Source Artifacts"
    direction TB
    Content["Local AsciiDoc Source Content"]:::source
    Pages["Asciidoc Chapter & Module Pages"]:::source
    Assets["Static Assets & Images for Content"]:::source
    Submodules["Git Submodule References"]:::source
  end

  subgraph "Configuration"
    direction TB
    AntoraYml["Antora Playbook Configuration"]:::config
    ModuleSkeleton["Antora Module Skeletons"]:::config
    DockerComposeDef["Docker Compose Definition for Asciidoctor Container"]:::config
    LocalBuildScripts["Local Build Helper Scripts & Compose Snippet"]:::config
    README["Project Metadata & Introductory Documentation"]:::config
  end

  subgraph "Build Engines & CI"
    direction TB
    Workflow1["CI Pipeline - Antora Site Build Workflow"]:::config
    Workflow2["CI Pipeline - Legacy Asciidoc Build Workflow"]:::config
    Workflow3["CI Pipeline - Remote Release Workflow"]:::config
    GHActions["GitHub Actions Runner"]:::exec
    AntoraPlaybook["Antora Playbook"]:::exec
    AsciidoctorContainer["Asciidoctor Container"]:::exec
  end

  subgraph "Outputs"
    direction TB
    LocalHTML["Local HTML Preview"]:::output
    StaticHTML["Static HTML Site"]:::output
  end

  Content --> AntoraPlaybook
  Pages --> AntoraPlaybook
  Assets --> AntoraPlaybook
  Submodules --> AntoraPlaybook
  AntoraYml --> AntoraPlaybook
  ModuleSkeleton --> AntoraPlaybook

  Workflow1 --> GHActions
  Workflow2 --> GHActions
  Workflow3 --> GHActions
  GHActions --> AntoraPlaybook
  AntoraPlaybook --> StaticHTML

  DockerComposeDef --> AsciidoctorContainer
  LocalBuildScripts --> AsciidoctorContainer
  AsciidoctorContainer --> LocalHTML

  click AntoraYml "https://github.com/opensimulationinterface/osi-documentation/blob/master/.antora/antora.yml"
  click ModuleSkeleton "https://github.com/opensimulationinterface/osi-documentation/tree/master/.antora/modules/specification"
  click Content "https://github.com/opensimulationinterface/osi-documentation/tree/master/content/"
  click Pages "https://github.com/opensimulationinterface/osi-documentation/tree/master/.antora/modules/specification/pages"
  click Assets "https://github.com/opensimulationinterface/osi-documentation/tree/master/content/_static/"
  click Submodules "https://github.com/opensimulationinterface/osi-documentation/blob/master/.gitmodules"
  click DockerComposeDef "https://github.com/opensimulationinterface/osi-documentation/blob/master/docker-compose.yml"
  click LocalBuildScripts "https://github.com/opensimulationinterface/osi-documentation/blob/master/local_build_tools/compose.yml"
  click Workflow1 "https://github.com/opensimulationinterface/osi-documentation/blob/master/.github/workflows/antora-build.yml"
  click Workflow2 "https://github.com/opensimulationinterface/osi-documentation/blob/master/.github/workflows/asciidoc-build.yml"
  click Workflow3 "https://github.com/opensimulationinterface/osi-documentation/blob/master/.github/workflows/remote_release.yml"
  click README "https://github.com/opensimulationinterface/osi-documentation/blob/master/README.adoc"

  classDef source fill:#cce5ff,stroke:#3399ff,color:#000;
  classDef config fill:#d4edda,stroke:#28a745,color:#000;
  classDef exec fill:#ffe5b4,stroke:#ff9933,color:#000;
  classDef output fill:#f3e6ff,stroke:#9933ff,color:#000;
```
