Confluence Publishing Plan — Read-Only Mirror of NovaTrek Architecture Portal¶

                          Git Push to main
                               │
                               ▼
                    ┌─────────────────────┐
                    │   GitHub Actions     │
                    │   docs-deploy.yml    │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
     ┌────────────────┐ ┌───────────┐ ┌──────────────────┐
     │ generate-all.sh│ │ mark      │ │ Transform        │
     │ + mkdocs build │ │ preprocess│ │ MD → Confluence  │
     └───────┬────────┘ └─────┬─────┘ └────────┬─────────┘
             │                │                 │
             ▼                │                 ▼
     ┌────────────────┐       │        ┌──────────────────┐
     │  Azure SWA     │       │        │ mark publish     │
     │  Deploy        │       │        │ → Confluence API │
     └────────────────┘       │        └──────────────────┘
             │                │                 │
             ▼                │                 ▼
     ┌────────────────┐       │        ┌──────────────────┐
     │  Portal Live   │       │        │  Confluence      │
     │  (mango-sand)  │◄──────┘        │  Space (mirror)  │
     │  PRIMARY       │  same content  │  READ-ONLY       │
     └────────────────┘                └──────────────────┘

<!-- Space: ARCH -->
<!-- Parent: NovaTrek Architecture Portal -->
<!-- Title: svc-check-in — Microservice Deep Dive -->
<!-- Label: microservice, svc-check-in, auto-generated -->

# svc-check-in — Microservice Deep Dive
...

# macOS
brew install mark

# Linux (GitHub Actions)
curl -sL https://github.com/kovetskiy/mark/releases/latest/download/mark_linux_amd64 -o /usr/local/bin/mark
chmod +x /usr/local/bin/mark

# Or via Go
go install github.com/kovetskiy/mark@latest

NovaTrek Architecture Portal (space home)
├── Design Standards
├── Service Catalog
├── Solutions
├── Business Capabilities
├── Tickets
├── Applications
├── Microservice Pages
├── Event Catalog
└── Actor Catalog

