# izzyflestado/gitzy architecture

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

- Interactive diagram: https://gitdiagram.com/izzyflestado/gitzy
- Repository: https://github.com/izzyflestado/gitzy

## Overview

Gitzy is a macOS menu-bar app for managing saved Git repositories, viewing GitHub contribution data, and displaying the active editor’s branch in a floating widget. The main user flow starts at the menu-bar popover: users browse projects and GitHub data, or open settings; project and editor state also drives the widget and global shortcuts. The graph includes the documented capabilities and sampled runtime layers. Some feature implementations were not excerpted, so their links rely on README statements rather than claims about unsampled calls.

Main entry points: [`Gitzy/Features/Projects/ProjectStore.swift`](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Projects/ProjectStore.swift) (Saved projects), [`Gitzy/Features/BranchWidget/BranchWidgetController.swift`](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/BranchWidgetController.swift) (Widget controller), [`Gitzy/Features/Contributions/ContributionStore.swift`](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Contributions/ContributionStore.swift) (GitHub data state), [`Gitzy/Features/MenuBar/MenuBarController.swift`](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/MenuBar/MenuBarController.swift) (Menu bar popover)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_app["App startup<br/>[AppDelegate.swift]"]
  node_menubar["Menu bar popover"]
  node_popover["Popover tabs"]
end

subgraph group_projects["Projects"]
  node_projectstore["Saved projects<br/>[ProjectStore.swift]"]
  node_projectviews["Project browsing"]
  node_scanner["Folder repository scan"]
  node_windowopener["Project launching<br/>[WindowOpener.swift]"]
end

subgraph group_widget["Branch widget"]
  node_widgetcontroller["Widget controller"]
  node_widgetview["Floating branch display"]
  node_visibility["App-based visibility"]
end

subgraph group_github["GitHub contributions"]
  node_contributionstore["GitHub data state"]
  node_contributionviews["Contribution and activity views"]
end

subgraph group_controls["Settings and shortcuts"]
  node_settingswindow["Settings window"]
  node_settingsview["Settings controls<br/>[SettingsView.swift]"]
  node_shortcuts["Global shortcuts"]
end

subgraph group_runtime["Runtime services and models"]
  node_appsettings[("Preferences<br/>[AppSettings.swift]")]
  node_gitrepo["Repository status"]
  node_gitremote["Git remote parsing<br/>[GitRemote.swift]"]
  node_windowstate["Visible window snapshot"]
  node_githubservice["GitHub API client"]
  node_githubparser["Contribution parsing<br/>[GitHubParser.swift]"]
  node_activityparser["Activity parsing"]
  node_tokenfile[("Private token file<br/>[TokenFile.swift]")]
end

node_user(("User"))
node_github(("GitHub API"))

node_user -->|"opens menu"| node_menubar
node_menubar -->|"shows"| node_popover
node_menubar -->|"refreshes projects"| node_projectstore
node_menubar -->|"refreshes data"| node_contributionstore
node_app -->|"creates"| node_projectstore
node_app -->|"creates"| node_contributionstore
node_app -->|"creates"| node_widgetcontroller
node_app -->|"creates"| node_menubar
node_popover -->|"opens settings"| node_settingswindow
node_popover -->|"shows projects"| node_projectviews
node_popover -->|"shows GitHub tab"| node_contributionviews
node_user -->|"adds and sorts"| node_projectstore
node_projectstore -->|"scans folders"| node_scanner
node_projectstore -->|"reads status"| node_gitrepo
node_gitrepo -->|"reads remote"| node_gitremote
node_user -->|"opens project"| node_windowopener
node_user -->|"presses keys"| node_shortcuts
node_shortcuts -->|"selects saved project"| node_projectstore
node_user -->|"configures widget"| node_widgetcontroller
node_widgetcontroller -->|"matches saved project"| node_projectstore
node_widgetcontroller -->|"reads branch"| node_gitrepo
node_widgetcontroller -->|"builds display"| node_widgetview
node_widgetcontroller -->|"checks visibility"| node_visibility
node_visibility -->|"checks windows"| node_windowstate
node_user -->|"opens settings"| node_settingswindow
node_settingswindow -->|"hosts controls"| node_settingsview
node_user -->|"connects account"| node_contributionstore
node_contributionstore -->|"loads token"| node_tokenfile
node_contributionstore -->|"requests data"| node_githubservice
node_githubservice -->|"sends GraphQL"| node_github
node_githubservice -->|"parses response"| node_githubparser
node_githubservice -->|"parses activity"| node_activityparser
node_contributionstore -->|"supplies display data"| node_contributionviews
node_settingsview -.->|"configures preferences"| node_appsettings

