feat: Add architecture documentation in architecture tab and ADRs

docs/architecture/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Catena-X Certification",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}

docs/architecture/adrs/0001-record-monorepo-decision.md

@@ -0,0 +1,21 @@
+---
+title: 0001 - Use a monorepo for documentation and docs tooling
+sidebar_position: 2
+---
+
+Status: Accepted
+
+## Context
+
+We maintain multiple related documentation repositories and versioned docs. Synchronizing tooling and cross-references is occasionally error-prone.
+
+## Decision
+
+Adopt a monorepo approach for housing documentation, site tooling, and shared assets.
+
+## Consequences
+
+- Easier cross-references and versioned-site builds.
+- Centralized scripts to build PDFs for ADRs.
+
+Download PDF: [adr-0001-use-monorepo.pdf](/adrs/adr-0001-use-monorepo.pdf)

docs/architecture/adrs/0002-record-versioning-strategy.md

@@ -0,0 +1,16 @@
+---
+title: 0002 - ADR versioning and retention policy
+sidebar_position: 3
+---
+
+Status: Proposed
+
+## Context
+
+Decisions evolve; stakeholders need stable references to the decision at a given point in time.
+
+## Decision
+
+Keep ADRs immutable after acceptance; publish errata as new ADRs.
+
+Download PDF: [adr-0002-versioning-policy.pdf](/adrs/adr-0002-versioning-policy.pdf)

docs/architecture/adrs/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Architecture Decision Records",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}

docs/architecture/adrs/index.md

@@ -0,0 +1,30 @@
+---
+title: Architecture Decision Records (ADRs)
+slug: /architecture/adrs/
+sidebar_position: 1
+---
+
+This directory contains the Architecture Decision Records (ADRs) for Catena‑X.
+
+- ADRs are stored as Markdown files under this folder.
+- A downloadable PDF version can be provided alongside each ADR in `static/adrs/`.
+
+How to add a PDF for an ADR
+
+1. Install `pandoc` and a PDF engine (e.g., `wkhtmltopdf` or LaTeX).
+2. Run the included script to generate PDFs from the ADR markdown files:
+
+```bash
+# from repo root
+./scripts/generate-adrs-pdfs.sh
+```
+
+Generated PDFs will be placed in `static/adrs/` and will be available for download at `/adrs/<filename>.pdf`.
+
+If you prefer to upload prebuilt PDFs, add them to `static/adrs/` with the same basename as the ADR markdown.
+
+| ADR | Status | PDF |
+|---|---|---|
+| [0001 - Use a monorepo for documentation and docs tooling](./0001-record-monorepo-decision) | Accepted | <a class="button" href="/adrs/0001-record-monorepo-decision.pdf">PDF (if available)</a> |
+| [0002 - ADR versioning and retention policy](./0002-record-versioning-strategy) | Proposed | <a class="button" href="/adrs/0002-record-versioning-strategy.pdf">PDF (if available)</a> |
+

docs/architecture/certification.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+---
+# Catena-X Architecture
+
+:::info
+
+Coming Soon
+
+:::

docusaurus.config.ts

@@ -154,6 +154,12 @@ const config: Config = {
           position: "left",
           label: "Working Model",
         },
+        {
+          type: "docSidebar",
+          sidebarId: "sidebar_architecture",
+          position: "left",
+          label: "Architecture",
+        },
         {
           type: 'dropdown',
           label: 'Releases',

package.json

@@ -14,7 +14,11 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "lint": "markdownlint --ignore node_modules --config .markdownlint.json '**/*.md'",
-    "prepare": "husky install"
+    "prepare": "husky install",
+    "generate:adrs-index": "node scripts/generate-adr-index.js"
+  },
+  "adrs": {
+    "generatePdfScript": "scripts/generate-adrs-pdfs.sh"
   },
   "dependencies": {
     "@docusaurus/core": "^3.9.2",
@@ -56,4 +60,5 @@
   "engines": {
     "node": ">=18.0"
   }
+
 }

