# wojciech-kulik/flashspace architecture

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

- Interactive diagram: https://gitdiagram.com/wojciech-kulik/flashspace
- Repository: https://github.com/wojciech-kulik/flashspace

## Overview

##### Main Components
- Entry Point & Core App Logic:
- Components in FlashSpace/App (FlashSpaceApp, AppDelegate, AppDependencies, Migrations) represent the entry point and core life-cycle management.
- Feature Modules:
- FlashSpace/Features contains modular components for each feature: FocusManager (window and app focus switching), HotKeys (managing configurable hotkeys), Integrations (interfacing with external applications/systems), MenuBar (display and interaction with the macOS menu bar), PictureInPicture (handling experimental PiP capabilities), Profiles (configuration management), Settings (user preferences and configuration views), SpaceControl (preview and control of workspaces), and Workspaces (defining and managing workspaces).
- UI Components:
- FlashSpace/UI holds custom UI elements (Alerts, InputDialog, Toast notifications, HotKeyControl) to deliver user interactions and notifications.
- FlashSpace/Main deals with the main view and its corresponding view model.
- Utilities & Extensions:
- FlashSpace/Utils offers support services such as Autostart, FileChooser, PermissionsManager, and UpdatesManager.
- FlashSpace/Extensions provides helper extensions for common types and functionality that enable cleaner code throughout the application.
- Assets & Resources:
- Project & Build Infrastructure:
- Files like project.yml, the Xcode project (FlashSpace.xcodeproj), and fastlane configurations indicate the build and deployment setup.
- GitHub workflows and configuration files support continuous integration and quality checks.

##### Relationships and Interactions
- The Core Application interacts with multiple feature modules, invoking specialized managers (like the FocusManager or SpaceControl) based on user input or system events.
- UI components bind to feature view models (e.g., MainViewModel and SpaceControlViewModel) to reflect live status and control state.
- The Features interact with each other (e.g., HotKeys may trigger workspace changes managed by the WorkspaceManager; MenuBar features display workspace info) and with Utils for system tasks such as launching, configuration updates, and permission handling.
- Extensions provide common functionality that is used across features and the core app to simplify tasks like handling shortcuts, manipulating views, or formatting strings.
- There is also an external service integration part (e.g., SketchyBar integration) which is triggered by changes in the workspace state and handled via configurable scripts.

##### Architectural Patterns and Design Principles
- Modularization: Each major functionality (workspace management, window focus, hotkey management, settings) is encapsulated in its own module under the Features directory.
- MVVM for UI: The code includes clear separation between View (MainView, SpaceControlView, etc.) and ViewModel components.
- Extensions and Utility Layers: The code leverages Swift’s extension mechanism to add common functionalities and maintain DRY code.
- Clean Separation of Concerns: Core services (e.g., AppDependencies, Migrations) are isolated from UI and feature-specific logic.