> **Interactive Version Available**
> This page has an interactive version with live API exploration at:
> [View on NovaTrek Architecture Portal](https://architecture.novatrek.cc/microservices/svc-check-in/)

<ac:structured-macro ac:name="info">
  <ac:rich-text-body>
    <p><strong>Interactive Version Available</strong><br/>
    This page has an interactive version with live API exploration at:
    <a href="https://architecture.novatrek.cc/microservices/svc-check-in/">View on NovaTrek Architecture Portal</a></p>
  </ac:rich-text-body>
</ac:structured-macro>

# svc-check-in — Operations Check-In Service

## Overview
The Check-In service handles day-of-adventure guest registration...

![Check-In Flow](svg/svc-check-in-post-checkins.svg)

See also: [svc-guest-profiles](svc-guest-profiles.md)

<!-- Space: ARCH -->
<!-- Parent: Microservice Pages -->
<!-- Title: svc-check-in — Operations Check-In Service -->
<!-- Label: microservice, svc-check-in, auto-generated, do-not-edit -->

# svc-check-in — Operations Check-In Service

> **Interactive Version Available**
> View the full interactive version with clickable SVG diagrams and Swagger UI at:
> [NovaTrek Architecture Portal](https://architecture.novatrek.cc/microservices/svc-check-in/)

## Overview
The Check-In service handles day-of-adventure guest registration...

![Check-In Flow](svg/svc-check-in-post-checkins.svg)

See also: [svc-guest-profiles — Guest Identity Service](svc-guest-profiles — Guest Identity Service)

NAV_PARENT_MAP = {
    "standards/": "Design Standards",
    "services/": "Service Catalog",
    "solutions/": "Solutions",
    "capabilities/": "Business Capabilities",
    "tickets/": "Tickets",
    "applications/": "Applications",
    "microservices/": "Microservice Pages",
    "events/": "Event Catalog",
    "actors/": "Actor Catalog",
}

applications/web-guest-portal/wireframes/check-in-confirmation.md
  → Parent: "web-guest-portal" (which itself has Parent: "Applications")

<!-- Macro: ac:image
     ri:filename: svc-check-in-post-checkins.svg
     ac:width: 800 -->

![Check-In Flow|width=800](svg/svc-check-in-post-checkins.svg)

!!! warning "Safety Critical"
    Unknown adventure categories MUST default to Pattern 3 (Full Service).
    This is a safety requirement per ADR-005.

<!-- Macro: warning
     Title: Safety Critical -->
Unknown adventure categories MUST default to Pattern 3 (Full Service).
This is a safety requirement per ADR-005.
<!-- /Macro -->

ARCH Space
│
├── NovaTrek Architecture Portal (Home)
│
├── Design Standards
│   ├── arc42 Template
│   │   ├── Master Document
│   │   ├── 01 Introduction and Goals
│   │   ├── 02 Architecture Constraints
│   │   └── ... (12 sub-pages)
│   ├── C4 Model
│   │   ├── Notation Guide
│   │   ├── C4-PlantUML Guide
│   │   └── Diagram Checklist
│   ├── MADR
│   │   ├── Full Template
│   │   ├── Short Template
│   │   └── Examples
│   ├── ADR Templates
│   │   └── (3 template pages)
│   └── Quality Model
│       └── ISO 25010 Quality Tree
│
├── Service Catalog
│
├── Solutions
│   ├── Solutions Index
│   ├── NTK-10001 — Add Elevation to Trail Response
│   ├── NTK-10002 — Adventure Category Classification
│   ├── NTK-10004 — Guide Schedule Overwrite Bug
│   └── NTK-10005 — Wristband RFID Field
│
├── Business Capabilities
│   └── Business Capabilities Index
│
├── Tickets
│   ├── Tickets Index
│   ├── NTK-10001
│   ├── NTK-10002
│   └── ... (7 tickets)
│
├── Applications
│   ├── Applications Index
│   ├── web-guest-portal
│   │   └── Wireframes
│   │       └── Check-in Confirmation
│   ├── web-ops-dashboard
│   │   └── Wireframes
│   │       └── Live Tracking
│   └── app-guest-mobile
│       └── Wireframes
│           └── Adventure Selection
│
├── Microservice Pages
│   ├── Microservice Pages Index
│   ├── svc-analytics
│   ├── svc-check-in
│   └── ... (19 services)
│
├── Event Catalog
│   ├── Event Catalog Index
│   └── ... (event pages)
│
└── Actor Catalog
    └── ... (actor pages)

# New job in .github/workflows/docs-deploy.yml

  # -------------------------------------------------------------------------
  # Publish to Confluence (read-only mirror)
  # -------------------------------------------------------------------------
  publish-confluence:
    runs-on: ubuntu-latest
    name: Publish to Confluence
    needs: build
    if: github.event_name == 'push'  # Only publish on merge to main
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-site
          path: site/

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip

      - name: Install mark
        run: |
          curl -sL https://github.com/kovetskiy/mark/releases/latest/download/mark_linux_amd64 \
            -o /usr/local/bin/mark
          chmod +x /usr/local/bin/mark

      - name: Prepare Confluence pages
        run: python3 portal/scripts/confluence-prepare.py
        env:
          PORTAL_BASE_URL: https://architecture.novatrek.cc

      - name: Publish to Confluence (dry-run on PR)
        run: |
          mark \
            --base-url "https://${{ vars.CONFLUENCE_DOMAIN }}.atlassian.net/wiki" \
            --username "${{ secrets.CONFLUENCE_USERNAME }}" \
            --password "${{ secrets.CONFLUENCE_API_TOKEN }}" \
            --files "portal/confluence/**/*.md" \
            --color \
            --ci
        env:
          CONFLUENCE_DOMAIN: ${{ vars.CONFLUENCE_DOMAIN }}

      - name: Lock published pages
        run: |
          python3 portal/scripts/confluence-lock-pages.py \
            --base-url "https://${{ vars.CONFLUENCE_DOMAIN }}.atlassian.net/wiki" \
            --username "${{ secrets.CONFLUENCE_USERNAME }}" \
            --api-token "${{ secrets.CONFLUENCE_API_TOKEN }}" \
            --space "ARCH" \
            --label "auto-generated"

                    Push to main
                        │
              ┌─────────┴──────────┐
              │                    │
              ▼                    ▼
         Build Job            (waits)
              │                    │
              ▼                    │
     generate-all.sh               │
     mkdocs build                  │
              │                    │
              ▼                    │
     Upload artifact ──────────────┤
              │                    │
       ┌──────┴──────┐            │
       │             │            │
       ▼             ▼            │
   Deploy to     Publish to       │
   Azure SWA     Confluence       │
       │             │            │
       │        ┌────┘            │
       │        │                 │
       │        ▼                 │
       │   confluence-prepare.py  │
       │   (inject headers,       │
       │    rewrite links,        │
       │    convert admonitions)  │
       │        │                 │
       │        ▼                 │
       │   mark publish           │
       │   (create/update pages,  │
       │    upload SVG attachments)│
       │        │                 │
       │        ▼                 │
       │   confluence-lock-pages  │
       │   (restrict editing)     │
       │                          │
       ▼                          ▼
    Portal Live             Confluence Live
    (primary)               (read-only mirror)

  validate-confluence:
    runs-on: ubuntu-latest
    name: Validate Confluence Output
    needs: build
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-site
          path: site/

      - name: Prepare Confluence pages
        run: python3 portal/scripts/confluence-prepare.py

      - name: Install mark
        run: |
          curl -sL https://github.com/kovetskiy/mark/releases/latest/download/mark_linux_amd64 \
            -o /usr/local/bin/mark
          chmod +x /usr/local/bin/mark

      - name: Dry-run Confluence publish
        run: |
          mark \
            --base-url "https://${{ vars.CONFLUENCE_DOMAIN }}.atlassian.net/wiki" \
            --username "${{ secrets.CONFLUENCE_USERNAME }}" \
            --password "${{ secrets.CONFLUENCE_API_TOKEN }}" \
            --files "portal/confluence/**/*.md" \
            --dry-run \
            --color

"""
confluence-lock-pages.py
Sets edit restrictions on all auto-generated pages so only the
CI service account can modify them.
"""

# For each page with label "auto-generated":
# PUT /wiki/rest/api/content/{id}/restriction
# {
#   "results": [{
#     "operation": "update",
#     "restrictions": {
#       "user": {
#         "results": [{"accountId": "<service-account-id>"}]
#       }
#     }
#   }]
# }

<!-- Label: auto-generated, do-not-edit, novatrek-portal -->

> **This page is auto-generated from Git. Do not edit here.**
> Source: [NovaTrek Architecture Portal](https://architecture.novatrek.cc)
> Any changes made on this Confluence page will be overwritten on the next deploy.

# .github/workflows/confluence-drift-check.yml
name: Confluence Drift Check

on:
  schedule:
    - cron: '0 6 * * 1-5'  # 6 AM UTC weekdays
  workflow_dispatch: {}

jobs:
  check-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: pip install requests pyyaml

      - name: Check for drift
        run: python3 portal/scripts/confluence-drift-check.py
        env:
          CONFLUENCE_BASE_URL: https://${{ vars.CONFLUENCE_DOMAIN }}.atlassian.net/wiki
          CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
          CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}
          CONFLUENCE_SPACE: ARCH

mark \
  --base-url "https://novatrek.atlassian.net/wiki" \
  --username "$CONFLUENCE_USERNAME" \
  --password "$CONFLUENCE_API_TOKEN" \
  --files "portal/confluence/microservices/svc-check-in.md"

portal/docs/**/*.md  ──→  confluence-prepare.py  ──→  portal/confluence/**/*.md
                                    │
                    Reads: portal/mkdocs.yml (nav structure)
                    Reads: portal/docs/**/*.svg (images to stage)
                    Writes: portal/confluence/**/*.md (with mark headers)
                    Copies: SVG/PNG files alongside their Markdown

#!/usr/bin/env python3
"""
confluence-prepare.py
Transforms portal Markdown files into mark-compatible Confluence Markdown.
Reads MkDocs nav structure to determine page hierarchy.
Stages transformed files in portal/confluence/ for mark to publish.
"""

import os
import re
import shutil
import yaml
from pathlib import Path

PORTAL_DIR = Path(__file__).parent.parent
DOCS_DIR = PORTAL_DIR / "docs"
CONFLUENCE_DIR = PORTAL_DIR / "confluence"
MKDOCS_YML = PORTAL_DIR / "mkdocs.yml"
SPACE_KEY = "ARCH"
PORTAL_BASE_URL = os.environ.get(
    "PORTAL_BASE_URL",
    "https://architecture.novatrek.cc"
)

DO_NOT_EDIT_BANNER = """
> **This page is auto-generated from Git. Do not edit here.**
> Source: [{portal_url}]({portal_url})
> Any changes made on this Confluence page will be overwritten on the next deploy.

"""

def load_nav_structure():
    """Parse mkdocs.yml nav to build file → (title, parent) mapping."""
    ...

def convert_admonitions(content: str) -> str:
    """Convert MkDocs admonitions to mark macro syntax."""
    ...

def convert_object_tags(content: str) -> str:
    """Convert <object data='...svg'> to ![alt](path.svg)."""
    ...

def rewrite_internal_links(content: str, nav_map: dict) -> str:
    """Rewrite [text](file.md) to [text](Confluence Page Title)."""
    ...

def inject_headers(content: str, space: str, parent: str,
                   title: str, labels: list) -> str:
    """Prepend mark metadata headers."""
    ...

def prepare_file(src: Path, dst: Path, nav_map: dict):
    """Full transformation pipeline for a single file."""
    ...

def main():
    nav_map = load_nav_structure()
    if CONFLUENCE_DIR.exists():
        shutil.rmtree(CONFLUENCE_DIR)
    CONFLUENCE_DIR.mkdir(parents=True)

    for md_file in DOCS_DIR.rglob("*.md"):
        rel = md_file.relative_to(DOCS_DIR)
        dst = CONFLUENCE_DIR / rel
        dst.parent.mkdir(parents=True, exist_ok=True)
        prepare_file(md_file, dst, nav_map)

    # Copy images alongside their referencing markdown
    for img in DOCS_DIR.rglob("*.svg"):
        dst = CONFLUENCE_DIR / img.relative_to(DOCS_DIR)
        dst.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(img, dst)

    print(f"Prepared {sum(1 for _ in CONFLUENCE_DIR.rglob('*.md'))} "
          f"Confluence pages in {CONFLUENCE_DIR}")

if __name__ == "__main__":
    main()

# Publish all files matching glob
mark --files "portal/confluence/**/*.md" \
     --base-url "https://novatrek.atlassian.net/wiki" \
     --username "user@example.com" \
     --password "ATATT3xxxxxxxxxxx"

# Dry-run (validate without publishing)
mark --files "portal/confluence/**/*.md" \
     --base-url "https://novatrek.atlassian.net/wiki" \
     --username "user@example.com" \
     --password "ATATT3xxxxxxxxxxx" \
     --dry-run

# Publish single file
mark --files "portal/confluence/microservices/svc-check-in.md" \
     --base-url "https://novatrek.atlassian.net/wiki" \
     --username "user@example.com" \
     --password "ATATT3xxxxxxxxxxx"

# With color output and CI mode (non-interactive)
mark --files "portal/confluence/**/*.md" \
     --base-url "https://novatrek.atlassian.net/wiki" \
     --username "user@example.com" \
     --password "ATATT3xxxxxxxxxxx" \
     --color --ci

# Trace mode for debugging
mark --files "portal/confluence/solutions/*.md" \
     --base-url "https://novatrek.atlassian.net/wiki" \
     --username "user@example.com" \
     --password "ATATT3xxxxxxxxxxx" \
     --trace

<!-- Space: ARCH -->
<!-- Parent: {parent_page_title} -->
<!-- Title: {page_title} -->
<!-- Label: auto-generated, do-not-edit, novatrek-portal, {content-type-label} -->

> **This page is auto-generated from the NovaTrek Architecture Portal.**
> **Source of truth:** [View on Architecture Portal]({portal_url}/{page_path})
> **Do not edit this page.** Changes will be overwritten on the next deploy.