# rian445/macasc architecture

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

- Interactive diagram: https://gitdiagram.com/rian445/macasc
- Repository: https://github.com/rian445/macasc

## Overview

#### Purpose and Runtime

Mac ASC is a native macOS menu-bar utility combining disk insight, shell-command execution, notes, and on-demand AI CLI workflows. It is a Swift Package/AppKit + SwiftUI application, distributed as a DMG or Homebrew cask. Primary launch and panel lifecycle are in `Sources/MacStorageUtilityApp.swift`; packaging is driven by `build.sh` and `Package.swift`.

#### Application Shell and UI Boundary

The app exposes a status-bar item that controls a floating panel rather than a conventional web or document app window. The primary SwiftUI dashboard, tab switching, settings UI, and feature surfaces are centralized in `Sources/DropdownView.swift`. Native blur/glass treatment crosses into AppKit through `Sources/VisualEffectView.swift`, isolating platform-specific visual effects from the SwiftUI interface.

#### State Coordination

`Sources/StorageViewModel.swift` is the central application state coordinator. It bridges UI actions to storage scans, command state, notes, settings, tab customization, backup/restore, and AI workflow state. This is the primary control boundary between `Sources/DropdownView.swift` and system-facing operations in `Sources/StorageManager.swift` or native process execution.

#### Disk Insight Pipeline

Storage discovery and categorization are system-facing operations implemented by `Sources/StorageManager.swift`, with presentation and user interaction in `Sources/DropdownView.swift`. The pipeline scans directory sizes asynchronously, aggregates categories such as applications, developer caches, documents, media, and system files, and reads mounted/external volumes for display and ejection actions. Results flow back through `Sources/StorageViewModel.swift` to avoid making view code the source of scanning state.

#### Local Automation and Filesystem Features

Custom commands are user-defined shell scripts organized in nested paths. They can be handed to `Terminal.app` for visible execution or launched headlessly through Swift `Process`, with running-state and stop controls coordinated by `Sources/StorageViewModel.swift` and rendered in `Sources/DropdownView.swift`. Notes, pinned folders, local settings, sort structures, and JSON backup/import are likewise local-data features managed through the view model; no server-side application component is present.

#### AI CLI Integration

AI is intentionally an on-demand subprocess integration, not a resident model runtime: installed `opencode`, OpenAI `codex`, and Google `antigravity`/`agy` CLIs are invoked only when used, preserving zero idle AI memory. The execution/session orchestration belongs to `Sources/StorageViewModel.swift`; UI chat and Terminal handoff belong to `Sources/DropdownView.swift`. `AI_ARCHITECTURE.md` defines the intended multi-agent execution, workspace, and session-persistence model.

#### External Dependencies, Security, and Delivery

Material external boundaries are macOS/AppKit, filesystem and mounted-volume APIs, `Terminal.app`, local shell processes, and separately installed AI command-line tools. The stated privacy model is local-first with no analytics or telemetry; related constraints are documented in `PRIVACY.md`. Release delivery uses a bundled DMG via `build.sh`, while `Casks/macasc.rb` provides Homebrew installation metadata.

