navtoj/notchbar

1. What this repository is

- NotchBar is a macOS 14.5+ SwiftUI app that overlays custom content in the unused area around a MacBook notch and also exposes a small menu bar item for actions.

2. Top-level architecture

- The app is organized as a single macOS application target under src/NotchBar, built with Tuist (src/Project.swift, src/Tuist.swift, src/Tuist/Package.swift).

- Source is split into clear layers: app bootstrap, shared state, window/UI composition, reusable widget modules, shapes/visual helpers, and small extensions.

3. App lifecycle and bootstrap

- main.swift is the entry point.

- AppDelegate.swift and AppWindow.swift likely handle macOS-specific app startup concerns that SwiftUI alone does not cover well: creating the main overlay window, controlling visibility, and coordinating app/menu-bar behavior.

- AppView.swift is the top-level SwiftUI view that composes the main notch-bar interface.

4. Core state boundary

- AppState.swift and SystemState.swift form the app’s state layer.

- This is the primary boundary between UI and live system data: the UI reads from state objects, while system polling/observation updates them.

- AppUrls.swift centralizes app-specific navigation or external links used by settings/help actions.

5. Widget architecture

- The Sources/Widgets folder is the main feature subsystem.

- WidgetView.swift acts as a generic wrapper for a widget with:

- a primary view that is always visible in the notch bar,

- an optional secondary view used for a dropdown/details card.

- This gives the app a reusable pattern for multiple widget types without duplicating layout logic.

6. Concrete widgets shipped in the repo

- ActiveApp shows the currently focused app’s icon/name.

- MediaRemote displays media playback data and controls; it has both primary and secondary views and a MediaCommand model for user actions.

- SystemInfo shows system-monitor style information such as CPU, memory, storage, battery, and network.

- Example provides sample widget views and serves as a reference implementation/template.

7. Data flow from system sources to UI

- Widget-specific data models (ActiveAppData, MediaData, SystemInfoData) represent the live snapshot each widget renders.

- System-facing helpers and extensions (SystemInfoExtension.swift, MediaCommand.swift) adapt platform APIs into the app’s internal data flow.

- The general flow is: macOS/system APIs → widget data structs/state → SwiftUI widget views → overlay/menu-bar presentation.

8. Windowing and layout

- WindowViews/Settings.swift and WindowViews/Welcome.swift are separate window-level screens, distinct from the always-visible notch-bar content.

- This suggests the app uses a mix of main overlay window plus auxiliary windows/sheets for onboarding and configuration.

- Shapes/ contains custom geometry used to fit the display notch and rounded edges precisely:

- InvertedCapsule

- InvertedBottomCorners

- RoundCornersInvertedTop

9. UI helpers and platform extensions

- The Extensions/ folder contains small cross-cutting helpers for Angle, NSColor, NSImage, NSScreen, UserDefaults, and View.

- These are likely used to bridge AppKit and SwiftUI, inspect screen geometry, persist preferences, and tweak rendering behavior.

- External/Marquee.swift is a vendored UI utility for scrolling text, probably used where widget content must fit tight horizontal space.

10. Resources and assets

- App icons and color assets live under Resources/Assets.xcassets.

- The _assets folder is documentation/marketing content for the README, including screenshots and installation imagery; it is not part of runtime app logic.

11. Build, packaging, and release

- Tuist manages project generation and dependency resolution.

- .github/workflows/release.yml indicates an automated release pipeline that likely builds, packages, and publishes the distributable .zip/.app used by the README installation flow.

- The repo is therefore designed around source-managed app generation + release artifact distribution, not server deployment.

12. Architecture summary for a diagram

- The cleanest diagram is: macOS app shell in the center, fed by system/app state sources, rendering through SwiftUI widget modules, with custom notch-shaped window geometry and secondary settings/welcome windows, all built and packaged via Tuist + GitHub Actions.