# mtkennerly/dunamai architecture

> Architecture diagram of the GitHub repository mtkennerly/dunamai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mtkennerly/dunamai
- Repository: https://github.com/mtkennerly/dunamai

## Overview

##### Project type and purpose
- Dunamai is a Python-based library and command-line tool (CLI) whose sole concern is to generate dynamic, VCS-derived version strings.
- It’s not a web or full-stack application but an open-source, reusable tool focused on version discovery via Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, and Pijul.
- The README emphasizes both a programmatic API (`Version.from_*` calls) and a user-facing CLI (`dunamai from …`, `dunamai check …`), plus optional CI and build-system integrations (GitHub Action, Poetry plugin, setuptools).

##### File structure
- Top level
- Configuration & CI: `.github/`, `.flake8`, `pyproject.toml`, `tasks.py`, `mkdocs.yaml`, workflows, and docs.
- Core code: `dunamai/` package with `__main__.py`, `__init__.py`, `py.typed`.
- Documentation: `docs/` plus `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`.
- Tests: `tests/unit/`, `tests/integration/`, `tests/archival/` (archived‐repo fixtures).
- Patterns
- A clear separation of concerns: CLI entrypoint vs. library API vs. VCS adapters vs. formatting logic.
- No web server or persistence beyond reading the local repo or archival files.

##### README for additional insights
- Architecture is implied, not drawn:
- A version‐detection core that “auto-detects” or selects a VCS backend.
- Adapters for multiple VCSs, each encapsulating how to read tags, commits, metadata.
- A `Version` class with discrete parts and a `serialize()` engine that applies PEP 440, SemVer, Haskell PVP, or custom formats.
- Integration hooks (setup.py, Poetry, environment variables) and a GitHub Action.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Architecture"
        direction TB
        subgraph "CLI Layer"
            direction TB
            CLI["CLI Entrypoint"]:::cli
        end
        subgraph "Library Core" 
            direction TB
            Core["Version Core\n(Version class)"]:::core
            PyTyped["Type Stub Marker\n(py.typed)"]:::core
            Serializer["Serializer/\nFormatter"]:::core
        end
        subgraph "VCS Adapter Layer"
            direction TB
            Git["Git Adapter"]:::adapter
            HG["Mercurial Adapter"]:::adapter
            Darcs["Darcs Adapter"]:::adapter
            SVN["Subversion Adapter"]:::adapter
            Bazaar["Bazaar Adapter"]:::adapter
            Fossil["Fossil Adapter"]:::adapter
            Pijul["Pijul Adapter"]:::adapter
        end
        ExternalRepo["Local VCS Repo\nor Archive Files"]:::external
        Consumer["Consumer Integration\n(CLI stdout or API)"]:::external

        CLI -->|"invoke CLI commands"| Core
        Core -->|"construct Version object"| Serializer
        Core -->|"use adapter"| Git
        Core -->|"use adapter"| HG
        Core -->|"use adapter"| Darcs
        Core -->|"use adapter"| SVN
        Core -->|"use adapter"| Bazaar
        Core -->|"use adapter"| Fossil
        Core -->|"use adapter"| Pijul
        Git -->|"read tags/commits"| ExternalRepo
        HG -->|"read tags/commits"| ExternalRepo
        Darcs -->|"read metadata"| ExternalRepo
        SVN -->|"read metadata"| ExternalRepo
        Bazaar -->|"read metadata"| ExternalRepo
        Fossil -->|"read metadata"| ExternalRepo
        Pijul -->|"read metadata"| ExternalRepo
        Serializer -->|"return formatted string"| Consumer
        CLI -->|"print version"| Consumer
        Consumer -->|"direct API call"| Core
        Core -->|"load type hints"| PyTyped
    end

    subgraph "Development & QA" 
        direction TB
        subgraph "Documentation"
            MkDocsCfg["MkDocs Config\n(mkdocs.yaml)"]:::dev
            DocsSource["Docs Source\n(docs/index.md,\n[dunamai.1], docs/requirements.txt)"]:::dev
        end
        subgraph "Testing"
            UnitCore["Unit Tests\n(test_dunamai.py)"]:::dev
            UnitCLI["Unit CLI Tests\n(test_main.py)"]:::dev
            Integration["Integration Tests\n(test_dunamai.py)"]:::dev
            subgraph "Archival Fixtures"
                direction TB
                GitTagged["Git Tagged Fixtures\n(.git_archival.json)"]:::dev
                GitTaggedPost["Git Tagged Post Fixtures\n(.git_archival.json)"]:::dev
                GitUntagged["Git Untagged Fixtures\n(.git_archival.json)"]:::dev
                HgTagged["Hg Tagged Fixtures\n(.hg_archival.txt,\n.hgtags)"]:::dev
                HgUntagged["Hg Untagged Fixtures\n(.hg_archival.txt)"]:::dev
            end
        end
        CI["CI Workflow\n(.github/workflows/main.yaml)"]:::dev
        BuildConfig["pyproject.toml"]:::dev
        Tasks["Development Tasks\n(tasks.py)"]:::dev
        Configs["Lint & Formatting\n(.flake8, .editorconfig,\n.pre-commit-config.yaml,\n.coveragerc)"]:::dev
        GitAttr["VCS Filters\n(.gitignore,\n.gitattributes)"]:::dev
        MetaDocs["Project Docs\n(README.md,\nCHANGELOG.md,\nCONTRIBUTING.md)"]:::dev
    end

    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef dev fill:#fff3cd,stroke:#856404,color:#856404;

    click CLI "https://github.com/mtkennerly/dunamai/blob/master/dunamai/__main__.py"
    click Core "https://github.com/mtkennerly/dunamai/blob/master/dunamai/__init__.py"
    click PyTyped "https://github.com/mtkennerly/dunamai/blob/master/dunamai/py.typed"
    click GitTagged "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/git-tagged/.git_archival.json"
    click GitTaggedPost "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/git-tagged-post/.git_archival.json"
    click GitUntagged "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/git-untagged/.git_archival.json"
    click HgTagged "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/hg-tagged/.hg_archival.txt"
    click HgTagged "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/hg-tagged/.hgtags"
    click HgUntagged "https://github.com/mtkennerly/dunamai/blob/master/tests/archival/hg-untagged/.hg_archival.txt"
    click UnitCore "https://github.com/mtkennerly/dunamai/blob/master/tests/unit/test_dunamai.py"
    click UnitCLI "https://github.com/mtkennerly/dunamai/blob/master/tests/unit/test_main.py"
    click Integration "https://github.com/mtkennerly/dunamai/blob/master/tests/integration/test_dunamai.py"
    click CI "https://github.com/mtkennerly/dunamai/blob/master/.github/workflows/main.yaml"
    click BuildConfig "https://github.com/mtkennerly/dunamai/blob/master/pyproject.toml"
    click Tasks "https://github.com/mtkennerly/dunamai/blob/master/tasks.py"
    click MkDocsCfg "https://github.com/mtkennerly/dunamai/blob/master/mkdocs.yaml"
    click DocsSource "https://github.com/mtkennerly/dunamai/blob/master/docs/index.md"
    click MetaDocs "https://github.com/mtkennerly/dunamai/blob/master/README.md"
    click Configs "https://github.com/mtkennerly/dunamai/blob/master/.flake8"
    click GitAttr "https://github.com/mtkennerly/dunamai/blob/master/.gitignore"
```
