# senges/tovald architecture

> Architecture diagram of the GitHub repository senges/tovald, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/senges/tovald
- Repository: https://github.com/senges/tovald

## Overview

#### Purpose and Entry Points
Tovald is a Python CLI that publishes a directory tree of Markdown documentation to a Confluence space. The executable entry path is `tovald/main.py`; package metadata and runtime dependencies are defined in `pyproject.toml`. Invocation accepts a documentation root and an optional cleanup mode.

#### CLI Orchestration
`tovald/main.py` reads CLI arguments and environment-based Confluence settings, then drives compilation and publication. `tovald/conf.py` centralizes generated Sphinx/Confluence configuration, keeping runtime credentials and publication policy separate from source Markdown.

#### Documentation Tree Contract
The input boundary is a filesystem tree in which each Confluence page is a directory containing `index.md`; optional `.assets` directories hold page-local static files. The compiler must preserve directory hierarchy as a Confluence page hierarchy and derive page titles from top-level Markdown headings. Fixture trees demonstrate valid and invalid structural cases under `tests/static/valid_tree/doc` and `tests/static/missing_index_tree/doc`.

#### Compilation Stage
`tovald/compiler/main.py` transforms the source documentation tree into a Sphinx-compatible intermediate project. This includes validating page structure, generating navigation/toctree material from the directory tree, and preparing content/assets for Sphinx processing. Its package boundary is `tovald/compiler/__init__.py`; the generated toctree template is `tovald/static/toctree.j2`.

#### Sphinx-to-Confluence Publication
The generated Sphinx project is configured to use MyST Markdown parsing and `sphinxcontrib-confluencebuilder`, which renders pages and calls Confluence using the configured server URL, space key, parent page, PAT, source URL, and optional page-name prefix. Sphinx/Confluence output is an external-service boundary; Tovald primarily supplies project structure and configuration rather than implementing rendering or Confluence API behavior itself.

#### Cleanup Control Path
The `--cleanup` flag in `tovald/main.py` represents a distinct publication-management path, intended to remove or reconcile previously published pages rather than merely compile and publish current content. It shares the Confluence configuration boundary in `tovald/conf.py`.

#### Runtime and Delivery
The project runs on Python and is packaged for direct installation or `uv` execution (`pyproject.toml`, `uv.lock`). A containerized runtime is defined by `Dockerfile`. GitHub Actions provide lint/test and image/package build-publish pipelines: `.github/workflows/lint-and-test.yml`, `.github/workflows/docker-build.yml`, and `.github/workflows/build-and-publish.yml`.