##### Final Detailed Steps for the Principal Software Engineer
a. Start by sketching the top-level structure:
- Surround it with the major feature modules (e.g., Focus Manager, HotKeys, SpaceControl, Settings, Workspaces).
- UI components (MainView, MenuBar, etc.) connected to these features.
c. In external integrations (such as SketchyBar) to illustrate how the app interfaces with external systems.
f. Use annotations to highlight critical design decisions such as the “non-disruptive behavior” and the deliberate avoidance of managing individual app windows per workspace.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core App Layer
    subgraph "Core App Layer"
        CA1["FlashSpaceApp"]
        CA2["AppDelegate"]
        CA3["AppDependencies"]
        CA4["Migrations"]
    end

    %% Feature Modules Layer
    subgraph "Feature Modules Layer"
        subgraph "Focus Manager"
            FM1["FocusManager"]
            FM2["FocusedWindowTracker"]
            FM3["Focus Models"]
        end
        subgraph "HotKeys"
            HK1["HotKeysManager"]
            HK2["HotKeysMonitor"]
        end
        subgraph "Integrations"
            INT1["Integrations"]
        end
        subgraph "MenuBar"
            MB1["FlashSpaceMenuBar"]
            MB2["MenuBarTitle"]
        end
        subgraph "Picture-in-Picture"
            PP1["PictureInPictureManager"]
        end
        subgraph "Profiles"
            P1["ProfilesRepository"]
        end
        subgraph "Settings"
            SET1["SettingsRepository"]
            SET2["Settings Views"]
        end
        subgraph "SpaceControl"
            SC1["SpaceControl"]
            SC2["WorkspaceScreenshotManager"]
            SC3["SpaceControl Views"]
        end
        subgraph "Workspaces"
            WS1["Workspace Models"]
            WS2["WorkspaceHotKeys"]
            WS3["WorkspaceManager"]
            WS4["WorkspaceRepository"]
        end
    end

    %% UI Components Layer
    subgraph "UI Components Layer"
        subgraph "FlashSpace/UI"
            UIa["Alerts"]
            UIb["HotKeyControl"]
            UIc["InputDialog"]
            UId["Toast"]
        end
        subgraph "FlashSpace/Main"
            UIM1["MainView"]
            UIM2["MainViewModel"]
        end
    end

    %% Utilities & Extensions Layer
    subgraph "Utilities & Extensions Layer"
        subgraph "Utilities"
            UTL["AutostartService"]
            FT01["FileChooser"]
            PT01["PermissionsManager"]
            UM01["UpdatesManager"]
        end
        EXT["Extensions"]
    end

    %% Assets & Resources
    subgraph "Assets & Resources"
        AS["Assets & Resources"]
    end

    %% Build Infrastructure
    subgraph "Build Infrastructure"
        B1["project.yml"]
        B2["Xcode Project"]
        B3["fastlane"]
        B4["GitHub Workflows"]
    end

    %% External Integration
    EX["SketchyBar Integration"]

    %% Connections within Core App
    CA1 --> CA2
    CA2 --> CA3
    CA3 --> CA4

    %% Core App interacts with Feature Modules
    CA1 --> FM1
    CA1 --> HK1
    CA1 --> INT1
    CA1 --> MB1
    CA1 --> PP1
    CA1 --> P1
    CA1 --> SET1
    CA1 --> SC1
    CA1 --> WS3

    %% Feature Modules Interactions
    HK1 -->|"triggers"| WS3
    MB1 -->|"displays"| WS3
    SC1 -->|"notifies"| INT1
    INT1 --> EX

    %% UI Components interactions with Feature Modules
    UIM1 -->|"bindsTo"| SC1
    UIM1 -->|"bindsTo"| WS3
    UIM1 -->|"controls"| MB1

    %% Feature Modules using Utilities & Extensions
    FM1 --> UTL
    FM1 --> EXT
    HK1 --> UTL
    HK1 --> EXT
    INT1 --> UTL
    INT1 --> EXT
    MB1 --> UTL
    MB1 --> EXT
    PP1 --> UTL
    PP1 --> EXT
    P1 --> UTL
    P1 --> EXT
    SET1 --> UTL
    SET1 --> EXT
    SC1 --> UTL
    SC1 --> EXT
    WS3 --> UTL
    WS3 --> EXT

    %% Assets used by UI Components
    AS --> UIM1

    %% Build Infrastructure builds the Core App
    B1 --> CA1
    B2 --> CA1
    B3 --> CA1
    B4 --> CA1

    %% Class Definitions
    class CA1,CA2,CA3,CA4 core
    class FM1,FM2,FM3,HK1,HK2,INT1,MB1,MB2,PP1,P1,SET1,SET2,SC1,SC2,SC3,WS1,WS2,WS3,WS4 feature
    class UIa,UIb,UIc,UId,UIM1,UIM2 ui
    class UTL,FT01,PT01,UM01,EXT util
    class AS asset
    class B1,B2,B3,B4 build
    class EX external

    %% Click Events for Core App
    click CA1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/App/FlashSpaceApp.swift"
    click CA2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/App/AppDelegate.swift"
    click CA3 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/App/AppDependencies.swift"
    click CA4 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/App/Migrations.swift"

    %% Click Events for FocusManager Feature Module
    click FM1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/FocusManager/FocusManager.swift"
    click FM2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/FocusManager/FocusedWindowTracker.swift"
    click FM3 "https://github.com/wojciech-kulik/flashspace/tree/main/FlashSpace/Features/FocusManager/Models"

    %% Click Events for HotKeys Feature Module
    click HK1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/HotKeys/HotKeysManager.swift"
    click HK2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/HotKeys/HotKeysMonitor.swift"

    %% Click Events for Integrations Feature Module
    click INT1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Integrations/Integrations.swift"

    %% Click Events for MenuBar Feature Module
    click MB1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/MenuBar/FlashSpaceMenuBar.swift"
    click MB2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/MenuBar/MenuBarTitle.swift"

    %% Click Event for PictureInPicture Feature Module
    click PP1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/PictureInPicture/PictureInPictureManager.swift"

    %% Click Event for Profiles Feature Module
    click P1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Profiles/ProfilesRepository.swift"

    %% Click Events for Settings Feature Module
    click SET1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Settings/SettingsRepository.swift"
    click SET2 "https://github.com/wojciech-kulik/flashspace/tree/main/FlashSpace/Features/Settings/Views"

    %% Click Events for SpaceControl Feature Module
    click SC1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/SpaceControl/SpaceControl.swift"
    click SC2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/SpaceControl/WorkspaceScreenshotManager.swift"
    click SC3 "https://github.com/wojciech-kulik/flashspace/tree/main/FlashSpace/Features/SpaceControl/Views"

    %% Click Events for Workspaces Feature Module
    click WS1 "https://github.com/wojciech-kulik/flashspace/tree/main/FlashSpace/Features/Workspaces/Models"
    click WS2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Workspaces/WorkspaceHotKeys.swift"
    click WS3 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Workspaces/WorkspaceManager.swift"
    click WS4 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Features/Workspaces/WorkspaceRepository.swift"

    %% Click Events for UI Components (FlashSpace/UI)
    click UIa "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/UI/Alerts.swift"
    click UIb "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/UI/HotKeyControl.swift"
    click UIc "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/UI/InputDialog.swift"
    click UId "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/UI/Toast.swift"

    %% Click Events for UI Components (FlashSpace/Main)
    click UIM1 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Main/MainView.swift"
    click UIM2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Main/MainViewModel.swift"

    %% Click Events for Utilities
    click UTL "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Utils/AutostartService.swift"
    click FT01 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Utils/FileChooser.swift"
    click PT01 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Utils/PermissionsManager.swift"
    click UM01 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Utils/UpdatesManager.swift"

    %% Click Event for Extensions
    click EXT "https://github.com/wojciech-kulik/flashspace/tree/main/FlashSpace/Extensions"

    %% Click Event for Assets
    click AS "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace/Assets.xcassets"

    %% Click Events for Build Infrastructure
    click B1 "https://github.com/wojciech-kulik/flashspace/blob/main/project.yml"
    click B2 "https://github.com/wojciech-kulik/flashspace/blob/main/FlashSpace.xcodeproj"
    click B3 "https://github.com/wojciech-kulik/flashspace/tree/main/fastlane/Fastfile"
    click B4 "https://github.com/wojciech-kulik/flashspace/tree/main/.github/workflows"
    
classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
classDef feature fill:#ccffcc,stroke:#006600,stroke-width:2px;
classDef ui fill:#ccccff,stroke:#000099,stroke-width:2px;
classDef util fill:#ffffcc,stroke:#999900,stroke-width:2px;
classDef asset fill:#e0e0e0,stroke:#666666,stroke-width:2px;
classDef build fill:#ffccff,stroke:#990099,stroke-width:2px;
classDef external fill:#ccffff,stroke:#009999,stroke-width:2px;
```