click node_app "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/App/AppDelegate.swift"
click node_menubar "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/MenuBar/MenuBarController.swift"
click node_popover "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/MenuBar/PopoverRootView.swift"
click node_settingswindow "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Settings/SettingsWindowController.swift"
click node_settingsview "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Settings/SettingsView.swift"
click node_appsettings "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Models/AppSettings.swift"
click node_projectstore "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Projects/ProjectStore.swift"
click node_projectviews "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Projects/ProjectRowView.swift"
click node_scanner "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/ProjectScanner.swift"
click node_gitrepo "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitRepositoryService.swift"
click node_gitremote "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitRemote.swift"
click node_windowopener "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/WindowOpener.swift"
click node_shortcuts "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Shortcuts/ShortcutController.swift"
click node_widgetcontroller "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/BranchWidgetController.swift"
click node_widgetview "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/BranchWidgetView.swift"
click node_visibility "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/AppVisibilityMonitor.swift"
click node_windowstate "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/WindowSnapshot.swift"
click node_contributionstore "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Contributions/ContributionStore.swift"
click node_contributionviews "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Contributions/ContributionGraphView.swift"
click node_githubservice "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitHubService.swift"
click node_githubparser "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitHubParser.swift"
click node_activityparser "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/ActivityParser.swift"
click node_tokenfile "https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/TokenFile.swift"

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_app,node_menubar,node_popover,node_user toneBlue
class node_projectstore,node_projectviews,node_scanner,node_windowopener toneAmber
class node_widgetcontroller,node_widgetview,node_visibility,node_github toneMint
class node_contributionstore,node_contributionviews toneRose
class node_settingswindow,node_settingsview,node_shortcuts toneIndigo
class node_appsettings,node_gitrepo,node_gitremote,node_windowstate,node_githubservice,node_githubparser,node_activityparser,node_tokenfile toneTeal
```

## Components

### App shell

- [App startup](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/App/AppDelegate.swift): `Gitzy/App/AppDelegate.swift`
- [Menu bar popover](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/MenuBar/MenuBarController.swift): `Gitzy/Features/MenuBar/MenuBarController.swift`
- [Popover tabs](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/MenuBar/PopoverRootView.swift): `Gitzy/Features/MenuBar/PopoverRootView.swift`

### Projects

- [Saved projects](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Projects/ProjectStore.swift): `Gitzy/Features/Projects/ProjectStore.swift`
- [Project browsing](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Projects/ProjectRowView.swift): `Gitzy/Features/Projects/ProjectRowView.swift`
- [Folder repository scan](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/ProjectScanner.swift): `Gitzy/Services/ProjectScanner.swift`
- [Project launching](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/WindowOpener.swift): `Gitzy/Services/WindowOpener.swift`

### Branch widget

- [Widget controller](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/BranchWidgetController.swift): `Gitzy/Features/BranchWidget/BranchWidgetController.swift`
- [Floating branch display](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/BranchWidgetView.swift): `Gitzy/Features/BranchWidget/BranchWidgetView.swift`
- [App-based visibility](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/BranchWidget/AppVisibilityMonitor.swift): `Gitzy/Features/BranchWidget/AppVisibilityMonitor.swift`

### GitHub contributions

- [GitHub data state](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Contributions/ContributionStore.swift): `Gitzy/Features/Contributions/ContributionStore.swift`
- [Contribution and activity views](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Contributions/ContributionGraphView.swift): `Gitzy/Features/Contributions/ContributionGraphView.swift`

### Settings and shortcuts

- [Settings window](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Settings/SettingsWindowController.swift): `Gitzy/Features/Settings/SettingsWindowController.swift`
- [Settings controls](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Settings/SettingsView.swift): `Gitzy/Features/Settings/SettingsView.swift`
- [Global shortcuts](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Features/Shortcuts/ShortcutController.swift): `Gitzy/Features/Shortcuts/ShortcutController.swift`

### Runtime services and models

- [Preferences](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Models/AppSettings.swift): `Gitzy/Models/AppSettings.swift`
- [Repository status](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitRepositoryService.swift): `Gitzy/Services/GitRepositoryService.swift`
- [Git remote parsing](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitRemote.swift): `Gitzy/Services/GitRemote.swift`
- [Visible window snapshot](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/WindowSnapshot.swift): `Gitzy/Services/WindowSnapshot.swift`
- [GitHub API client](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitHubService.swift): `Gitzy/Services/GitHubService.swift`
- [Contribution parsing](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/GitHubParser.swift): `Gitzy/Services/GitHubParser.swift`
- [Activity parsing](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/ActivityParser.swift): `Gitzy/Services/ActivityParser.swift`
- [Private token file](https://github.com/izzyflestado/gitzy/blob/main/Gitzy/Services/TokenFile.swift): `Gitzy/Services/TokenFile.swift`

### Other components

- **User**
- **GitHub API**

## Connections

- User → Menu bar popover: opens menu
- Menu bar popover → Popover tabs: shows (evidence: `Gitzy/Features/MenuBar/MenuBarController.swift`)
- Menu bar popover → Saved projects: refreshes projects (evidence: `Gitzy/Features/MenuBar/MenuBarController.swift`)
- Menu bar popover → GitHub data state: refreshes data (evidence: `Gitzy/Features/MenuBar/MenuBarController.swift`)
- App startup → Saved projects: creates (evidence: `Gitzy/App/AppDelegate.swift`)
- App startup → GitHub data state: creates (evidence: `Gitzy/App/AppDelegate.swift`)
- App startup → Widget controller: creates (evidence: `Gitzy/App/AppDelegate.swift`)
- App startup → Menu bar popover: creates (evidence: `Gitzy/App/AppDelegate.swift`)
- Popover tabs → Settings window: opens settings (evidence: `Gitzy/Features/MenuBar/MenuBarController.swift`)
- Popover tabs → Project browsing: shows projects
- Popover tabs → Contribution and activity views: shows GitHub tab
- User → Saved projects: adds and sorts
- Saved projects → Folder repository scan: scans folders (evidence: `Gitzy/Features/Projects/ProjectStore.swift`)
- Saved projects → Repository status: reads status (evidence: `Gitzy/Features/Projects/ProjectStore.swift`)
- Repository status → Git remote parsing: reads remote (evidence: `Gitzy/Services/GitRepositoryService.swift`)
- User → Project launching: opens project
- User → Global shortcuts: presses keys
- Global shortcuts → Saved projects: selects saved project (evidence: `Gitzy/Features/Shortcuts/ShortcutController.swift`)
- User → Widget controller: configures widget
- Widget controller → Saved projects: matches saved project (evidence: `Gitzy/Features/BranchWidget/BranchWidgetController.swift`)
- Widget controller → Repository status: reads branch (evidence: `Gitzy/Features/BranchWidget/BranchWidgetController.swift`)
- Widget controller → Floating branch display: builds display (evidence: `Gitzy/Features/BranchWidget/BranchWidgetController.swift`)
- Widget controller → App-based visibility: checks visibility (evidence: `Gitzy/Features/BranchWidget/BranchWidgetController.swift`)
- App-based visibility → Visible window snapshot: checks windows (evidence: `Gitzy/Features/BranchWidget/AppVisibilityMonitor.swift`)
- User → Settings window: opens settings
- Settings window → Settings controls: hosts controls (evidence: `Gitzy/Features/Settings/SettingsWindowController.swift`)
- User → GitHub data state: connects account
- GitHub data state → Private token file: loads token (evidence: `Gitzy/Features/Contributions/ContributionStore.swift`)
- GitHub data state → GitHub API client: requests data (evidence: `Gitzy/Features/Contributions/ContributionStore.swift`)
- GitHub API client → GitHub API: sends GraphQL (evidence: `Gitzy/Services/GitHubService.swift`)
- GitHub API client → Contribution parsing: parses response (evidence: `Gitzy/Services/GitHubService.swift`)
- GitHub API client → Activity parsing: parses activity (evidence: `Gitzy/Services/GitHubService.swift`)
- GitHub data state → Contribution and activity views: supplies display data
- Settings controls → Preferences: configures preferences