archledger

archledger is a source-first arc42 documentation tool. It stores architecture knowledge as small, reviewable Markdown or AsciiDoc records with YAML front matter, validates those records, tracks source drift, and assembles complete arc42-style architecture documents on demand.

Release status

archledger is currently beta.

• Native Markdown and AsciiDoc source workflows are the most stable path.
• Converter-backed exports are supported when the required external tools are installed and validated by CI.
• See docs/changelog.md for recent release-oriented changes and docs/release-process.md for the maintainer release checklist.

What archledger is

archledger is intentionally small:

• project-local configuration through Ledgercore at .ledger/ledger.toml and .ledger/archledger/config.toml
• canonical source fragments in Markdown or AsciiDoc
• a compact Typer CLI for init, read, record creation, validation, source drift tracking, migration, and builds
• deterministic native document assembly with optional converter-backed exports

The “ledger” is the project-local set of architecture records: requirements, decisions, constraints, building blocks, runtime scenarios, deployment nodes, quality scenarios, risks, glossary terms, and diagrams.

archledger is not an accounting ledger, blockchain ledger, Arch Linux package tool, or task tracker.

When to use it

Use archledger when you want architecture documentation that can be updated incrementally by humans or coding agents, reviewed in Git, and assembled into arc42-style documents on demand.

Install

Editable development install:

python -m pip install -e ".[dev]"

Ledger boundary

Archledger is an isolated architecture ledger. It stores architecture records, record links, and source references. It does not import/export behavior specs, enforce SDD policy, run BDD tools, or coordinate other ledgers.

Use generic links or source_refs to point to external artifacts. External resolution is owned by an organizer such as Ledgerdeck.

Safe mutation commands update front matter and re-run repository validation:

archledger record set content-0013 --status accepted
archledger refs add content-0013 --path src/example.py --role implements
archledger links add content-0013 --rel decided_by --target adr-0014
archledger ac add content-0013 --statement "The behavior is covered"

Published schemas and integration scaffolds are available from the CLI:

archledger --json schema --format jsonschema --target record
archledger install github-actions

Normal user install:

python -m pip install .

Docs build support:

python -m pip install -e ".[docs]"

Optional converter tools:

• pandoc for Markdown-source exports and some AsciiDoc exports
• asciidoctor for native AsciiDoc HTML and DocBook conversion
• asciidoctor-pdf for native AsciiDoc PDF output

Converter-backed formats are part of the supported workflow only when those tools are present and the related integration checks pass.

Quick start

Markdown source

archledger init --source-format markdown
archledger init --source-format markdown --id-prefix ta --id-width 3
archledger init --source-format markdown --id-segment-mode type
archledger seed arc42-minimal
archledger --json read --body
archledger build --format markdown

AsciiDoc source

archledger init --source-format asciidoc
archledger seed arc42-minimal
archledger --json read --body
archledger build --format asciidoc

Core concepts

Workspace config

Archledger uses the Ledgercore canonical repository layout. archledger init creates or updates .ledger/ledger.toml, stores stable settings in .ledger/archledger/config.toml, and stores authoritative data at .ledger/archledger/data through one unscoped repository mount. Legacy root-level configs and arbitrary archledger_dir values require archledger migrate project. [build].default_output_dir remains relative to the project root.

Source fragments

Each section file and record file has YAML front matter plus a body in the configured dialect. Example:

---
schema_version: 4
id: adr-0013
kind: adr
type: adr
title: "Treat source fragments as canonical"
status: accepted
section: architecture_decisions
order: 10
version: 1
body_format: markdown
---

body_format must match the project source.format unless you explicitly use the migration escape hatch during a manual source conversion. Archledger CLI mutations increment version; manual source edits must increment it manually.

Sections and records

Sections are the arc42 chapter skeleton. Records hold individual requirements, decisions, building blocks, risks, and other architecture facts. Use the CLI to allocate paths and ids, then edit the generated fragment.

ID format is configurable via [ids]:

[ids]
prefix = "al"
width = 4
segment_mode = "none"
default_segment = "content"

Segmented IDs use:

<prefix>_<segment>_<number>

Example:

al_content_0013
al_risk_0014

segment_mode = "type" resolves the segment deterministically from front matter:

1. id_segment metadata (if present and valid)
2. [ids.segment_map] lookup by type
3. default_segment

Use renumber to migrate existing IDs and references:

archledger renumber --prefix ta --width 3
archledger renumber --prefix ta --width 3 --apply
archledger renumber --id-segment-mode type
archledger renumber --id-segment-mode type --apply
archledger renumber --id-segment-mode none --apply

The numeric sequence is always global and unchanged (for example 0014 stays 0014).

Generated outputs

Generated build outputs are derived artifacts and should not be edited as source. New projects default to build/ under the workspace root, and [build].default_output_dir can place outputs elsewhere. This repository intentionally sets [build].default_output_dir = "." and writes ARCHITECTURE.md at the repository root.

What to commit

For a project that uses archledger, commit the canonical source and config:

