Architecture

This project is operated through Make targets and installed CLI commands. Start from the workflow you need, then follow the links into the implementation only when you are changing behavior.

Entry Point Map

Workflow	Maintainer entry point	Direct CLI or helper	Main code
Expand an upstream compact template	make transform	dsw-template-transform	template_transform.py, _template_transform/
Export, audit, merge, and sync translation trees	make export-translation-tree, make audit-translation-tree, make merge-translation-tree, make sync-translation-tree	dsw-template-tree	translation_tree.py, _translation_tree/
Render one project preview or release package	make render-project, make render-package	dsw-template-render-project	cli/render_project.py, render_project.py
Run and prove render regression	make render-regression, make render-regression-ci-plan, make render-translated-package-regression, make verify-runtime-evidence	dsw-template-render-regression, verify_runtime_evidence.py	cli/render_regression.py, workflow.py, regression_config.py, runtime_evidence.py
Build clean upstream scaffold artifacts	make discover-upstream-compat, make build-upstream-artifacts, make render-upstream-artifact-previews	CI helpers under scripts/ci/	dsw_compat.py, compat_ledger.py
Refresh public repository sync/v* branches	make sync-translation-version-branches, make check-translation-migrations	sync_translation_version_branches.py	translation_repository/
Review wording across public repository versions	make report-translation-consistency	report_translation_consistency.py	translation_repository/consistency.py
Publish clean scaffold release assets	make publish-clean-scaffold-releases	publish_clean_scaffold_releases.py	stage_release_assets.py

For exact command syntax, use Command Reference. For where each operation fits in day-to-day maintenance, use Operator Quickstart.

Repository Shape

• src/dsw_document_template_tool/ is the Python package. Maintained direct CLIs live under src/dsw_document_template_tool/cli/.

• scripts/ci/ contains GitHub Actions helpers and cross-repository automation. These scripts may be run directly for debugging, but Make targets are the supported operator interface.

• config/ contains regression, compatibility, lint, and dependency configuration.

• fixtures/ contains checked-in demo and regression project fixtures plus matching Knowledge Model bundles.

• examples/ contains public repository workflow and documentation templates. Updating an example does not update existing public repository branches by itself.

• workspace/, outputs/, and .cache/ are generated operator workspaces, build outputs, and caches. They should stay out of master unless a file is a reusable fixture under fixtures/.

Code Layers

Template Transform

The transform layer expands an upstream compact template into a translation-safe workspace. It preserves complete translatable sentences around Jinja branches and records enough metadata for later audits.

Key files:

• _template_transform/workspace.py reads and writes compact and expanded template workspaces.

• _template_transform/scanner.py scans template files for translatable regions.

• _template_transform/markers.py writes and reads translation marker comments.

• _template_transform/rewrite_rules.py provides shared rewrite rule primitives.

• _template_transform/profile.py selects template-family behavior from template.json and records every named rewrite group in .transform/manifest.json. make explain-transform prints the same trace for maintainers.

• _template_transform/branch_groups.py, branch_sentences.py, inline_conditionals.py, and append_sentences.py keep optional and branched text translatable as whole sentences.

• _template_transform/science_europe.py, science_europe_balanced_rules.py, and science_europe_unbalanced_rules.py isolate Science Europe-specific rewrite behavior.

• _template_transform/localization.py applies reversible zh-Hant package metadata, HTML language, and PDF typography adjustments during transform. Compaction removes these adjustments before comparing with upstream source.

Change this layer when upstream Jinja or HTML structure needs to be split, joined, or marked differently before translators see it.

Translation Tree

The translation tree layer owns translator-facing translation.md files, metadata, migration, audits, and final sync back into a translated expanded template.

Key files:

• _translation_tree/extraction.py extracts marked translatable units from expanded templates.

• _translation_tree/source_quality_rules.py contains named, display-only guards for known upstream sentence fragments. These guards detect parser regressions; they never rewrite executable source.

• _translation_tree/document.py reads and writes human-facing translation.md files.

• _translation_tree/filesystem.py, store.py, and ids.py define stable tree paths and IDs.

• _translation_tree/manifest.py, metadata.py, and outline.py generate review metadata and progress views.

• _translation_tree/merge.py preserves translations during refresh and performs explicit exact-source replacement during cross-version synchronization.

