# caldis/mos architecture

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

- Interactive diagram: https://gitdiagram.com/caldis/mos
- Repository: https://github.com/caldis/mos

## Overview

##### Project type and purpose
- This is a native macOS status‐bar application (Cocoa) that intercepts and smooths scroll events.
- It consists of a core scroll‐processing engine, a collection of UI windows/panels, singleton managers, utilities, localization bundles, build/package scripts, and a small web component for the project website.

##### File structure
Top-level layers:
- Mos/ – application source
· AppDelegate.swift – app lifecycle entry point
· ScrollCore/ – core smoothing engine
· Managers/ – NSStatusItem, Popover, Window, Desktop controllers
· Popovers/ – status‐item popover UI panels
· Windows/ – the various NSWindow‐based panels (Preferences, Monitor, Welcome)
· Options/ – domain model for user customization (whitelist/blacklist, curves)
· Utils/ – event intercept, logging, helpers
- dmg/ – DMG packaging scripts and assets
- docs/ & website/ – static website for documentation and download links

##### Key points from the README
- Goal: smooth mouse scrolling, separate touchpad vs. mouse, custom curves, per‐app settings, live charts.
- Dependencies: Charts library for graphical monitor window.
- Delivery via Homebrew Cask or DMG.

A. UI Layer
- Status Bar Item (NSStatusItem) → triggers PopoverManager
- Popovers & Windows
– Main Panel popover (controls on/off, flip direction)
– Preferences Window (tabs for General, Advanced, Exception lists, Updates)
– Monitor Window (live chart of scroll events using Charts framework)
– Welcome/Introduction window
B. Core Processing Layer
- EventMonitor / Interceptor (captures CGEvent taps for scroll events)
- ScrollCore
– ScrollEvent → ScrollFilter → Interpolator → ScrollPoster
– ScrollUtils, ScrollPhase, ScrollCurve config
C. Managers (Singletons)
- PopoverManager (shows/hides popovers)
- WindowManager (opens windows)
- DesktopManager (tracks active applications for white/black‐listing)
D. Options & Storage
- Options.swift + ExceptionalApplication.swift (model)
- Persist user settings (UserDefaults or Archive.swift)
E. Utilities
- Logger, Enhancers, Helpers
F. External Dependencies
- Charts framework (embedded)
G. Deployment/Packaging
- Xcode → Mos.app → create-dmg.command → .dmg
- Homebrew Cask recipe

##### Relationships and data flows
- User scrolls: OS → CGEventTap (Interceptor) → EventMonitor → ScrollCore pipeline → post back CGEvents → UI Chart (MonitorWindow)
- Changing preferences: PreferencesWindowController → updates Options → persists → informs ScrollCore / Managers
- Packaging: Xcode build → dmg/create-dmg.command → outputs distributable .dmg; Homebrew taps .app to /Applications

##### Architectural patterns and principles
- Cocoa/MVC: ViewControllers for each window/panel
- Singleton Managers for cross-module coordination
- Separation of concerns: UI vs. core smoothing logic vs. persistence
- Observer pattern: Options changes notify engine & UI