Main entry points: [`Sources/DropdownView.swift`](https://github.com/rian445/macasc/blob/main/Sources/DropdownView.swift) (Dashboard & Feature UI), [`Sources/StorageViewModel.swift`](https://github.com/rian445/macasc/blob/main/Sources/StorageViewModel.swift) (Application State), [`Sources/MacStorageUtilityApp.swift`](https://github.com/rian445/macasc/blob/main/Sources/MacStorageUtilityApp.swift) (Menu Bar App), [`Sources/StorageManager.swift`](https://github.com/rian445/macasc/blob/main/Sources/StorageManager.swift) (Storage Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App Shell & UI"]
  node_app["Menu Bar App<br/>Swift app entry"]
  node_dashboard["Dashboard &amp; Feature UI<br/>SwiftUI views<br/>[DropdownView.swift]"]
  node_visual_effects["Native Glass Effects<br/>AppKit bridge"]
end

subgraph group_core["State &amp; Local Features"]
  node_view_model{{"Application State<br/>state coordinator"}}
  node_storage_manager["Storage Discovery<br/>storage service"]
  node_local_data[("Local User Data<br/>local persistence")]
  node_command_runtime["Command Runtime<br/>process orchestration"]
  node_ai_orchestration["AI Workflow Sessions<br/>CLI orchestration"]
end

subgraph group_system["System Integrations"]
  node_filesystem[("Filesystem &amp; Volumes<br/>macOS APIs")]
  node_terminal["Terminal.app<br/>external application"]
  node_shell{{"Local Shell Processes<br/>macOS Process"}}
  node_ai_clis{{"Installed AI CLIs<br/>external tools"}}
end

subgraph group_delivery["Architecture &amp; Delivery"]
  node_ai_architecture["AI Execution Design<br/>architecture document<br/>[AI_ARCHITECTURE.md]"]
  node_privacy["Privacy Model<br/>policy document<br/>[PRIVACY.md]"]
  node_package["Swift Package<br/>build manifest<br/>[Package.swift]"]
  node_build["DMG Build<br/>release script<br/>[build.sh]"]
  node_cask["Homebrew Cask<br/>install metadata<br/>[macasc.rb]"]
end

node_app -->|"hosts floating panel"| node_dashboard
node_dashboard -->|"uses"| node_visual_effects
node_dashboard -->|"binds actions and state"| node_view_model
node_view_model -->|"requests scans"| node_storage_manager
node_storage_manager -->|"scans directories and volumes"| node_filesystem
node_view_model -->|"manages"| node_local_data
node_view_model -->|"coordinates"| node_command_runtime
node_command_runtime -->|"launches headlessly"| node_shell
node_dashboard -->|"hands off visible commands"| node_terminal
node_view_model -->|"coordinates"| node_ai_orchestration
node_ai_orchestration -->|"invokes on demand"| node_ai_clis
node_dashboard -.->|"hands off AI sessions"| node_terminal
node_ai_orchestration -.->|"follows design"| node_ai_architecture
node_package -->|"builds"| node_app
node_build -->|"packages"| node_package
node_cask -->|"distributes DMG"| node_build
node_privacy -.->|"documents local-first boundary"| node_local_data

click node_app "https://github.com/rian445/macasc/blob/main/Sources/MacStorageUtilityApp.swift"
click node_dashboard "https://github.com/rian445/macasc/blob/main/Sources/DropdownView.swift"
click node_visual_effects "https://github.com/rian445/macasc/blob/main/Sources/VisualEffectView.swift"
click node_view_model "https://github.com/rian445/macasc/blob/main/Sources/StorageViewModel.swift"
click node_storage_manager "https://github.com/rian445/macasc/blob/main/Sources/StorageManager.swift"
click node_ai_architecture "https://github.com/rian445/macasc/blob/main/AI_ARCHITECTURE.md"
click node_privacy "https://github.com/rian445/macasc/blob/main/PRIVACY.md"
click node_package "https://github.com/rian445/macasc/blob/main/Package.swift"
click node_build "https://github.com/rian445/macasc/blob/main/build.sh"
click node_cask "https://github.com/rian445/macasc/blob/main/Casks/macasc.rb"

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_dashboard,node_visual_effects toneBlue
class node_view_model,node_storage_manager,node_local_data,node_command_runtime,node_ai_orchestration toneAmber
class node_filesystem,node_terminal,node_shell,node_ai_clis toneMint
class node_ai_architecture,node_privacy,node_package,node_build,node_cask toneRose
```

## Components

### App Shell & UI

- [Menu Bar App](https://github.com/rian445/macasc/blob/main/Sources/MacStorageUtilityApp.swift): Swift app entry · Owns status item and floating panel lifecycle. · `Sources/MacStorageUtilityApp.swift`
- [Dashboard & Feature UI](https://github.com/rian445/macasc/blob/main/Sources/DropdownView.swift): SwiftUI views · Hosts tabs, settings, storage, commands, notes, and AI surfaces. · `Sources/DropdownView.swift`
- [Native Glass Effects](https://github.com/rian445/macasc/blob/main/Sources/VisualEffectView.swift): AppKit bridge · `Sources/VisualEffectView.swift`

### State & Local Features

- [Application State](https://github.com/rian445/macasc/blob/main/Sources/StorageViewModel.swift): state coordinator · Coordinates UI state, local data, processes, scans, and AI sessions. · `Sources/StorageViewModel.swift`
- [Storage Discovery](https://github.com/rian445/macasc/blob/main/Sources/StorageManager.swift): storage service · Asynchronously scans sizes, categories, and mounted volumes. · `Sources/StorageManager.swift`
- **Local User Data**: local persistence · Notes, pinned folders, settings, sort data, and JSON backup/import.
- **Command Runtime**: process orchestration · Runs user shell scripts headlessly and tracks stop/running state.
- **AI Workflow Sessions**: CLI orchestration · Starts on-demand AI CLI workflows and preserves session state.

### System Integrations

- **Filesystem & Volumes**: macOS APIs · Directory metadata, mounted/external volumes, and ejection.
- **Terminal.app**: external application · Receives visible command and AI handoffs.
- **Local Shell Processes**: macOS Process
- **Installed AI CLIs**: external tools · opencode, codex, and antigravity/agy run only on demand.

### Architecture & Delivery

- [AI Execution Design](https://github.com/rian445/macasc/blob/main/AI_ARCHITECTURE.md): architecture document · Defines multi-agent execution, workspaces, and session persistence. · `AI_ARCHITECTURE.md`
- [Privacy Model](https://github.com/rian445/macasc/blob/main/PRIVACY.md): policy document · Documents local-first operation with no analytics or telemetry. · `PRIVACY.md`
- [Swift Package](https://github.com/rian445/macasc/blob/main/Package.swift): build manifest · `Package.swift`
- [DMG Build](https://github.com/rian445/macasc/blob/main/build.sh): release script · Builds the bundled DMG distribution. · `build.sh`
- [Homebrew Cask](https://github.com/rian445/macasc/blob/main/Casks/macasc.rb): install metadata · `Casks/macasc.rb`

## Connections

- Menu Bar App → Dashboard & Feature UI: hosts floating panel
- Dashboard & Feature UI → Native Glass Effects: uses
- Dashboard & Feature UI → Application State: binds actions and state
- Application State → Storage Discovery: requests scans
- Storage Discovery → Filesystem & Volumes: scans directories and volumes
- Application State → Local User Data: manages
- Application State → Command Runtime: coordinates
- Command Runtime → Local Shell Processes: launches headlessly
- Dashboard & Feature UI → Terminal.app: hands off visible commands
- Application State → AI Workflow Sessions: coordinates
- AI Workflow Sessions → Installed AI CLIs: invokes on demand
- Dashboard & Feature UI → Terminal.app: hands off AI sessions
- AI Workflow Sessions → AI Execution Design: follows design
- Swift Package → Menu Bar App: builds
- DMG Build → Swift Package: packages
- Homebrew Cask → DMG Build: distributes DMG
- Privacy Model → Local User Data: documents local-first boundary