# dob9601/jointhedots architecture

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

- Interactive diagram: https://gitdiagram.com/dob9601/jointhedots
- Repository: https://github.com/dob9601/jointhedots

## Overview

1. **What this repo is**
   - `jointhedots` is a single Rust CLI binary for managing dotfiles from a Git repository.
   - There is no server component; the architecture centers on local filesystem operations plus Git operations against a remote repo.

2. **Top-level entry points**
   - `src/main.rs` is the executable entry.
   - `src/cli.rs` defines the command-line interface and dispatches to the subcommands.
   - `src/lib.rs` exposes the reusable application logic shared by the binary and internal modules.

3. **Primary user workflows**
   - The CLI exposes three core paths: `install`, `interactive`, and `sync`.
   - `install` applies a manifest-driven dotfile repo onto the user’s machine.
   - `interactive` is the same install pipeline with user selection/prompting layered on top.
   - `sync` pushes local dotfile changes back into the repository and reconciles with Git.

4. **Manifest-driven configuration**
   - The repo expects a `jtd.yaml` manifest in the root of a dotfile repository.
   - `src/structs/manifest.rs` and `src/structs/dotfile.rs` model the manifest entries: source file, target path, and optional install hooks.
   - `src/structs/config.rs` represents global behavior such as commit prefix and squash behavior.

5. **Install-step and state model**
   - The manifest can include `pre_install` and `post_install` shell commands, so install is not just file copying; it is a controlled execution pipeline.
   - `src/structs/metadata.rs` likely stores install-state metadata, including hashes of install steps so they only rerun when the manifest changes.
   - This creates a durable boundary between “declared desired state” in the manifest and “what has already been applied” on the host.

6. **Filesystem side of the architecture**
   - Install operations map repo files into user destinations such as `~/.config/...`.
   - The core filesystem boundary is between the checked-out dotfile repository and the user’s home directory.
   - Utility code in `src/utils.rs` likely handles path resolution, command execution, and shared filesystem helpers.

7. **Git subsystem**
   - `src/git/operations.rs` and `src/git/remote.rs` isolate Git-specific behavior from the rest of the app.
   - This layer is responsible for repo state checks, committing, merging/syncing, and pushing or pulling to a remote.
   - The rest of the application talks to this module rather than dealing with Git details directly.

8. **Install and sync data flow**
   - `install` starts by loading and validating the manifest, checking whether the repo is ahead/behind where relevant, then executing install hooks and placing files.
   - `sync` flows in the opposite direction: detect local file changes, turn them into Git commits, and push them to the configured remote.
   - The README implies sync behavior is deterministic and can be non-interactive for scripting.

9. **Interactive mode**
   - `src/subcommands/interactive.rs` adds a user-choice layer over the same underlying install engine.
   - It is not a separate subsystem; it is a UI wrapper that narrows which dotfiles are processed.

10. **Validation and schema support**
   - `src/dotfile_schema.json` provides JSON Schema for editor support and manifest validation.
   - `src/jtd-wrapper.sh` suggests a bootstrap/wrapper path used for one-line installation or execution packaging.
   - These are support artifacts around the manifest contract rather than runtime business logic.

11. **Logging and observability**
   - `src/log.rs` centralizes logging behavior for CLI output.
   - This is important because the app performs multi-step operations with external side effects: file writes, shell commands, and Git changes.

12. **Architecture boundaries to draw**
   - Draw three main boundaries: the **CLI/front end**, the **dotfile domain + install/sync engine**, and the **Git/filesystem side effects**.
   - Persistent inputs/outputs are: `jtd.yaml`, installed metadata, user home files, and the remote Git repository.
   - The repo is essentially a deterministic orchestration layer that translates manifest state into local installs and Git-backed synchronization.