##### Detail level
- Charts library under “Monitor Window”
- Website/docs as an external system accessed by users for download

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External OS
    subgraph "macOS System"
        OS["OS Scroll Events"]:::external
    end

    %% App Lifecycle
    AppDelegate["AppDelegate"]:::app
    click AppDelegate "https://github.com/caldis/mos/blob/master/Mos/AppDelegate.swift"

    %% Utils: Event Capture
    subgraph "Event Capture" 
        EM["EventMonitor"]:::utils
        IN["Interceptor"]:::utils
    end
    click EM "https://github.com/caldis/mos/blob/master/Mos/Utils/EventMonitor.swift"
    click IN "https://github.com/caldis/mos/blob/master/Mos/Utils/Interceptor.swift"

    %% Core Processing Engine
    subgraph "ScrollCore Engine" 
        SC["ScrollCore"]:::core
        SE["ScrollEvent"]:::core
        SF["ScrollFilter"]:::core
        IP["Interpolator"]:::core
        SP["ScrollPoster"]:::core
        SPH["ScrollPhase"]:::core
        SU["ScrollUtils"]:::core
    end
    click SC "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollCore.swift"
    click SE "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollEvent.swift"
    click SF "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollFilter.swift"
    click IP "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/Interpolator.swift"
    click SP "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollPoster.swift"
    click SPH "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollPhase.swift"
    click SU "https://github.com/caldis/mos/blob/master/Mos/ScrollCore/ScrollUtils.swift"

    %% Managers
    subgraph "Singleton Managers" 
        SIM["StatusItemManager"]:::manager
        POM["PopoverManager"]:::manager
        WIM["WindowManager"]:::manager
        DEM["DesktopManager"]:::manager
    end
    click SIM "https://github.com/caldis/mos/blob/master/Mos/Managers/StatusItemManager.swift"
    click POM "https://github.com/caldis/mos/blob/master/Mos/Managers/PopoverManager.swift"
    click WIM "https://github.com/caldis/mos/blob/master/Mos/Managers/WindowManager.swift"
    click DEM "https://github.com/caldis/mos/blob/master/Mos/Managers/DesktopManager.swift"

    %% UI Layer
    subgraph "UI Layer" 
        subgraph Popovers
            MP["Main Panel Popover"]:::ui
            SPo["Secondary Popover"]:::ui
        end
        subgraph Windows
            IW["Introduction Window"]:::ui
            MW["Monitor Window"]:::ui
            PW["Preferences Window"]:::ui
            WW["Welcome Window"]:::ui
        end
    end
    click MP "https://github.com/caldis/mos/blob/master/Mos/Popovers/StatusItemMainPanel/StatusItemMainPanelViewController.swift"
    click SPo "https://github.com/caldis/mos/blob/master/Mos/Popovers/StatusItemPopover/StatusItemPopoverViewController.swift"
    click IW "https://github.com/caldis/mos/blob/master/Mos/Windows/IntroductionWindow/IntroductionWindowController.swift"
    click MW "https://github.com/caldis/mos/blob/master/Mos/Windows/MonitorWindow/MonitorWindowController.swift"
    click PW "https://github.com/caldis/mos/blob/master/Mos/Windows/PreferencesWindow/PreferencesWindowController.swift"
    click WW "https://github.com/caldis/mos/blob/master/Mos/Windows/WelcomeWindow/WelcomeWindowController.swift"

    %% Options & Storage
    subgraph "Options & Storage"
        OP["Options Model"]:::storage
        EA["ExceptionalApplication"]:::storage
        AR["Archive (Persistence)"]:::storage
    end
    click OP "https://github.com/caldis/mos/blob/master/Mos/Options/Options.swift"
    click EA "https://github.com/caldis/mos/blob/master/Mos/Options/ExceptionalApplication.swift"
    click AR "https://github.com/caldis/mos/blob/master/Mos/Utils/Archieve.swift"

    %% Utility Helpers
    subgraph "Utilities"
        LG["Logger"]:::utils
        EA2["EnhanceArray"]:::utils
        U["Utils"]:::utils
        C["Constants"]:::utils
    end
    click LG "https://github.com/caldis/mos/blob/master/Mos/Utils/Logger.swift"
    click EA2 "https://github.com/caldis/mos/blob/master/Mos/Utils/EnhanceArray.swift"
    click U "https://github.com/caldis/mos/blob/master/Mos/Utils/Utils.swift"
    click C "https://github.com/caldis/mos/blob/master/Mos/Utils/Constants.swift"

    %% External Dependencies
    subgraph "External Dependencies"
        CH["Charts Framework"]:::external
    end
    click CH "https://github.com/caldis/mos/blob/master/Mos.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved"

    %% Deployment & Docs
    subgraph "Deployment & Docs" 
        XB["Xcode Build → Mos.app"]:::deploy
        DMG["create-dmg.command"]:::deploy
        HB["Homebrew Cask Recipe"]:::deploy
        DOCS["Documentation Site"]:::external
        WEB["Website (Next.js)"]:::external
    end
    click DMG "https://github.com/caldis/mos/blob/master/dmg/create-dmg.command"
    click DOCS "https://github.com/caldis/mos/tree/master/docs/"
    click WEB "https://github.com/caldis/mos/tree/master/website/"

    %% Flows
    OS --> EM
    EM --> IN
    IN --> SC
    SC --> SE
    SE --> SF
    SF --> IP
    IP --> SP
    SP -->|repost| OS

    AppDelegate -->|registers| EM
    AppDelegate --> SIM
    AppDelegate --> POM
    AppDelegate --> WIM
    AppDelegate --> DEM

    SIM --> POM
    POM --> MP
    POM --> SPo
    SIM -->|click| MP

    MP --> OP
    SPo --> OP

    PW --> OP
    IW --> OP
    MW --> CH
    WW --> OP

    OP --> AR
    OP -->|notify| SC
    OP -->|notify| SIM

    PW -->|updates| OP
    MW -->|binds| OP

    %% Managers controlling UI
    WIM --> IW
    WIM --> MW
    WIM --> PW
    WIM --> WW

    %% Utils usage
    EM --> LG
    SC --> SU
    SC --> SPH
    SC --> LG

    %% Deployment flows
    XB --> DMG
    XB --> HB

    %% External access
    WEB --> DOCS

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px,shape:roundrect
    classDef core fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px
    classDef manager fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px
    classDef storage fill:#ffeeba,stroke:#856404,color:#856404,stroke-width:1px,shape:cylinder
    classDef utils fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px,shape:rect
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24,stroke-width:1px
    classDef deploy fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:1px,stroke-dasharray: 5 5
    classDef app fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px,shape:rect
```
