# denisdefreyne/ddenv architecture

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

- Interactive diagram: https://gitdiagram.com/denisdefreyne/ddenv
- Repository: https://github.com/denisdefreyne/ddenv

## Overview

##### Main components
- CLI Entrypoint (cmd/ddenv/main.go)
- Configuration Loader (ddenv.yaml parser)
- Core Orchestration Engine (core/core.go)
- Goal Handlers (goals/*.go)
- Homebrew Submodule (homebrew/main.go)
- External Systems & Services (Homebrew, Shell, Version Managers, Databases, Redis, Shadowenv)

##### Relationships and data flow
a. User Types `ddenv` → CLI Entrypoint
b. CLI Entrypoint → reads `ddenv.yaml` via Configuration Loader
c. Configuration Loader → produces an ordered list of “goal” specifications
d. Core Orchestration Engine → iterates the list, for each goal:
- Instantiates corresponding Goal Handler from the goals package
- Injects any shared dependencies (e.g. logger, file system, environment)
e. Each Goal Handler → executes domain logic:
- Calls Homebrew submodule for brew-related goals
- Invokes external tools (ruby-install, nodenv or node-build, psql, redis-server)
- Manipulates Shadowenv (directory creation, .gitignore patching, env file writes)
f. Goal Handler → returns status and any exported environment variables
g. Core Engine → aggregates results and prints progress in the CLI

##### Architectural patterns
- Plugin-style pattern: each “goal” is a self-contained handler implementing a common interface (e.g. Goal interface in core)
- Dependency injection: shared services (logger, file system, shell executor) passed into each handler
- Single responsibility: cmd handles CLI parsing, core orchestrates workflow, goals contain domain logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    UserShell["User / Shell"]:::external
    CLI["ddenv CLI\n(cmd/ddenv/main.go)"]:::internal
    UserShell -->|"invokes"| CLI

    %% Configuration Loader
    Config["Config Loader\n(core/core.go)"]:::internal
    CLI -->|"reads ddenv.yaml"| Config

    %% Core Orchestrator
    Core["Core Orchestrator\n(core/core.go)"]:::internal
    Config -->|"produces goal specs"| Core

    %% Goals Cluster
    subgraph "Goal Handlers (goals/*.go)"
        direction TB
        HB["Homebrew Package Handler\n(goals/homebrew_package_installed.go)"]:::plugin
        Ruby1["Ruby Installed\n(goals/ruby_installed.go)"]:::plugin
        Ruby2["Ruby Setup\n(goals/ruby_set_up.go)"]:::plugin
        Ruby3["Ruby Shadowenv Created\n(goals/ruby_shadowenv_created.go)"]:::plugin
        Node1["Node Installed\n(goals/node_installed.go)"]:::plugin
        Node2["Node Setup\n(goals/node_set_up.go)"]:::plugin
        Node3["Node Shadowenv Created\n(goals/node_shadowenv_created.go)"]:::plugin
        Node4["npm Packages Installed\n(goals/npm_packages_installed.go)"]:::plugin
        Node5["pnpm Packages Installed\n(goals/pnpm_packages_installed.go)"]:::plugin
        Node6["yarn Packages Installed\n(goals/yarn_packages_installed.go)"]:::plugin
        PG1["PostgreSQL Setup\n(goals/postgresql_set_up.go)"]:::plugin
        PG2["PostgreSQL Shadowenv Created\n(goals/postgresql_shadowenv_created.go)"]:::plugin
        PG3["PostgreSQL Started\n(goals/postgresql_started.go)"]:::plugin
        Red1["Redis Setup\n(goals/redis_set_up.go)"]:::plugin
        Red2["Redis Shadowenv Created\n(goals/redis_shadowenv_created.go)"]:::plugin
        Red3["Redis Started\n(goals/redis_started.go)"]:::plugin
        SE1["Shadowenv Dir Created\n(goals/shadowenv_dir_created.go)"]:::plugin
        SE2["Shadowenv Gitignored\n(goals/shadowenv_dir_git_ignored.go)"]:::plugin
        SE3["Shadowenv Initialized\n(goals/shadowenv_initialized.go)"]:::plugin
        SE4["Shadowenv Setup\n(goals/shadowenv_set_up.go)"]:::plugin
        SE5["Shadowenv Trusted\n(goals/shadowenv_trusted.go)"]:::plugin
    end

    Core -->|instantiates| HB
    Core -->|instantiates| Ruby1
    Core -->|instantiates| Ruby2
    Core -->|instantiates| Ruby3
    Core -->|instantiates| Node1
    Core -->|instantiates| Node2
    Core -->|instantiates| Node3
    Core -->|instantiates| Node4
    Core -->|instantiates| Node5
    Core -->|instantiates| Node6
    Core -->|instantiates| PG1
    Core -->|instantiates| PG2
    Core -->|instantiates| PG3
    Core -->|instantiates| Red1
    Core -->|instantiates| Red2
    Core -->|instantiates| Red3
    Core -->|instantiates| SE1
    Core -->|instantiates| SE2
    Core -->|instantiates| SE3
    Core -->|instantiates| SE4
    Core -->|instantiates| SE5

    %% Homebrew Submodule
    HomebrewModule["Homebrew Module\n(homebrew/main.go)"]:::internal
    HB -->|"calls brew API"| HomebrewModule

    %% External Systems
    BrewCLI["Homebrew CLI"]:::external
    Shell["Shell / OS"]:::external
    RubyVM["Ruby Version Manager"]:::external
    NodeVM["Node Version Manager"]:::external
    NpmYarn["npm / pnpm / yarn"]:::external
    PGServer["PostgreSQL Server"]:::external
    RedisServer["Redis Server"]:::external
    ShadowFS["Shadowenv FS"]:::external

    HomebrewModule -->|"executes brew"| BrewCLI
    Ruby1 -->|"executes ruby-install"| RubyVM
    Ruby2 -->|"executes ruby-install"| RubyVM
    Ruby3 -->|"patches Shadowenv"| ShadowFS
    Node1 -->|"executes node-build"| NodeVM
    Node2 -->|"executes node-build"| NodeVM
    Node3 -->|"patches Shadowenv"| ShadowFS
    Node4 -->|"executes npm"| NpmYarn
    Node5 -->|"executes pnpm"| NpmYarn
    Node6 -->|"executes yarn"| NpmYarn
    PG1 -->|"executes psql"| PGServer
    PG2 -->|"patches Shadowenv"| ShadowFS
    PG3 -->|"starts postgres"| PGServer
    Red1 -->|"executes redis-server"| RedisServer
    Red2 -->|"patches Shadowenv"| ShadowFS
    Red3 -->|"starts redis"| RedisServer
    SE1 -->|"creates dir"| ShadowFS
    SE2 -->|"gitignore dir"| ShadowFS
    SE3 -->|"initializes"| ShadowFS
    SE4 -->|"sets up"| ShadowFS
    SE5 -->|"trusts"| ShadowFS

    %% Feedback
    BrewCLI -->|status/env| Core
    RubyVM -->|status/env| Core
    NodeVM -->|status/env| Core
    NpmYarn -->|status/env| Core
    PGServer -->|status/env| Core
    RedisServer -->|status/env| Core
    ShadowFS -->|status/env| Core

    Core -->|prints results| CLI

    %% Click events
    click CLI "https://github.com/denisdefreyne/ddenv/blob/main/cmd/ddenv/main.go"
    click Config "https://github.com/denisdefreyne/ddenv/blob/main/core/core.go"
    click Core "https://github.com/denisdefreyne/ddenv/blob/main/core/core.go"
    click HB "https://github.com/denisdefreyne/ddenv/blob/main/goals/homebrew_package_installed.go"
    click Ruby1 "https://github.com/denisdefreyne/ddenv/blob/main/goals/ruby_installed.go"
    click Ruby2 "https://github.com/denisdefreyne/ddenv/blob/main/goals/ruby_set_up.go"
    click Ruby3 "https://github.com/denisdefreyne/ddenv/blob/main/goals/ruby_shadowenv_created.go"
    click Node1 "https://github.com/denisdefreyne/ddenv/blob/main/goals/node_installed.go"
    click Node2 "https://github.com/denisdefreyne/ddenv/blob/main/goals/node_set_up.go"
    click Node3 "https://github.com/denisdefreyne/ddenv/blob/main/goals/node_shadowenv_created.go"
    click Node4 "https://github.com/denisdefreyne/ddenv/blob/main/goals/npm_packages_installed.go"
    click Node5 "https://github.com/denisdefreyne/ddenv/blob/main/goals/pnpm_packages_installed.go"
    click Node6 "https://github.com/denisdefreyne/ddenv/blob/main/goals/yarn_packages_installed.go"
    click PG1 "https://github.com/denisdefreyne/ddenv/blob/main/goals/postgresql_set_up.go"
    click PG2 "https://github.com/denisdefreyne/ddenv/blob/main/goals/postgresql_shadowenv_created.go"
    click PG3 "https://github.com/denisdefreyne/ddenv/blob/main/goals/postgresql_started.go"
    click Red1 "https://github.com/denisdefreyne/ddenv/blob/main/goals/redis_set_up.go"
    click Red2 "https://github.com/denisdefreyne/ddenv/blob/main/goals/redis_shadowenv_created.go"
    click Red3 "https://github.com/denisdefreyne/ddenv/blob/main/goals/redis_started.go"
    click SE1 "https://github.com/denisdefreyne/ddenv/blob/main/goals/shadowenv_dir_created.go"
    click SE2 "https://github.com/denisdefreyne/ddenv/blob/main/goals/shadowenv_dir_git_ignored.go"
    click SE3 "https://github.com/denisdefreyne/ddenv/blob/main/goals/shadowenv_initialized.go"
    click SE4 "https://github.com/denisdefreyne/ddenv/blob/main/goals/shadowenv_set_up.go"
    click SE5 "https://github.com/denisdefreyne/ddenv/blob/main/goals/shadowenv_trusted.go"
    click HomebrewModule "https://github.com/denisdefreyne/ddenv/blob/main/homebrew/main.go"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef plugin fill:#E3F2FD,stroke-dasharray: 5 5,stroke:#1976D2,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px
```
