# ninoseki/uv-dynamic-versioning architecture

> Architecture diagram of the GitHub repository ninoseki/uv-dynamic-versioning, 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/ninoseki/uv-dynamic-versioning
- Repository: https://github.com/ninoseki/uv-dynamic-versioning

## Overview

To accurately represent the architecture of **uv-dynamic-versioning**, we will break down the system into its core components, show their interactions, and highlight how this plugin-based Python package integrates into the `uv`/`hatch` build pipeline and with the VCS (Git). Follow these steps:

##### Main Components
a. **CLI Entrypoint (`uv-dynamic-versioning` script)**
b. **Core Library Modules (in `src/uv_dynamic_versioning/`)**
- `main.py` / `cli.py`: argument parsing & command dispatch
- `base.py`: common base classes & utilities
- `version_source.py`: logic to compute version from VCS (via `dunamai`)
- `metadata_hook.py`: logic to dynamically adjust package metadata
- `template.py`: Jinja-based formatting of version strings
- `schemas.py`: pydantic models for configuration validation
- `hooks.py`: registration of plugins with `uv`/`hatchling`
c. **External Systems**
- **Git (VCS)**: source of truth for tags/commits
- **`uv`/`hatchling` Build Backend**: invokes version source & metadata hook
- **PyPI (or other package index)**: ultimate consumer of built artifacts
d. **Examples & Documentation** (not part of runtime but useful for context)
- `examples/` demonstrating usage of both plugins
- `docs/` for version-source & metadata-hook design details

##### Relationships & Data Flows
a. **Build Invocation**
- User runs `uv build` (or `pip wheel`, etc.) → `hatchling.build` → plugin hooks
b. **Version Source Plugin Flow**
1. `hatchling` calls the version-source hook (registered via `hooks.py`)
2. `version_source.py` uses `dunamai` to examine local Git history
3. Computed version string flows back into the build metadata
c. **Metadata Hook Plugin Flow**
1. After version is set, `hatchling` calls the metadata-hook
2. `metadata_hook.py` reads configured patterns / monorepo layout
3. Dynamically adjusts `dependencies` / `optional-dependencies`
4. Returns modified metadata to build backend
d. **CLI Utility**
- Offers a standalone `uv-dynamic-versioning` command (via `main.py`) for manual tasks (e.g., printing version, debugging templates)

##### Architectural Patterns & Principles
- **Plugin Pattern**: registration via entry points (`hooks.py` → `pyproject.toml`)
- **Separation of Concerns**: distinct modules for version computation, templating, schema validation, and hook registration
- **Configuration Validation**: pydantic schemas ensure correct user input
- **Template-Driven Output**: Jinja templates for maximum flexibility

##### Essential Elements to Capture
- Plugin registration via `hooks.py` & `pyproject.toml` entry points
- `dunamai` integration for VCS interrogation
- Runtime sequence: Build Backend invokes hooks in order
- Configuration schemas that drive both plugins

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    subgraph "CLI Utility"
        Main["main.py"]:::internal
        CLI["cli.py"]:::internal
    end
    User -->|"run uv-dynamic-versioning"| Main
    Main -->|delegates to| CLI

    %% Build Process
    User -->|"run uv build / pip wheel"| BuildBackend["hatchling (Build Backend)"]:::external
    subgraph "uv-dynamic-versioning Core"
        Hooks["hooks.py"]:::internal
        VersionSource["version_source.py"]:::internal
        MetadataHook["metadata_hook.py"]:::internal
        Template["template.py"]:::internal
        Schemas["schemas.py"]:::internal
        Base["base.py"]:::internal
    end

    %% Plugin Registration
    BuildBackend -->|"load plugins via entry-points"| Hooks
    Hooks -->|"register version-source hook"| VersionSource
    Hooks -->|"register metadata-hook"| MetadataHook

    %% Version Source Flow
    BuildBackend -->|"invoke version-source"| VersionSource
    VersionSource -->|"uses dunamai"| Dunamai["dunamai"]:::external
    Dunamai -->|"inspects history"| Git["Git (VCS)"]:::external
    VersionSource -->|"return version string"| BuildBackend

    %% Metadata Hook Flow
    BuildBackend -->|"invoke metadata-hook"| MetadataHook
    MetadataHook -->|"validate config"| Schemas
    MetadataHook -->|"format patterns"| Template
    MetadataHook -->|"adjust dependencies"| BuildBackend

    %% Artifact Production
    BuildBackend -->|"produce artifact"| Artifact["Built Package"]:::internal
    Artifact -->|"publish"| PyPI["PyPI"]:::external

    %% Examples & Docs
    subgraph "Examples"
        ExampleVS["examples/version-source/"]:::external
        ExampleMH["examples/metadata-hook/"]:::external
    end
    subgraph "Documentation"
        DocVS["docs/version_source.md"]:::external
        DocMH["docs/metadata_hook.md"]:::external
        DocTips["docs/tips.md"]:::external
    end
    ExampleVS --> User
    ExampleMH --> User
    DocVS --> User
    DocMH --> User
    DocTips --> User

    %% Click Events
    click Main "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/main.py"
    click CLI "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/cli.py"
    click Hooks "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/hooks.py"
    click VersionSource "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/version_source.py"
    click MetadataHook "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/metadata_hook.py"
    click Base "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/base.py"
    click Template "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/template.py"
    click Schemas "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/src/uv_dynamic_versioning/schemas.py"
    click Pyproject "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/pyproject.toml"
    click ExampleVS "https://github.com/ninoseki/uv-dynamic-versioning/tree/main/examples/version-source/"
    click ExampleMH "https://github.com/ninoseki/uv-dynamic-versioning/tree/main/examples/metadata-hook/"
    click DocVS "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/docs/version_source.md"
    click DocMH "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/docs/metadata_hook.md"
    click DocTips "https://github.com/ninoseki/uv-dynamic-versioning/blob/main/docs/tips.md"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#145A32,color:#145A32;
```
