# in03/snapper architecture

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

- Interactive diagram: https://gitdiagram.com/in03/snapper
- Repository: https://github.com/in03/snapper

## Overview

##### Project type and purpose
- Snapper is an open-source Python command‐line utility for DaVinci Resolve that automates “snapshot” (versioned timeline) creation.
- It’s not a web or full-stack app—it’s a CLI tool that calls Resolve’s local Python scripting API and performs file‐system operations.

##### File structure
- Top level: configuration for packaging (pyproject.toml), docs (mkdocs.yml, assets), CI (GitHub Actions), pre‐commit, license, README.
- snapper/ directory contains the runtime code:
- cli.py – entry point & command definitions (uses Click)
- utils.py – core logic (interacting with Resolve, file/directory operations)
- No database or network services—primary external dependency is the local DaVinci Resolve process.

##### README for insights
- Clearly describes the “new” command workflow:
- Duplicate active timeline via Resolve API
- Rename to next version number
- In an “@Snapshots” subfolder
- Dependencies: Python ≥3.10, Click, Resolve Python API, installed via pipx or Poetry.

##### Main components
a. User / Shell
b. Snapper CLI (Click command dispatcher)
c. Snapper Core module (utils.py)
d. DaVinci Resolve local scripting API (external process)
e. File system (project folders, “@Snapshots” subfolders)
f. Optional: logging subsystem (console output, debug messages)

##### Relationships & data flow
1) User runs `snapper new` in their shell.
2) Click (cli.py) parses the command and forwards it to the core logic.
3) Core logic (utils) queries Resolve API for the active timeline.
4) Core logic invokes Resolve API to duplicate & rename the timeline.
5) Core logic performs file‐system operations: create/@Snapshots folder and move or write the new timeline object there.
6) Snapper logs success/failure back to the console.

##### Architectural patterns & design principles
- Layered CLI architecture:
1) Presentation layer (Click in cli.py)
2) Domain layer (core timeline snapshot logic in utils.py)
3) External integration layer (Resolve API, file system)
- Separation of concerns: CLI vs business logic vs external bindings.
- Single‐responsibility modules: one module for commands, one for utilities.

##### Relevant technologies & libraries
- Python 3.10+
- Click (CLI parsing)
- DaVinci Resolve Python scripting API (hosted by Resolve Studio)
- pipx / Poetry (packaging & distribution)
- Pre‐commit & github actions (CI/CD)

##### Detailed capture of architectural elements
- That assets (mkdocs) produce documentation but are orthogonal to runtime.

- Clearly delineates Snapper’s CLI presentation, business logic, and external integrations
- Scales easily if additional commands or integrations are added in the future

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interaction
    User["User / Shell"]:::user

    %% Snapper CLI Layer
    subgraph "Snapper CLI Layer"
        Init["Package Init\n(__init__.py)"]:::internal
        CLI["CLI Dispatcher\n(cli.py)"]:::internal
    end

    %% Snapper Domain Layer
    subgraph "Snapper Domain Layer"
        Core["Core Logic\n(utils.py)"]:::internal
    end

    %% External Integration Layer
    subgraph "External Integration"
        Resolve["DaVinci Resolve API"]:::external
        FS["File System"]:::external
    end

    %% Logging
    Log["Logging Subsystem\n(console output)"]:::internal

    %% Deployment & CI
    subgraph "Deployment & CI"
        Pkg["pyproject.toml"]:::config
        DocCfg["mkdocs.yml"]:::config
        DocAssets["assets/"]:::config
        CI[".github/workflows/"]:::config
    end

    %% Data Flow
    User -->|"snapper new"| CLI
    CLI -->|"invoke snapshot()"| Core
    Core -->|"duplicateTimeline()"| Resolve
    Resolve -->|"timeline Object"| Core
    Core -->|"writeSnapshot()"| FS
    Core -->|"logOutput"| Log
    Log -->|"console"| User

    %% Optional relations
    Core -.->|uses| Init
    CLI -.->|packaged by| Pkg
    CLI -.->|docs config| DocCfg
    CLI -.->|docs assets| DocAssets
    Init -.->|CI/CD setup| CI

    %% Click Events
    click CLI "https://github.com/in03/snapper/blob/main/snapper/cli.py"
    click Core "https://github.com/in03/snapper/blob/main/snapper/utils.py"
    click Init "https://github.com/in03/snapper/blob/main/snapper/__init__.py"
    click Pkg "https://github.com/in03/snapper/blob/main/pyproject.toml"
    click DocCfg "https://github.com/in03/snapper/blob/main/mkdocs.yml"
    click DocAssets "https://github.com/in03/snapper/tree/main/assets/"
    click CI "https://github.com/in03/snapper/tree/main/.github/workflows/"

    %% Styling
    classDef internal fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef user fill:#F2F3F4,stroke:#BDC3C7,color:#566573;
    classDef config fill:#FCF3CF,stroke:#D4AC0D,color:#7D6608;
```
