# fif7y/pelmet architecture

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

- Interactive diagram: https://gitdiagram.com/fif7y/pelmet
- Repository: https://github.com/fif7y/pelmet

## Overview

Pelmet is a native macOS menu-bar organizer: users assign icons to Visible, Hidden, and Always Hidden, then reveal them on demand or apply an edited layout. AppState coordinates the section model, the menu-bar engine, settings, and interactions; the engine observes and rearranges items while macOS performs native hiding. The README documents additional display rules, built-in replacement items, separators, animation, onboarding, and signed updates. Several feature implementations are unsampled, so those branches are shown at their documented subsystem paths; edges are limited to documented or indexed relationships.

Main entry points: [`Pelmet/App/AppState.swift`](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/AppState.swift) (AppState), [`Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift`](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift) (Bar engine), [`Pelmet/App/TransitionCoordinator.swift`](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/TransitionCoordinator.swift) (Reveal transitions), [`Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift`](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift) (Section model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Policy and layout"]
  node_settings[("Settings store")]
  node_section_model["Section model<br/>[SectionModel.swift]"]
  node_policy["Menu bar policy"]
  node_geometry["Placement geometry"]
end

subgraph group_engine["Menu bar engine"]
  node_engine["Bar engine"]
  node_enumerator["Item enumeration"]
  node_engine_api["Engine interface"]
  node_accessibility["Accessibility access"]
end

subgraph group_app["App coordination"]
  node_app_entry["Pelmet app<br/>[PelmetApp.swift]"]
  node_app_state["AppState<br/>[AppState.swift]"]
end

subgraph group_interaction["Interaction and editor"]
  node_editor_builder["Editor items"]
  node_apply["Apply pass<br/>[ApplyPass.swift]"]
  node_events["Reveal interactions"]
  node_transition["Reveal transitions"]
  node_status["Status item"]
  node_ghost["Animation overlay"]
  node_settings_ui["Settings and editor UI"]
end

subgraph group_features["User features"]
  node_extras["Built-in extras"]
  node_separators["Separators"]
  node_onboarding["Onboarding"]
  node_updater["Signed updater"]
end

node_user(("User"))
node_macos["macOS menu bar"]
node_sparkle["Sparkle update service"]

node_user -.->|"launches"| node_app_entry
node_app_state -->|"reads and writes"| node_settings
node_app_state -->|"coordinates"| node_engine
node_engine -->|"converges toward"| node_section_model
node_engine -->|"uses"| node_engine_api
node_engine -->|"refreshes from"| node_enumerator
node_engine -->|"asserts visibility and moves"| node_macos
node_engine -->|"observes and clicks via"| node_accessibility
node_section_model -->|"consults"| node_policy
node_user -->|"edits layout"| node_settings_ui
node_settings_ui -.->|"builds item tiles"| node_editor_builder
node_editor_builder -->|"reads assignments"| node_section_model
node_user -->|"applies layout"| node_app_state
node_app_state -->|"starts apply pass"| node_apply
node_apply -.->|"moves items"| node_engine
node_user -->|"requests reveal"| node_events
node_events -->|"signals interactions"| node_app_state
node_app_state -->|"coordinates transitions"| node_transition
node_transition -->|"converges visibility"| node_engine
node_transition -->|"animates over bar"| node_ghost
node_app_state -->|"updates status item"| node_status
node_app_state -->|"coordinates extras"| node_extras
node_app_state -->|"coordinates separators"| node_separators
node_user -->|"grants permissions"| node_onboarding
node_app_state -->|"presents onboarding"| node_onboarding
node_user -->|"checks for updates"| node_updater
node_updater -->|"checks signed releases"| node_sparkle
node_user -->|"uses native menu bar"| node_macos
node_geometry -->|"supports placement"| node_editor_builder

click node_app_entry "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/PelmetApp.swift"
click node_app_state "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/AppState.swift"
click node_settings "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/SettingsStore.swift"
click node_section_model "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift"
click node_policy "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/MenuBarPolicy.swift"
click node_geometry "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/PlacementGeometry.swift"
click node_engine "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift"
click node_enumerator "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/ItemEnumerator.swift"
click node_engine_api "https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/MenuBarEngine.swift"
click node_accessibility "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/AccessibilityAccess.swift"
click node_editor_builder "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/EditorItemsBuilder.swift"
click node_apply "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/ApplyPass.swift"
click node_events "https://github.com/fif7y/pelmet/tree/main/Pelmet/Events"
click node_transition "https://github.com/fif7y/pelmet/blob/main/Pelmet/App/TransitionCoordinator.swift"
click node_status "https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/PelmetStatusItem.swift"
click node_ghost "https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/ConcealGhostOverlay.swift"
click node_settings_ui "https://github.com/fif7y/pelmet/tree/main/Pelmet/Settings"
click node_extras "https://github.com/fif7y/pelmet/tree/main/Pelmet/Extras"
click node_separators "https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/SeparatorManager.swift"
click node_onboarding "https://github.com/fif7y/pelmet/blob/main/Pelmet/Onboarding/OnboardingController.swift"
click node_updater "https://github.com/fif7y/pelmet/blob/main/Pelmet/Update/SparkleController.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_settings,node_section_model,node_policy,node_geometry,node_user toneBlue
class node_engine,node_enumerator,node_engine_api,node_accessibility toneAmber
class node_app_entry,node_app_state toneMint
class node_editor_builder,node_apply,node_events,node_transition,node_status,node_ghost,node_settings_ui toneRose
class node_extras,node_separators,node_onboarding,node_updater,node_macos,node_sparkle toneIndigo
```

## Components

### Policy and layout

- [Settings store](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/SettingsStore.swift): `Packages/PelmetCore/Sources/PelmetCore/SettingsStore.swift`
- [Section model](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift): `Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift`
- [Menu bar policy](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/MenuBarPolicy.swift): `Packages/PelmetCore/Sources/PelmetCore/MenuBarPolicy.swift`
- [Placement geometry](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetCore/Sources/PelmetCore/PlacementGeometry.swift): `Packages/PelmetCore/Sources/PelmetCore/PlacementGeometry.swift`

### Menu bar engine

- [Bar engine](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift): `Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift`
- [Item enumeration](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/ItemEnumerator.swift): `Packages/PelmetEngine/Sources/PelmetEngine/ItemEnumerator.swift`
- [Engine interface](https://github.com/fif7y/pelmet/blob/main/Packages/PelmetEngine/Sources/PelmetEngine/MenuBarEngine.swift): `Packages/PelmetEngine/Sources/PelmetEngine/MenuBarEngine.swift`
- [Accessibility access](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/AccessibilityAccess.swift): `Pelmet/App/AccessibilityAccess.swift`

### App coordination

- [Pelmet app](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/PelmetApp.swift): `Pelmet/App/PelmetApp.swift`
- [AppState](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/AppState.swift): `Pelmet/App/AppState.swift`

### Interaction and editor

- [Editor items](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/EditorItemsBuilder.swift): `Pelmet/App/EditorItemsBuilder.swift`
- [Apply pass](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/ApplyPass.swift): `Pelmet/App/ApplyPass.swift`
- [Reveal interactions](https://github.com/fif7y/pelmet/tree/main/Pelmet/Events): `Pelmet/Events`
- [Reveal transitions](https://github.com/fif7y/pelmet/blob/main/Pelmet/App/TransitionCoordinator.swift): `Pelmet/App/TransitionCoordinator.swift`
- [Status item](https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/PelmetStatusItem.swift): `Pelmet/StatusItem/PelmetStatusItem.swift`
- [Animation overlay](https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/ConcealGhostOverlay.swift): `Pelmet/StatusItem/ConcealGhostOverlay.swift`
- [Settings and editor UI](https://github.com/fif7y/pelmet/tree/main/Pelmet/Settings): `Pelmet/Settings`

### User features

- [Built-in extras](https://github.com/fif7y/pelmet/tree/main/Pelmet/Extras): `Pelmet/Extras`
- [Separators](https://github.com/fif7y/pelmet/blob/main/Pelmet/StatusItem/SeparatorManager.swift): `Pelmet/StatusItem/SeparatorManager.swift`
- [Onboarding](https://github.com/fif7y/pelmet/blob/main/Pelmet/Onboarding/OnboardingController.swift): `Pelmet/Onboarding/OnboardingController.swift`
- [Signed updater](https://github.com/fif7y/pelmet/blob/main/Pelmet/Update/SparkleController.swift): `Pelmet/Update/SparkleController.swift`

### Other components

- **User**
- **macOS menu bar**
- **Sparkle update service**

## Connections

- User → Pelmet app: launches
- AppState → Settings store: reads and writes (evidence: `Pelmet/App/AppState.swift`)
- AppState → Bar engine: coordinates (evidence: `Pelmet/App/AppState.swift`)
- Bar engine → Section model: converges toward (evidence: `Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift`)
- Bar engine → Engine interface: uses (evidence: `Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift`)
- Bar engine → Item enumeration: refreshes from (evidence: `Packages/PelmetEngine/Sources/PelmetEngine/AgentBarEngine.swift`)
- Bar engine → macOS menu bar: asserts visibility and moves (evidence: `README.md`)
- Bar engine → Accessibility access: observes and clicks via (evidence: `README.md`)
- Section model → Menu bar policy: consults (evidence: `Packages/PelmetCore/Sources/PelmetCore/SectionModel.swift`)
- User → Settings and editor UI: edits layout (evidence: `README.md`)
- Settings and editor UI → Editor items: builds item tiles
- Editor items → Section model: reads assignments (evidence: `Pelmet/App/EditorItemsBuilder.swift`)
- User → AppState: applies layout (evidence: `README.md`)
- AppState → Apply pass: starts apply pass (evidence: `Pelmet/App/AppState.swift`)
- Apply pass → Bar engine: moves items (evidence: `Pelmet/App/ApplyPass.swift`)
- User → Reveal interactions: requests reveal (evidence: `README.md`)
- Reveal interactions → AppState: signals interactions (evidence: `Pelmet/Events/MenuBarBandMonitor.swift`)
- AppState → Reveal transitions: coordinates transitions (evidence: `Pelmet/App/AppState.swift`)
- Reveal transitions → Bar engine: converges visibility (evidence: `Pelmet/App/TransitionCoordinator.swift`)
- Reveal transitions → Animation overlay: animates over bar (evidence: `Pelmet/App/TransitionCoordinator.swift`)
- AppState → Status item: updates status item (evidence: `Pelmet/App/AppState.swift`)
- AppState → Built-in extras: coordinates extras (evidence: `Pelmet/Extras/MediaControls.swift`)
- AppState → Separators: coordinates separators (evidence: `Pelmet/App/AppState.swift`)
- User → Onboarding: grants permissions (evidence: `README.md`)
- AppState → Onboarding: presents onboarding (evidence: `Pelmet/App/AppState.swift`)
- User → Signed updater: checks for updates (evidence: `README.md`)
- Signed updater → Sparkle update service: checks signed releases (evidence: `README.md`)
- User → macOS menu bar: uses native menu bar (evidence: `README.md`)
- Placement geometry → Editor items: supports placement (evidence: `Pelmet/App/EditorItemsBuilder.swift`)