Main entry points: [`tovald/main.py`](https://github.com/senges/tovald/blob/main/tovald/main.py) (CLI entry point), [`tovald/compiler/main.py`](https://github.com/senges/tovald/blob/main/tovald/compiler/main.py) (Documentation compiler), [`pyproject.toml`](https://github.com/senges/tovald/blob/main/pyproject.toml) (Package definition), [`tovald/conf.py`](https://github.com/senges/tovald/blob/main/tovald/conf.py) (Confluence configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["CLI entry point<br/>Python CLI<br/>[main.py]"]
  node_package["Package definition<br/>Python packaging<br/>[pyproject.toml]"]
  node_container["Container runtime<br/>Docker image"]
end

subgraph group_compiler["Compilation"]
  node_compiler_api["Compiler package<br/>package boundary<br/>[__init__.py]"]
  node_compiler_main["Documentation compiler<br/>transformer<br/>[main.py]"]
  node_toctree_template["Toctree template<br/>Jinja template<br/>[toctree.j2]"]
  node_sphinx_project["Generated Sphinx project<br/>intermediate project"]
end

subgraph group_publication["Publication"]
  node_conf["Confluence configuration<br/>configuration boundary<br/>[conf.py]"]
  node_sphinx{{"Sphinx + MyST<br/>renderer"}}
  node_confluence_builder{{"Confluence builder<br/>Sphinx extension"}}
  node_confluence[("Confluence space<br/>external service")]
  node_cleanup["Cleanup operation<br/>publication management<br/>[main.py]"]
end

subgraph group_delivery["Delivery"]
  node_lint_test["Lint and test workflow<br/>GitHub Actions workflow<br/>[lint-and-test.yml]"]
  node_docker_build["Docker build workflow<br/>GitHub Actions workflow<br/>[docker-build.yml]"]
  node_package_publish["Package publish workflow<br/>GitHub Actions workflow"]
end

node_doc_tree["Markdown documentation tree<br/>input contract"]
node_valid_fixture["Valid tree fixture"]
node_invalid_fixture["Missing-index fixture"]

node_valid_fixture -.->|"demonstrates"| node_doc_tree
node_invalid_fixture -.->|"tests invalid contract"| node_doc_tree
node_package -->|"installs runtime"| node_cli
node_container -->|"runs"| node_cli
node_cli -->|"invokes"| node_compiler_api
node_compiler_api -->|"exposes"| node_compiler_main
node_doc_tree -->|"source input"| node_compiler_main
node_toctree_template -->|"generates navigation"| node_compiler_main
node_compiler_main -->|"builds"| node_sphinx_project
node_cli -->|"loads settings"| node_conf
node_sphinx_project -->|"renders"| node_sphinx
node_conf -->|"configures"| node_confluence_builder
node_sphinx -->|"uses extension"| node_confluence_builder
node_confluence_builder -->|"publishes pages"| node_confluence
node_cli -->|"--cleanup"| node_cleanup
node_cleanup -->|"uses settings"| node_conf
node_cleanup -->|"reconciles pages"| node_confluence
node_lint_test -.->|"validates"| node_package
node_docker_build -->|"builds image"| node_container
node_package_publish -->|"builds and publishes"| node_package

click node_valid_fixture "https://github.com/senges/tovald/tree/main/tests/static/valid_tree/doc"
click node_invalid_fixture "https://github.com/senges/tovald/tree/main/tests/static/missing_index_tree/doc"
click node_cli "https://github.com/senges/tovald/blob/main/tovald/main.py"
click node_package "https://github.com/senges/tovald/blob/main/pyproject.toml"
click node_container "https://github.com/senges/tovald/blob/main/Dockerfile"
click node_compiler_api "https://github.com/senges/tovald/blob/main/tovald/compiler/__init__.py"
click node_compiler_main "https://github.com/senges/tovald/blob/main/tovald/compiler/main.py"
click node_toctree_template "https://github.com/senges/tovald/blob/main/tovald/static/toctree.j2"
click node_conf "https://github.com/senges/tovald/blob/main/tovald/conf.py"
click node_cleanup "https://github.com/senges/tovald/blob/main/tovald/main.py"
click node_lint_test "https://github.com/senges/tovald/blob/main/.github/workflows/lint-and-test.yml"
click node_docker_build "https://github.com/senges/tovald/blob/main/.github/workflows/docker-build.yml"
click node_package_publish "https://github.com/senges/tovald/blob/main/.github/workflows/build-and-publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_package,node_container toneBlue
class node_compiler_api,node_compiler_main,node_toctree_template,node_sphinx_project toneAmber
class node_conf,node_sphinx,node_confluence_builder,node_confluence,node_cleanup toneMint
class node_lint_test,node_docker_build,node_package_publish toneRose
class node_doc_tree,node_valid_fixture,node_invalid_fixture toneNeutral
```

## Components

### Runtime

- [CLI entry point](https://github.com/senges/tovald/blob/main/tovald/main.py): Python CLI · Reads arguments and environment settings; selects publish or cleanup. · `tovald/main.py`
- [Package definition](https://github.com/senges/tovald/blob/main/pyproject.toml): Python packaging · Defines metadata and runtime dependencies. · `pyproject.toml`
- [Container runtime](https://github.com/senges/tovald/blob/main/Dockerfile): Docker image · `Dockerfile`

### Compilation

- [Compiler package](https://github.com/senges/tovald/blob/main/tovald/compiler/__init__.py): package boundary · `tovald/compiler/__init__.py`
- [Documentation compiler](https://github.com/senges/tovald/blob/main/tovald/compiler/main.py): transformer · Validates structure and creates a Sphinx-compatible project. · `tovald/compiler/main.py`
- [Toctree template](https://github.com/senges/tovald/blob/main/tovald/static/toctree.j2): Jinja template · `tovald/static/toctree.j2`
- **Generated Sphinx project**: intermediate project · Contains prepared Markdown, assets, and generated navigation.

### Publication

- [Confluence configuration](https://github.com/senges/tovald/blob/main/tovald/conf.py): configuration boundary · Supplies publication policy and runtime credentials. · `tovald/conf.py`
- **Sphinx + MyST**: renderer · Parses generated Markdown and renders Confluence content.
- **Confluence builder**: Sphinx extension · Publishes rendered pages using configured Confluence settings.
- **Confluence space**: external service · Receives the directory-derived page hierarchy.
- [Cleanup operation](https://github.com/senges/tovald/blob/main/tovald/main.py): publication management · Removes or reconciles previously published pages. · `tovald/main.py`

### Delivery

- [Lint and test workflow](https://github.com/senges/tovald/blob/main/.github/workflows/lint-and-test.yml): GitHub Actions workflow · `.github/workflows/lint-and-test.yml`
- [Docker build workflow](https://github.com/senges/tovald/blob/main/.github/workflows/docker-build.yml): GitHub Actions workflow · `.github/workflows/docker-build.yml`
- [Package publish workflow](https://github.com/senges/tovald/blob/main/.github/workflows/build-and-publish.yml): GitHub Actions workflow · `.github/workflows/build-and-publish.yml`

### Other components

- **Markdown documentation tree**: input contract · Each page directory requires index.md; .assets is optional.
- [Valid tree fixture](https://github.com/senges/tovald/tree/main/tests/static/valid_tree/doc): fixture · `tests/static/valid_tree/doc`
- [Missing-index fixture](https://github.com/senges/tovald/tree/main/tests/static/missing_index_tree/doc): fixture · `tests/static/missing_index_tree/doc`

## Connections

- Valid tree fixture → Markdown documentation tree: demonstrates
- Missing-index fixture → Markdown documentation tree: tests invalid contract
- Package definition → CLI entry point: installs runtime
- Container runtime → CLI entry point: runs
- CLI entry point → Compiler package: invokes
- Compiler package → Documentation compiler: exposes
- Markdown documentation tree → Documentation compiler: source input
- Toctree template → Documentation compiler: generates navigation
- Documentation compiler → Generated Sphinx project: builds
- CLI entry point → Confluence configuration: loads settings
- Generated Sphinx project → Sphinx + MyST: renders
- Confluence configuration → Confluence builder: configures
- Sphinx + MyST → Confluence builder: uses extension
- Confluence builder → Confluence space: publishes pages
- CLI entry point → Cleanup operation: --cleanup
- Cleanup operation → Confluence configuration: uses settings
- Cleanup operation → Confluence space: reconciles pages
- Lint and test workflow → Package definition: validates
- Docker build workflow → Container runtime: builds image
- Package publish workflow → Package definition: builds and publishes