# timmo001/dotfiles architecture

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

- Interactive diagram: https://gitdiagram.com/timmo001/dotfiles
- Repository: https://github.com/timmo001/dotfiles

## Overview

The product is a personal Omarchy dotfiles environment managed by the `dot` command. Its central user workflow is first-use initialization, followed by health checks and recurring updates/stow; the CLI also exposes GitHub-backed repository workflows, dependency automation, skills, and service management. The graph emphasizes documented command dispatch and the sampled runtime entry points. Several command internals are unsampled, so their connections are shown only where the CLI specification documents dispatch.

Main entry points: [`dot/src/cli/spec.ts`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/cli/spec.ts) (Command specification), [`dot/src/index.ts`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/index.ts) (CLI runtime), [`dot/src/commands/Services.ts`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Services.ts) (Service status), [`dot/src/commands/Init.ts`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Init.ts) (First-use setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_cli["Command specification<br/>[spec.ts]"]
  node_runtime["CLI runtime<br/>[index.ts]"]
  node_init["First-use setup<br/>[Init.ts]"]
  node_bootstrap["Private clone bootstrap"]
end

subgraph group_machine["Machine management"]
  node_doctor["Health checks<br/>[Doctor.ts]"]
  node_checks["Doctor checks"]
  node_update["Dotfiles update<br/>[Update.ts]"]
  node_systemupdate["System updates<br/>[SystemUpdate.ts]"]
  node_stow["Stow management<br/>[Stow.ts]"]
  node_services["Service status<br/>[Services.ts]"]
end

subgraph group_git["Git workflows"]
  node_gitcommands["Git commands"]
  node_gitservices["Git services"]
  node_reviews["Review helpers"]
end

subgraph group_automation["Automation"]
  node_depscommand["Dependency command<br/>[Dependencies.ts]"]
  node_deps["Dependency automation"]
  node_skills["Skills commands<br/>[Skills.ts]"]
  node_mcp["MCP synchronization"]
  node_herdragents["Herdr integrations<br/>[HerdrAgents.ts]"]
end

node_user(("Terminal user"))
node_systemd["systemd user services"]
node_github["GitHub"]

node_user -->|"invokes"| node_runtime
node_runtime -->|"resolves command"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_doctor
node_cli -->|"dispatches"| node_update
node_cli -->|"dispatches"| node_systemupdate
node_cli -->|"dispatches"| node_stow
node_cli -->|"dispatches"| node_services
node_cli -->|"dispatches"| node_gitcommands
node_cli -->|"dispatches"| node_depscommand
node_cli -->|"dispatches"| node_skills
node_cli -->|"dispatches"| node_mcp
node_init -->|"clones overlay"| node_bootstrap
node_doctor -->|"runs checks"| node_checks
node_services -->|"queries units"| node_systemd
node_services -->|"opens logs via"| node_runtime
node_gitcommands -->|"uses services"| node_gitservices
node_gitservices -->|"requests data"| node_github
node_reviews -->|"queries GraphQL"| node_github
node_depscommand -->|"runs automation"| node_deps
node_deps -->|"reads repository data"| node_github
node_herdragents -->|"executes status command"| node_runtime

click node_cli "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/cli/spec.ts"
click node_runtime "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/index.ts"
click node_init "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Init.ts"
click node_doctor "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Doctor.ts"
click node_checks "https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/doctor/checks"
click node_update "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Update.ts"
click node_systemupdate "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/SystemUpdate.ts"
click node_stow "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Stow.ts"
click node_services "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Services.ts"
click node_gitcommands "https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/git/commands"
click node_gitservices "https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/git/services"
click node_reviews "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/lib/pullRequestReviews.ts"
click node_depscommand "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Dependencies.ts"
click node_deps "https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/deps"
click node_skills "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Skills.ts"
click node_mcp "https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/mcp/sync"
click node_herdragents "https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/HerdrAgents.ts"

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_cli,node_runtime,node_init,node_bootstrap,node_user,node_systemd toneBlue
class node_doctor,node_checks,node_update,node_systemupdate,node_stow,node_services toneAmber
class node_gitcommands,node_gitservices,node_reviews toneMint
class node_depscommand,node_deps,node_skills,node_mcp,node_herdragents toneRose
class node_github toneIndigo
```

## Components

### CLI and setup

- [Command specification](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/cli/spec.ts): `dot/src/cli/spec.ts`
- [CLI runtime](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/index.ts): `dot/src/index.ts`
- [First-use setup](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Init.ts): `dot/src/commands/Init.ts`
- **Private clone bootstrap**

### Machine management

- [Health checks](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Doctor.ts): `dot/src/commands/Doctor.ts`
- [Doctor checks](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/doctor/checks): `dot/src/doctor/checks`
- [Dotfiles update](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Update.ts): `dot/src/commands/Update.ts`
- [System updates](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/SystemUpdate.ts): `dot/src/commands/SystemUpdate.ts`
- [Stow management](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Stow.ts): `dot/src/commands/Stow.ts`
- [Service status](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Services.ts): `dot/src/commands/Services.ts`

### Git workflows

- [Git commands](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/git/commands): `dot/src/git/commands`
- [Git services](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/git/services): `dot/src/git/services`
- [Review helpers](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/lib/pullRequestReviews.ts): `dot/src/lib/pullRequestReviews.ts`

### Automation

- [Dependency command](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Dependencies.ts): `dot/src/commands/Dependencies.ts`
- [Dependency automation](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/deps): `dot/src/deps`
- [Skills commands](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/Skills.ts): `dot/src/commands/Skills.ts`
- [MCP synchronization](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro/dot/src/mcp/sync): `dot/src/mcp/sync`
- [Herdr integrations](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/dot/src/commands/HerdrAgents.ts): `dot/src/commands/HerdrAgents.ts`

### Other components

- **Terminal user**
- **systemd user services**
- **GitHub**

## Connections

- Terminal user → CLI runtime: invokes
- CLI runtime → Command specification: resolves command
- Command specification → First-use setup: dispatches
- Command specification → Health checks: dispatches
- Command specification → Dotfiles update: dispatches
- Command specification → System updates: dispatches
- Command specification → Stow management: dispatches
- Command specification → Service status: dispatches
- Command specification → Git commands: dispatches
- Command specification → Dependency command: dispatches
- Command specification → Skills commands: dispatches
- Command specification → MCP synchronization: dispatches
- First-use setup → Private clone bootstrap: clones overlay
- Health checks → Doctor checks: runs checks
- Service status → systemd user services: queries units
- Service status → CLI runtime: opens logs via
- Git commands → Git services: uses services
- Git services → GitHub: requests data
- Review helpers → GitHub: queries GraphQL
- Dependency command → Dependency automation: runs automation
- Dependency automation → GitHub: reads repository data
- Herdr integrations → CLI runtime: executes status command