# syntax-read3r/powerflow architecture

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

- Interactive diagram: https://gitdiagram.com/syntax-read3r/powerflow
- Repository: https://github.com/syntax-read3r/powerflow

## Overview

1. **What this repo is**
   PowerFlow is a PowerShell profile distribution: a bootstrapping layer that dot-sources a set of feature modules to turn an interactive shell into a command hub for navigation, Git, file operations, terminal control, and self-updating behavior.

2. **Primary runtime boundary**
   The main runtime is PowerShell 5.1+ on Windows, with Windows Terminal as the intended host. The profile is designed to load at shell startup, then expose aliases/functions that replace or augment standard shell commands. A smaller Ubuntu/Linux adaptation exists under `ubuntu/`, but the core architecture is Windows/PowerShell-first.

3. **Startup and composition model**
   The repo is organized around `Microsoft.PowerShell_profile.ps1` plus `components/` and `config/`. The profile acts as a loader: it imports configuration, core behavior, shared helpers, then feature modules. This makes the shell profile behave like a plugin system rather than a monolith.

4. **Configuration layer**
   `config/PowerFlow.settings.ps1` and `config/PowerFlow.paths.ps1` hold versioning, feature flags, paths, and runtime settings. This separates user/environment-specific behavior from feature code. The README also documents toggles for dependency checks and update checks, indicating config is the main control plane for enabling/disabling subsystems.

5. **Core subsystem**
   `components/core/` contains the foundational lifecycle logic: dependency checks, recovery, and version handling. This is the lowest-level business logic layer because other modules depend on it for safe startup, upgrade behavior, and compatibility checks.

6. **Feature domains**
   The feature surface is split by domain:
   - `components/navigation/` for bookmarks, directory jumping, project search, and `nav`
   - `components/files/` for cut/paste, listing, rename, clipboard-style file workflows
   - `components/git/` for branch management, commit/release, remote actions, rollback, and interactive history/status
   - `components/github/` for GitHub repository browsing and token-backed access
   - `components/terminal/` for tab handling and WSL-related terminal actions
   - `components/help/` for the command/menu help system
   - `components/system/` for config/path/shutdown helpers
   - `components/projects/` for project creation helpers
   - `components/shared/` for aliases and string utilities used across modules

7. **Cross-cutting helpers**
   `components/shared/` holds low-level reuse points like aliases and string utilities, while the `IMPORT_ORDER.md` file suggests load ordering matters. That implies there is deliberate dependency layering: shared helpers first, then core, then feature modules that build on those helpers and on one another.

8. **Data flow for interactive commands**
   Most user-facing commands follow the same pattern: inspect current shell state, present an `fzf`-based selector or prompt, perform the action, then update shell-visible state. Examples include navigation/bookmark selection, Git branch/log/status views, file rename/move flows, and release bump selection. The main data flow is from filesystem/Git state → interactive picker/UI → shell action → optional persistence to config or Git metadata.

9. **External tool dependencies**
   The architecture depends on external CLI tools installed and managed automatically: `starship` for prompt rendering, `fzf` for interactive selection, `zoxide` for learned navigation, `lsd` for rich listings, Git for VCS operations, and a Nerd Font for icon rendering. These are not just conveniences; they are part of the feature runtime and shape how each subsystem is implemented.

10. **Installation and lifecycle management**
   `install.ps1` and `uninstall.ps1` are the top-level lifecycle entrypoints for getting PowerFlow into or out of a machine. Installation is responsible for dependency setup, font setup, bookmark initialization, and update configuration. The repo also includes Ubuntu install/uninstall scripts to support a secondary environment with similar goals but different shell integration.

11. **Release and update pipeline**
   The release flow is split between in-shell commands and GitHub Actions. In-shell, `git-rl` updates the version in config, commits, tags, and pushes. In CI, the `.github/workflows/` release pipeline validates the profile, generates install scripts, bundles artifacts, publishes GitHub releases, and sends notifications. This creates a clear boundary between local authoring/release intent and automated distribution.

12. **Documentation as part of the architecture**
   The `docs/` tree is substantial and mirrors the product structure: installation, features, troubleshooting, integration notes, and historical planning/logs. For architecture purposes, the docs function as the contract for command behavior, release expectations, and environment assumptions.