• .ledger/ledger.toml
• .ledger/archledger/config.toml
• .ledger/archledger/data/**
• the configured build output when it is intentionally versioned

Do not treat generated build output as canonical source. Determine its location from [build].default_output_dir (or archledger --json paths). Generated build output and converter intermediates are disposable unless you are intentionally debugging an export issue.

Record types

Kind	Common aliases	Default section
requirement	requirement	introduction_and_goals
stakeholder	stakeholder	introduction_and_goals
quality_goal	quality-goal	introduction_and_goals
constraint	constraint	architecture_constraints
context_interface	context-interface	context_and_scope
strategy_item	strategy-item	solution_strategy
white_box	white-box	building_block_view
black_box	black-box	building_block_view
interface	interface	building_block_view
runtime_scenario	runtime	runtime_view
infrastructure	infrastructure	deployment_view
diagram	diagram	cross_cutting_concepts
concept	concept	cross_cutting_concepts
adr	adr	architecture_decisions
quality_requirement	quality-requirement	quality_requirements
quality_scenario	quality-scenario	quality_requirements
risk	risk	risks_and_technical_debt
glossary_term	glossary-term	glossary

Reading source without exporting

Use read and the JSON commands to inspect the current source state directly:

archledger --json paths
archledger --json status
archledger --json check
archledger --json read --body --include-drafts
archledger --json read --section building_block_view --body
archledger --json read --kind adr --body

--json is a global option. Use archledger --json read ..., not archledger read --json.

read does not call the build pipeline and does not create generated output files.

Tracking implementation drift

Snapshots

archledger --json source snapshot --reason after-archledger-update

snapshot writes .ledger/archledger/data/source-state.json by default. Source-state payloads store SHA-256 content hashes only for files, do not persist mtimes or file sizes, and include a derived directory hash map. If [tracking].enabled = false, snapshot and changed fail explicitly instead of silently creating misleading tracking state.

Changed files

archledger --json source changed
archledger --json source changed --include-drafts

changed reports added, modified, deleted, and possible renamed files plus impacted records and sections linked through source_refs.

Linking source_refs

When fragments document real code or directories, add source_refs:

source_refs:
  - archledger/repository.py#ArchitectureRepository
  - path: archledger/storage/project_config.py
    symbols:
      - ProjectConfig
      - load_project_config
    reason: "Tracking configuration contract"
  - path: archledger/templates/
    reason: "Bundled templates"

Paths must be relative to the workspace root. Directory refs end with / and must point to an existing directory.

Practical drift workflow

archledger --json source changed
archledger --json read --body --include-drafts
# update the affected fragments and their source_refs
archledger --json check
archledger --json source snapshot --reason after-archledger-update

A useful pattern is:

1. Link records to the relevant code or directories with source_refs.
2. Run changed before broad documentation refreshes.
3. Update only the fragments whose refs were impacted.
4. Record a fresh snapshot only after the documentation update is validated.

Building output documents

Native builds

archledger build --format markdown
archledger build --format asciidoc

Converted builds

archledger build --format html
archledger build --format html --format markdown
archledger --json build --format html --format markdown

Tooling matrix

Source format	Output format	Tooling
Markdown	Markdown	none
AsciiDoc	AsciiDoc	none
Markdown	HTML, DOCX, RST, Textile, PDF, AsciiDoc	pandoc
AsciiDoc	HTML	asciidoctor or pandoc
AsciiDoc	PDF	asciidoctor-pdf or pandoc
AsciiDoc	DOCX, Markdown, RST, Textile	asciidoctor + pandoc

Per-output overrides live under [build.outputs.<format>]. Supported keys are tool, pdf_engine, reference_docx, and enabled. Supported tool values are auto, pandoc, and asciidoctor.

Diagram records

Diagram records are plain text by default. Dense architecture diagrams should use diagram_type = "text" or "unicode" so they remain readable in source, Git diffs, terminal output, and native Markdown/AsciiDoc builds. Mermaid remains available for compact diagrams, but it is not the default.

Create first-class diagram records directly:

archledger new diagram "Runtime login flow" --section runtime_view --status proposed
archledger new diagram "Deployment topology" --section deployment_view --caption "Target deployment"
archledger new diagram "Login sequence" --diagram-type mermaid

Supported diagram_type values: text (default), ascii, unicode, svgbob, mermaid.

Native Markdown/AsciiDoc builds preserve text diagram blocks as readable fenced/literal blocks without any external tool. Rendered image materialization for converter-backed formats is optional and disabled by default:

[diagrams]
enabled = true
renderer = "mermaid-cli"  # pass-through | mermaid-cli | asciidoctor-diagram
default_type = "text"
output_dir = "diagrams"
image_format = "svg"
kroki_url = ""

svgbob is a diagram_type, not a renderer. Supported renderer values are pass-through, mermaid-cli, and asciidoctor-diagram. Kroki is not currently accepted by config validation.

Migrating source dialects

source convert is a source migration command, not a general build/export command. It currently supports Markdown-source projects to AsciiDoc-source projects only.

Dry-run the migration first:

archledger source convert --to asciidoc

Write the migration:

archledger source convert --to asciidoc --apply

--apply now requires pandoc by default so the migrated .adoc files and the resulting source.format = "asciidoc" config stay consistent. If you intentionally want a temporary mixed-body migration, use:

archledger source convert --to asciidoc --apply --allow-mixed-body-format

Use this escape hatch only when you explicitly accept a manual cleanup step. Run the command from a clean VCS state.

Configuration reference

Example stable config v11:

config_version = 11

[ledger]
code = "al"
name = "archledger"

[ids]
width = 4

[source]
format = "markdown"

[build]
default_output = "architecture.md"
default_output_dir = "build"

[tracking]
enabled = true
state_file = "source-state.json"

[build].default_output_dir is relative to the project root.

source-state.json stores SHA-256 content hashes only for files. It does not persist mtimes or file sizes. Directory hashes are derived from file hashes.

CLI reference for agents

The canonical command tree is inventory-driven. Prefer these stable forms:

archledger --json storage where
archledger --json record create adr "Architecture decision"
archledger --json record list
archledger --json record show adr-0001
archledger --json record read --body
archledger --json record archive adr-0001 --reason "superseded"
archledger --json migrate plan identity-ledgercore
archledger --json migrate apply identity-ledgercore --reason "approved migration"

The old new, list, show, read, archive, refs, links, paths, and legacy migration paths remain compatibility aliases and emit deprecation warnings. See the generated CLI reference and storage migration guide.

For coding agents, prefer this loop:

1. Run archledger --json paths, archledger --json status, and archledger --json check independently instead of chaining them with &&.
2. If check reports legacy IDs or legacy timestamp metadata, review archledger --json migrate ids --to ledgercore and archledger --json migrate metadata --to versioned dry runs before applying them.
3. Run archledger --json source changed and then archledger --json read --body --include-drafts for broad refreshes, or use narrower context, trace, read --section, or read --kind commands when possible.
4. Edit only source fragments under .ledger/archledger/data/profiles/arc42/sections and .ledger/archledger/data/records.
5. For list or object metadata, use archledger record meta set RECORD_ID KEY --json-value '["item"]'. For option-like string values, use --string-value.
6. Never predict record IDs; capture the returned result.id from archledger --json new ....
7. Run archledger --json check --strict.
8. Run archledger --json source changed --fail-on-unlinked.
9. Build only when the user asks for an exported artifact.
10. Run archledger --json source snapshot --reason after-archledger-update after the docs have been updated and validated.

Archiving and structural repair

Do not delete numbered source fragments. Use:

archledger archive content-0022 --reason "obsolete after content-0041"

Archived records move to .ledger/archledger/data/archive/ and keep their original ID. They are excluded from default read/list/build flows but still reserve their ledger number.

Use:

archledger doctor
archledger doctor --repair
archledger renumber --prefix ta --width 3
archledger renumber --prefix ta --width 3 --apply

doctor --repair can recreate missing required section files, create archive tombstones for missing non-section IDs, and recompute storage.yaml.next_number without renumbering existing records.

Development

Run the standard checks:

python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy archledger
python -m sphinx -b html docs docs/_build/html

Release-oriented checks:

rm -rf dist build *.egg-info
python -m build
python -m twine check dist/*
python -m venv /tmp/archledger-wheel-test
/tmp/archledger-wheel-test/bin/python -m pip install dist/*.whl
/tmp/archledger-wheel-test/bin/archledger --version

For the full maintainer checklist, see docs/release-process.md.

Troubleshooting

Symptom	Cause	Fix
No Ledgercore project found	Command ran outside a configured workspace.	Run from the project tree or pass --root.
Draft records missing from builds	Drafts are excluded by default.	Use --include-drafts or promote the record status.
Build blocked by warnings	--strict treats warnings as failures.	Fix the warnings or build without --strict.
Converter executable not found	Requested output needs pandoc, asciidoctor, or asciidoctor-pdf.	Install the required tool or change the per-output converter config.
source changed says no baseline found	No source snapshot exists yet.	Run archledger --json source snapshot --reason after-archledger-update after the docs are current.
snapshot or changed says tracking is disabled	[tracking].enabled = false.	Re-enable tracking or avoid tracking commands for that workspace.
source convert --apply fails without pandoc	Apply mode is strict by default.	Install pandoc or re-run with --allow-mixed-body-format if you accept a manual cleanup step.
check reports missing ledger IDs	Numbered fragments were deleted or moved manually.	Use archledger archive for lifecycle removal and archledger doctor --repair for safe structural repair.

Skill

The repository-provided coding-agent protocol lives at skills/archledger/SKILL.md.

Security and trust

archledger reads local project files and only invokes external converters when you request output formats that need them. It does not sync or send project content anywhere by itself.

Traceability boundary

Archledger stores architecture data and generic references only. If a record links to an external artifact, Archledger preserves the reference without interpreting external domain semantics.