• _translation_tree/apply.py applies translations back into expanded templates.

• _translation_tree/placeholders.py, syntax.py, tree_audit.py, structure_audit.py, and html_structure.py check placeholders, Jinja, and translated output structure.

• _translation_tree/output_polish.py performs target-language cleanup after sync. For zh-Hant it removes unsafe leftover |dot punctuation behavior after the translation has already chosen Chinese punctuation.

• _translation_tree/output_readme.py selects the user-facing README for translated outputs.

Change this layer when the tree format, migration rules, safety checks, output polish, or translator-facing files need to change.

Render, Regression, and Fixtures

Rendering and regression prove that a transformed or translated template still behaves in DSW.

Key files:

• render_project.py is the reusable service that imports fixtures and renders a PDF. Argument parsing and environment variables live in cli/render_project.py.

• api.py normalizes DSW API differences at the transport boundary. In particular, released templates use ID-based references on DSW 4.26 and UUID-based references on current DSW; render and regression services consume one shared reference model instead of branching on DSW versions.

• cli/render_regression.py runs equality comparisons or single-package render assertions.

• regression_config.py generates version-aware equality configs and translated-package render configs while selecting pinned KM evidence.

• fixture_generator.py creates deterministic generated project fixtures from compiled DSW questionnaire models.

• fixture_coverage.py inventories reachable questionnaire branches and selects a compact fixture set before DSW rendering.

• regression_evidence.py validates immutable KM provenance and runtime assignments from config/regression-evidence.yml.

• runtime_evidence.py joins runtime, KM, coverage, comparison, and PDF outputs into the final CI proof instead of leaving maintainers to infer success from separate logs.

• html_diff.py normalizes rendered HTML and reports behavior differences.

• workflow.py contains DSW lifecycle and regression orchestration. It keeps compact/expanded equality checks distinct from translated-package render-success checks. Deterministic artifacts and isolated parallel renders live under _regression/.

• tdk.py wraps dsw-tdk calls.

Change this layer when previews, regression coverage, fixture handling, or DSW interaction behavior needs to change. Keep API-generation differences in api.py; do not scatter version checks through workflows or CLI commands.

Runtime and CI Helpers

The runtime layer maps upstream template metamodels to DSW and dsw-tdk versions, then feeds that mapping into CI and release automation.

Key files:

• translation_repository/runtime.py strictly loads the proven runtime table in config/dsw-compat.yml.

• regression_evidence.py maps each runtime key to a pinned KM fixture and rejects stale checksums or metadata before DSW starts.

• dsw_compat.py reads the official DSW specification only to suggest candidates for unknown metamodels. Candidates do not become trusted runtimes until full regression, strict preview, and runtime evidence pass.

• compat_probe.py owns the typed probe plan and stable rendering of runtime/evidence changes. It keeps compatibility policy out of Git and GitHub orchestration code.

• compat_ledger.py writes compatibility fingerprints for clean scaffold artifacts.

• discover_dsw_compat.py checks upstream tags against configured runtimes.

• sync_dsw_runtime_matrix.py regenerates GitHub Actions matrices from config/dsw-compat.yml.

• create_dsw_compat_pr.py opens or updates follow-up PRs when new upstream metamodels need runtime confirmation; it delegates planning and config rendering to compat_probe.py.

Change this layer when upstream versions, DSW runtime support, GitHub Actions matrices, or release asset staging behavior changes.

Public Repository Policy

The translation_repository/ package is the typed boundary shared by tool and public-repository workflows. config.py validates translation-config.yml, policy.py decides lifecycle behavior, paths.py derives branch/workspace paths, runtime.py selects DSW runtimes, and versions.py owns semantic-version matching. Import the package facade from automation; edit the focused module that owns the behavior.

Ownership Rules

• If a change affects sentence boundaries, Jinja branch grouping, or what a translator sees, update the transform or translation tree layer and run the parser checklist in Parser and Translation Tree.

• If a workflow step needs parsing, branching, GitHub API calls, or cross-repository behavior, put it in scripts/ci/ with tests instead of embedding it only in YAML.

• If a behavior is specific to one upstream template family, isolate it in a named template-specific module rather than a generic utility.

• If a command is meant for maintainers, expose it through Makefile and document it in Command Reference.