scripts/generate-adr-index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const ADRS_DIR = path.join(ROOT, 'docs', 'architecture', 'adrs');
+const INDEX_FILE = path.join(ADRS_DIR, 'index.md');
+const STATIC_ADRS = path.join(ROOT, 'static', 'adrs');
+
+function readFiles() {
+  return fs.readdirSync(ADRS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .filter(f => !['index.md'].includes(f))
+    .map(f => path.join(ADRS_DIR, f));
+}
+
+function extractMeta(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  // frontmatter title
+  const fm = /^---\n([\s\S]*?)\n---/m.exec(content);
+  let title = null;
+  let status = '';
+  if (fm) {
+    const body = fm[1];
+    const mTitle = /title:\s*(.+)/.exec(body);
+    if (mTitle) title = mTitle[1].trim();
+  }
+  if (!title) {
+    const mH = /^#\s+(.+)$/m.exec(content);
+    if (mH) title = mH[1].trim();
+  }
+  const mStatus = /^Status:\s*(.+)$/m.exec(content);
+  if (mStatus) status = mStatus[1].trim();
+  return { title: title || path.basename(filePath), status };
+}
+
+function buildTable(items) {
+  const header = '| ADR | Status | PDF |\n|---|---|---|\n';
+  const rows = items.map(({file, meta}) => {
+    const base = path.basename(file, '.md');
+    const docLink = `./${base}`;
+    const pdfPath = `/adrs/${base}.pdf`;
+    const download = fs.existsSync(path.join(STATIC_ADRS, `${base}.pdf`))
+      ? `<a class="button" href="${pdfPath}" download>Download PDF</a>`
+      : `<a class="button" href="${pdfPath}">PDF (if available)</a>`;
+    return `| [${meta.title}](${docLink}) | ${meta.status || ''} | ${download} |`;
+  }).join('\n');
+  return header + rows + '\n';
+}
+
+function main() {
+  const files = readFiles();
+  const items = files.map(f => ({ file: f, meta: extractMeta(f) }));
+  const table = buildTable(items);
+
+  let index = fs.readFileSync(INDEX_FILE, 'utf8');
+  const token = '<!-- ADR_TABLE -->';
+  if (!index.includes(token)) {
+    // append token at end
+    index = index + '\n\n' + token + '\n';
+  }
+  const out = index.replace(token, table);
+  fs.writeFileSync(INDEX_FILE, out, 'utf8');
+  console.log('Wrote ADR table into', INDEX_FILE);
+}
+
+main();

scripts/generate-adrs-pdfs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generates PDFs for ADR markdown files into static/adrs/
+# Requires: pandoc and a PDF engine (e.g. wkhtmltopdf or a TeX distribution)
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ADRS_MD_DIR="$ROOT_DIR/docs/architecture/adrs"
+OUT_DIR="$ROOT_DIR/static/adrs"
+
+mkdir -p "$OUT_DIR"
+
+echo "Generating ADR PDFs from $ADRS_MD_DIR to $OUT_DIR"
+
+if ! command -v pandoc >/dev/null 2>&1; then
+  cat >&2 <<'EOF'
+Error: pandoc is not installed or not on PATH.
+
+On macOS you can install it with Homebrew:
+  brew install pandoc
+
+If you need a PDF engine (recommended) also install a TeX distribution or wkhtmltopdf:
+  brew install --cask basictex
+  sudo tlmgr update --self
+  sudo tlmgr install collection-fontsrecommended
+
+Or install wkhtmltopdf instead of TeX:
+  brew install wkhtmltopdf
+
+Then re-run this script.
+EOF
+  exit 127
+fi
+
+for f in "$ADRS_MD_DIR"/*.md; do
+  [ -e "$f" ] || continue
+  base=$(basename "$f" .md)
+  out="$OUT_DIR/${base}.pdf"
+  echo "-> $base -> $out"
+  # Prefer xelatex if available; pandoc will error if no PDF engine is available.
+  pandoc "$f" -o "$out" --pdf-engine=xelatex || pandoc "$f" -o "$out"
+done
+
+echo "Done. PDFs are in $OUT_DIR"

sidebars.ts

@@ -15,6 +15,7 @@ const sidebars: SidebarsConfig = {
   sidebar_standards: [{type: 'autogenerated', dirName: 'standards'}],
   sidebar_op_model: [{type: 'autogenerated', dirName: 'operating-model'}],
   sidebar_certification: [{type: 'autogenerated', dirName: 'certification'}],
+  sidebar_architecture: [{type: 'autogenerated', dirName: 'architecture'}],
   sidebar_regulatory_framework: [{type: 'autogenerated', dirName: 'regulatory-framework'}],
   sidebar_working_model: [{type: 'autogenerated', dirName: 'working-model'}],
 

versioned_docs/version-24.03/architecture/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Catena-X Certification",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}

versioned_docs/version-24.03/architecture/certification.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+# Catena-X Architecture
+
+:::info
+
+Coming Soon
+
+:::
+

versioned_docs/version-Io/architecture/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Catena-X Certification",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}

versioned_docs/version-Io/architecture/certification.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+# Catena-X Architecture
+
+:::info
+
+Coming Soon
+
+:::
+

versioned_docs/version-Jupiter/architecture/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Catena-X Certification",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}

versioned_docs/version-Jupiter/architecture/certification.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+# Catena-X Architecture
+
+:::info
+
+Coming Soon
+
+:::
+

versioned_docs/version-Saturn/architecture/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Catena-X Certification",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}

versioned_docs/version-Saturn/architecture/certification.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+# Catena-X Architecture
+
+:::info
+
+Coming Soon
+
+:::
+

versioned_sidebars/version-24.03-sidebars.json

@@ -17,6 +17,12 @@
       "dirName": "working-model"
     }
   ],
+  "sidebar_architecture": [
+    {
+      "type": "autogenerated",
+      "dirName": "architecture"
+    }
+  ],
   "sidebar_regulatory_framework": [
     {
       "type": "autogenerated",

versioned_sidebars/version-Io-sidebars.json

@@ -17,6 +17,12 @@
       "dirName": "certification"
     }
   ],
+  "sidebar_architecture": [
+    {
+      "type": "autogenerated",
+      "dirName": "architecture"
+    }
+  ],
   "sidebar_regulatory_framework": [
     {
       "type": "autogenerated",

versioned_sidebars/version-Jupiter-sidebars.json

@@ -17,6 +17,12 @@
       "dirName": "certification"
     }
   ],
+  "sidebar_architecture": [
+    {
+      "type": "autogenerated",
+      "dirName": "architecture"
+    }
+  ],
   "sidebar_regulatory_framework": [
     {
       "type": "autogenerated",

versioned_sidebars/version-Saturn-sidebars.json

@@ -17,6 +17,12 @@
       "dirName": "certification"
     }
   ],
+  "sidebar_architecture": [
+    {
+      "type": "autogenerated",
+      "dirName": "architecture"
+    }
+  ],
   "sidebar_regulatory_framework": [
     {
       "type": "autogenerated",