Main entry points: [`src/subcommands/install.rs`](https://github.com/dob9601/jointhedots/blob/master/src/subcommands/install.rs) (Install), [`src/subcommands/sync.rs`](https://github.com/dob9601/jointhedots/blob/master/src/subcommands/sync.rs) (Sync), [`src/structs/manifest.rs`](https://github.com/dob9601/jointhedots/blob/master/src/structs/manifest.rs) (Manifest), [`src/lib.rs`](https://github.com/dob9601/jointhedots/blob/master/src/lib.rs) (Lib)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["CLI Front End"]
  node_main(("Main<br/>binary entry<br/>[main.rs]"))
  node_cli["CLI<br/>arg router<br/>[cli.rs]"]
  node_interactive["Interactive<br/>subcommand<br/>[interactive.rs]"]
end

subgraph group_domain["Dotfile Domain"]
  node_install["Install<br/>subcommand<br/>[install.rs]"]
  node_sync["Sync<br/>subcommand<br/>[sync.rs]"]
  node_lib["Lib<br/>shared core<br/>[lib.rs]"]
  node_manifest["Manifest<br/>jtd.yaml model<br/>[manifest.rs]"]
  node_dotfile["Dotfile<br/>entry model<br/>[dotfile.rs]"]
  node_config["Config<br/>global settings<br/>[config.rs]"]
  node_metadata["Metadata<br/>state record<br/>[metadata.rs]"]
  node_utils{{"Utils<br/>fs/process helpers<br/>[utils.rs]"}}
end

subgraph group_git["Git Layer"]
  node_gitops["Git Ops<br/>git orchestration<br/>[operations.rs]"]
  node_remote["Remote<br/>[remote.rs]"]
end

subgraph group_support["Support Artifacts"]
  node_log{{"Logging<br/>[log.rs]"}}
  node_schema["Schema"]
  node_wrapper["Wrapper<br/>bootstrap script<br/>[jtd-wrapper.sh]"]
end

node_main -->|"starts"| node_cli
node_cli -->|"dispatches"| node_install
node_cli -->|"dispatches"| node_interactive
node_cli -->|"dispatches"| node_sync
node_interactive -->|"wraps"| node_install
node_install -->|"loads"| node_manifest
node_install -->|"applies"| node_dotfile
node_install -->|"updates"| node_metadata
node_install -->|"reads"| node_config
node_install -->|"uses"| node_utils
node_install -->|"checks"| node_gitops
node_sync -->|"commits"| node_gitops
node_sync -->|"pushes"| node_remote
node_sync -->|"uses"| node_utils
node_sync -->|"tracks"| node_dotfile
node_manifest -->|"contains"| node_dotfile
node_manifest -->|"includes"| node_config
node_manifest -.->|"drives"| node_metadata
node_gitops -->|"uses"| node_remote
node_log -->|"observes"| node_install
node_log -->|"observes"| node_sync
node_schema -.->|"validates"| node_manifest
node_wrapper -.->|"boots"| node_main
node_lib -->|"exports"| node_install
node_lib -->|"exports"| node_sync
node_lib -->|"reuses"| node_gitops
node_lib -->|"reuses"| node_utils

click node_main "https://github.com/dob9601/jointhedots/blob/master/src/main.rs"
click node_cli "https://github.com/dob9601/jointhedots/blob/master/src/cli.rs"
click node_install "https://github.com/dob9601/jointhedots/blob/master/src/subcommands/install.rs"
click node_interactive "https://github.com/dob9601/jointhedots/blob/master/src/subcommands/interactive.rs"
click node_sync "https://github.com/dob9601/jointhedots/blob/master/src/subcommands/sync.rs"
click node_lib "https://github.com/dob9601/jointhedots/blob/master/src/lib.rs"
click node_manifest "https://github.com/dob9601/jointhedots/blob/master/src/structs/manifest.rs"
click node_dotfile "https://github.com/dob9601/jointhedots/blob/master/src/structs/dotfile.rs"
click node_config "https://github.com/dob9601/jointhedots/blob/master/src/structs/config.rs"
click node_metadata "https://github.com/dob9601/jointhedots/blob/master/src/structs/metadata.rs"
click node_utils "https://github.com/dob9601/jointhedots/blob/master/src/utils.rs"
click node_gitops "https://github.com/dob9601/jointhedots/blob/master/src/git/operations.rs"
click node_remote "https://github.com/dob9601/jointhedots/blob/master/src/git/remote.rs"
click node_log "https://github.com/dob9601/jointhedots/blob/master/src/log.rs"
click node_schema "https://github.com/dob9601/jointhedots/blob/master/src/dotfile_schema.json"
click node_wrapper "https://github.com/dob9601/jointhedots/blob/master/src/jtd-wrapper.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_interactive toneBlue
class node_install,node_sync,node_lib,node_manifest,node_dotfile,node_config,node_metadata,node_utils toneAmber
class node_gitops,node_remote toneMint
class node_log,node_schema,node_wrapper toneRose
```

## Components

### CLI Front End

Command entrypoints and user-facing subcommands.

- [Main](https://github.com/dob9601/jointhedots/blob/master/src/main.rs): binary entry · Executable entrypoint. · `src/main.rs`
- [CLI](https://github.com/dob9601/jointhedots/blob/master/src/cli.rs): arg router · Parses commands and dispatches subcommands. · `src/cli.rs`
- [Interactive](https://github.com/dob9601/jointhedots/blob/master/src/subcommands/interactive.rs): subcommand · Interactive selection layered over install. · `src/subcommands/interactive.rs`

### Dotfile Domain

Manifest-driven install and sync orchestration.

- [Install](https://github.com/dob9601/jointhedots/blob/master/src/subcommands/install.rs): subcommand · Applies manifest-defined dotfiles and hooks. · `src/subcommands/install.rs`
- [Sync](https://github.com/dob9601/jointhedots/blob/master/src/subcommands/sync.rs): subcommand · Reconciles local changes back into Git. · `src/subcommands/sync.rs`
- [Lib](https://github.com/dob9601/jointhedots/blob/master/src/lib.rs): shared core · Reusable application logic for the binary and modules. · `src/lib.rs`
- [Manifest](https://github.com/dob9601/jointhedots/blob/master/src/structs/manifest.rs): jtd.yaml model · Repository manifest describing dotfiles and hooks. · `src/structs/manifest.rs`
- [Dotfile](https://github.com/dob9601/jointhedots/blob/master/src/structs/dotfile.rs): entry model · Represents a source file, target path, and install hooks. · `src/structs/dotfile.rs`
- [Config](https://github.com/dob9601/jointhedots/blob/master/src/structs/config.rs): global settings · Global behavior such as commit prefix and squash settings. · `src/structs/config.rs`
- [Metadata](https://github.com/dob9601/jointhedots/blob/master/src/structs/metadata.rs): state record · Tracks applied install state and step hashes. · `src/structs/metadata.rs`
- [Utils](https://github.com/dob9601/jointhedots/blob/master/src/utils.rs): fs/process helpers · Shared helpers for paths, execution, and filesystem work. · `src/utils.rs`

### Git Layer

Git-specific operations and remote handling.

- [Git Ops](https://github.com/dob9601/jointhedots/blob/master/src/git/operations.rs): git orchestration · Repo checks, commits, merges, sync, and push/pull flow. · `src/git/operations.rs`
- [Remote](https://github.com/dob9601/jointhedots/blob/master/src/git/remote.rs): git remote · Remote repository configuration and interaction. · `src/git/remote.rs`

### Support Artifacts

Schema, wrapper, and logging support around the main flows.

- [Logging](https://github.com/dob9601/jointhedots/blob/master/src/log.rs): cli logging · Centralized logging for multi-step side effects. · `src/log.rs`
- [Schema](https://github.com/dob9601/jointhedots/blob/master/src/dotfile_schema.json): json schema · Manifest schema for validation and editor support. · `src/dotfile_schema.json`
- [Wrapper](https://github.com/dob9601/jointhedots/blob/master/src/jtd-wrapper.sh): bootstrap script · Shell wrapper used for packaging or one-line execution. · `src/jtd-wrapper.sh`

## Connections

- Main → CLI: starts · Binary enters through CLI parsing and dispatch.
- CLI → Install: dispatches · Routes the install command.
- CLI → Interactive: dispatches · Routes the interactive command.
- CLI → Sync: dispatches · Routes the sync command.
- Interactive → Install: wraps · Interactive mode reuses the install pipeline.
- Install → Manifest: loads · Install begins by reading the manifest.
- Install → Dotfile: applies · Uses dotfile entries to place files and hooks.
- Install → Metadata: updates · Persists install state and step hashes.
- Install → Config: reads · Uses global behavior settings.
- Install → Utils: uses · Relies on shared filesystem and process helpers.
- Install → Git Ops: checks · May inspect repository state before applying changes.
- Sync → Git Ops: commits · Turns local changes into git operations.
- Sync → Remote: pushes · Synchronizes with the configured remote.
- Sync → Utils: uses · Shares path and filesystem helpers.
- Sync → Dotfile: tracks · Uses dotfile definitions when reconciling changes.
- Manifest → Dotfile: contains · Manifest is composed of dotfile entries.
- Manifest → Config: includes · Manifest references global behavior settings.
- Manifest → Metadata: drives · Manifest changes influence applied-state metadata.
- Git Ops → Remote: uses · Git operations are isolated from remote handling.
- Logging → Install: observes · Logs the install pipeline.
- Logging → Sync: observes · Logs the sync pipeline.
- Schema → Manifest: validates · Schema supports manifest validation and editor tooling.
- Wrapper → Main: boots · Wrapper script can launch the CLI entrypoint.
- Lib → Install: exports · Shared core exposes install logic to the binary.
- Lib → Sync: exports · Shared core exposes sync logic to the binary.
- Lib → Git Ops: reuses · Centralizes Git access through shared application logic.
- Lib → Utils: reuses · Shares common helpers across modules.