13. **Operational safety and recovery**
   Safety is built into the design: backups before updates, rollback branches for Git operations, confirmation prompts for destructive actions, and recovery logic in core startup/update flows. This suggests PowerFlow treats shell customizations as stateful and potentially risky, so resilience is a first-class concern.

14. **How to diagram it**
   A good architecture diagram should show: user shell session at the center; startup loader/config feeding feature modules; feature modules grouped by domain; external CLI tools as dependencies; GitHub Actions as the release/distribution pipeline; and installation scripts as the machine bootstrap/uninstall boundary. The main structural idea is “profile-as-platform” with modular command domains layered over shared core services.

Main entry points: [`Microsoft.PowerShell_profile.ps1`](https://github.com/syntax-read3r/powerflow/blob/main/Microsoft.PowerShell_profile.ps1) (Profile loader), [`components/git`](https://github.com/syntax-read3r/powerflow/tree/main/components/git) (Git tools), [`docs`](https://github.com/syntax-read3r/powerflow/tree/main/docs) (Docs), [`install.ps1`](https://github.com/syntax-read3r/powerflow/blob/main/install.ps1) (Install scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_n_profile["Profile loader<br/>ps1 entrypoint"]
  node_n_shell(("Shell session<br/>interactive runtime"))
end

subgraph group_g_features["Feature modules"]
  node_n_nav["Navigation<br/>command domain"]
  node_n_files["Files<br/>command domain"]
  node_n_git["Git tools<br/>command domain"]
  node_n_github["GitHub<br/>command domain"]
  node_n_terminal["Terminal<br/>command domain"]
  node_n_help["Help menu<br/>command domain"]
  node_n_system["System<br/>command domain"]
  node_n_projects["Projects<br/>command domain"]
end

subgraph group_g_support["Support"]
  node_n_settings["Settings<br/>config"]
  node_n_paths["Paths<br/>config"]
  node_n_shared["Shared helpers<br/>common module"]
  node_n_core["Core lifecycle<br/>startup core"]
  node_n_external[("External tools<br/>runtime deps")]
  node_n_docs["Docs<br/>documentation"]
end

subgraph group_g_delivery["Delivery"]
  node_n_install["Install scripts<br/>machine bootstrap<br/>[install.ps1]"]
  node_n_uninstall["Uninstall script<br/>machine teardown<br/>[uninstall.ps1]"]
  node_n_release["Release pipeline<br/>ci workflow<br/>[release.yml]"]
end

node_n_profile -->|"loads"| node_n_settings
node_n_profile -->|"loads"| node_n_paths
node_n_profile -->|"loads"| node_n_shared
node_n_profile -->|"loads"| node_n_core
node_n_profile -->|"loads"| node_n_nav
node_n_profile -->|"loads"| node_n_files
node_n_profile -->|"loads"| node_n_git
node_n_profile -->|"loads"| node_n_github
node_n_profile -->|"loads"| node_n_terminal
node_n_profile -->|"loads"| node_n_help
node_n_profile -->|"loads"| node_n_system
node_n_profile -->|"loads"| node_n_projects
node_n_profile -->|"starts in"| node_n_shell
node_n_core -->|"checks"| node_n_external
node_n_nav -->|"uses"| node_n_external
node_n_files -->|"uses"| node_n_external
node_n_git -->|"uses"| node_n_external
node_n_github -->|"uses"| node_n_external
node_n_terminal -->|"uses"| node_n_external
node_n_system -->|"reads"| node_n_settings
node_n_system -->|"reads"| node_n_paths
node_n_git -->|"depends on"| node_n_core
node_n_nav -->|"depends on"| node_n_shared
node_n_files -->|"depends on"| node_n_shared
node_n_git -->|"depends on"| node_n_shared
node_n_install -->|"installs"| node_n_external
node_n_install -->|"configures"| node_n_settings
node_n_uninstall -.->|"reverses"| node_n_install
node_n_release -->|"bumps"| node_n_settings
node_n_release -.->|"publishes"| node_n_docs
node_n_docs -.->|"describes"| node_n_profile
node_n_docs -.->|"describes"| node_n_install
node_n_docs -.->|"describes"| node_n_release

click node_n_profile "https://github.com/syntax-read3r/powerflow/blob/main/Microsoft.PowerShell_profile.ps1"
click node_n_settings "https://github.com/syntax-read3r/powerflow/blob/main/config/PowerFlow.settings.ps1"
click node_n_paths "https://github.com/syntax-read3r/powerflow/blob/main/config/PowerFlow.paths.ps1"
click node_n_shared "https://github.com/syntax-read3r/powerflow/tree/main/components/shared"
click node_n_core "https://github.com/syntax-read3r/powerflow/tree/main/components/core"
click node_n_nav "https://github.com/syntax-read3r/powerflow/tree/main/components/navigation"
click node_n_files "https://github.com/syntax-read3r/powerflow/tree/main/components/files"
click node_n_git "https://github.com/syntax-read3r/powerflow/tree/main/components/git"
click node_n_github "https://github.com/syntax-read3r/powerflow/tree/main/components/github"
click node_n_terminal "https://github.com/syntax-read3r/powerflow/tree/main/components/terminal"
click node_n_help "https://github.com/syntax-read3r/powerflow/tree/main/components/help"
click node_n_system "https://github.com/syntax-read3r/powerflow/tree/main/components/system"
click node_n_projects "https://github.com/syntax-read3r/powerflow/tree/main/components/projects"
click node_n_install "https://github.com/syntax-read3r/powerflow/blob/main/install.ps1"
click node_n_uninstall "https://github.com/syntax-read3r/powerflow/blob/main/uninstall.ps1"
click node_n_release "https://github.com/syntax-read3r/powerflow/blob/main/.github/workflows/release.yml"
click node_n_docs "https://github.com/syntax-read3r/powerflow/tree/main/docs"

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_n_profile,node_n_shell toneBlue
class node_n_nav,node_n_files,node_n_git,node_n_github,node_n_terminal,node_n_help,node_n_system,node_n_projects toneAmber
class node_n_settings,node_n_paths,node_n_shared,node_n_core,node_n_external,node_n_docs toneMint
class node_n_install,node_n_uninstall,node_n_release toneRose
```

## Components

### Runtime

Interactive shell session and startup composition

- [Profile loader](https://github.com/syntax-read3r/powerflow/blob/main/Microsoft.PowerShell_profile.ps1): ps1 entrypoint · Bootstraps the shell by dot-sourcing config, core, shared helpers, and feature modules. · `Microsoft.PowerShell_profile.ps1`
- **Shell session**: interactive runtime · Windows PowerShell interactive environment where commands, aliases, and state live.

### Feature modules

Command domains loaded into the profile

- [Navigation](https://github.com/syntax-read3r/powerflow/tree/main/components/navigation): command domain · Bookmarks, directory jumping, project search, and nav commands. · `components/navigation`
- [Files](https://github.com/syntax-read3r/powerflow/tree/main/components/files): command domain · Clipboard-style file workflows, listings, moves, and renames. · `components/files`
- [Git tools](https://github.com/syntax-read3r/powerflow/tree/main/components/git): command domain · Branch, commit, remote, reset, rollback, and release workflows. · `components/git`
- [GitHub](https://github.com/syntax-read3r/powerflow/tree/main/components/github): command domain · Repository browsing and token-backed GitHub access. · `components/github`
- [Terminal](https://github.com/syntax-read3r/powerflow/tree/main/components/terminal): command domain · Tab management and WSL-related terminal actions. · `components/terminal`
- [Help menu](https://github.com/syntax-read3r/powerflow/tree/main/components/help): command domain · Command discovery and menu-driven help. · `components/help`
- [System](https://github.com/syntax-read3r/powerflow/tree/main/components/system): command domain · Config files, path utilities, and shutdown helpers. · `components/system`
- [Projects](https://github.com/syntax-read3r/powerflow/tree/main/components/projects): command domain · Project creation helpers, including next-style scaffolding. · `components/projects`

### Support

Config, shared helpers, docs, and external dependencies

- [Settings](https://github.com/syntax-read3r/powerflow/blob/main/config/PowerFlow.settings.ps1): config · Versioning, feature flags, and runtime toggles. · `config/PowerFlow.settings.ps1`
- [Paths](https://github.com/syntax-read3r/powerflow/blob/main/config/PowerFlow.paths.ps1): config · Path definitions and environment-specific locations. · `config/PowerFlow.paths.ps1`
- [Shared helpers](https://github.com/syntax-read3r/powerflow/tree/main/components/shared): common module · Aliases and string utilities reused across modules. · `components/shared`
- [Core lifecycle](https://github.com/syntax-read3r/powerflow/tree/main/components/core): startup core · Dependency checks, recovery, and version handling for safe startup and updates. · `components/core`
- **External tools**: runtime deps · Starship, fzf, zoxide, lsd, Git, WSL, and Nerd Font dependencies used by the feature runtime.
- [Docs](https://github.com/syntax-read3r/powerflow/tree/main/docs): documentation · Feature, installation, troubleshooting, planning, and operational guidance. · `docs`

### Delivery

Install, uninstall, and release automation

- [Install scripts](https://github.com/syntax-read3r/powerflow/blob/main/install.ps1): machine bootstrap · Installs or removes PowerFlow and sets up dependencies, fonts, and bookmarks. · `install.ps1`
- [Uninstall script](https://github.com/syntax-read3r/powerflow/blob/main/uninstall.ps1): machine teardown · Removes PowerFlow from the machine. · `uninstall.ps1`
- [Release pipeline](https://github.com/syntax-read3r/powerflow/blob/main/.github/workflows/release.yml): ci workflow · Validates, bundles, publishes, and notifies for releases. · `.github/workflows/release.yml`

## Connections

- Profile loader → Settings: loads · Imports runtime configuration before feature modules.
- Profile loader → Paths: loads · Resolves repository and environment paths.
- Profile loader → Shared helpers: loads · Dot-sources shared helpers early.
- Profile loader → Core lifecycle: loads · Initializes lifecycle checks and recovery logic.
- Profile loader → Navigation: loads · Composes navigation commands into the shell.
- Profile loader → Files: loads · Composes file workflows into the shell.
- Profile loader → Git tools: loads · Composes Git workflows into the shell.
- Profile loader → GitHub: loads · Composes GitHub workflows into the shell.
- Profile loader → Terminal: loads · Adds terminal control features.
- Profile loader → Help menu: loads · Adds command discovery and help menus.
- Profile loader → System: loads · Adds system-level helper commands.
- Profile loader → Projects: loads · Adds project scaffolding commands.
- Profile loader → Shell session: starts in · Profile initializes the interactive session.
- Core lifecycle → External tools: checks · Verifies and relies on external command availability.
- Navigation → External tools: uses · Uses fuzzy pickers and navigation helpers.
- Files → External tools: uses · Uses interactive selection and rich listings.
- Git tools → External tools: uses · Uses Git and interactive selection tooling.
- GitHub → External tools: uses · Uses GitHub and interactive selection tooling.
- Terminal → External tools: uses · Uses terminal host capabilities and WSL integration.
- System → Settings: reads · Consumes config-driven behavior and toggles.
- System → Paths: reads · Uses path configuration for environment actions.
- Git tools → Core lifecycle: depends on · Relies on core startup safety and versioning.
- Navigation → Shared helpers: depends on · Reuses aliases and string helpers.
- Files → Shared helpers: depends on · Reuses shared helper functions.
- Git tools → Shared helpers: depends on · Reuses shared helper functions.
- Install scripts → External tools: installs · Sets up toolchain dependencies and fonts.
- Install scripts → Settings: configures · Initializes machine and feature configuration.
- Uninstall script → Install scripts: reverses · Provides the teardown path for installation.
- Release pipeline → Settings: bumps · Updates version/config for release flow.
- Release pipeline → Docs: publishes · Release artifacts and guidance are documented and generated from the repo.
- Docs → Profile loader: describes · Documents profile startup and command behavior.
- Docs → Install scripts: describes · Documents installation and environment setup.
- Docs → Release pipeline: describes · Documents release and operational procedures.
