# lvillani/chai architecture

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

- Interactive diagram: https://gitdiagram.com/lvillani/chai
- Repository: https://github.com/lvillani/chai

## Overview

##### Project Type & Purpose
- Chai is an open source macOS utility, similar in function to Caffeine. Its primary purpose is to prevent the Mac from falling asleep by using power assertions (making use of IOPMLib).
- The existence of installation instructions using Homebrew and comparisons to an existing tool (Caffeine) confirms it’s aimed at end users looking for a secure and open alternative.

##### Analyzing the File Structure
- Top-Level Directories/Files:
- The “Chai” directory contains the main application’s source code including AppDelegate.swift, assets (like AppIcon and imagesets), configuration files (Info.plist), and UI elements (MainMenu.xib).
- The “ChaiHelper” directory mirrors many of these files which suggests it’s a helper tool—likely used to run background tasks or extend functionality.
- The Xcode project (Chai.xcodeproj) and bridging header indicate the use of both Swift and possibly some Objective-C for interoperability.
- Other supporting directories like “script” and “.github” indicate additional elements for automation (CI builds, formatting, etc.) but aren’t part of the core runtime architecture.

##### Extracting Architectural Insights from the README
- The README highlights the use of power assertions through IOPMLib to keep the Mac awake.
- It emphasizes sandboxing (security) and positions Chai as a superior open-source alternative to Caffeine.
- These elements signal that security (sandbox usage), interaction with macOS system frameworks, and a clean separation between UI and system interactions are key design tenets.

a. Main Components:
- User / macOS Environment – representing the computer system where Chai runs.
- Chai Main Application – includes:
– UI Components: AppDelegate, MainMenu.xib, and Asset management.
– Core Logic Components: Files like Defaults.swift, State.swift, and PowerAssertion.swift that implement the functionality to prevent sleep.
– System Integration: Bundled with Info.plist and entitlements for sandbox compliance and macOS integration.
- ChaiHelper Process – a subsidiary module with its own UI and app delegate that likely handles auxiliary tasks.
- External Dependencies – highlight the use of IOPMLib (for power assertions) and macOS sandboxing framework.
- Build & Deployment Pipeline – indicate the presence of CI scripts in the “script” folder and workflows in “.github” that manage builds and formatting checks.

b. Relationships and Interactions:
- Optionally, include a side branch representing the CI/CD pipeline to indicate that the build and deployment automation (using Homebrew formulas and GitHub Actions) feeds into the main codebase.

c. Highlighting Architectural Patterns:
- The separation between “Chai” and “ChaiHelper” suggests a modular structure where one process handles the main interface and another assists in background or helper tasks.
- The use of separate modules for UI, configuration, and system integrations demonstrates a clean separation of concerns.
- The overall design follows standard macOS app architectural principles (AppDelegate handling lifecycle, use of Info.plist for configuration, reliance on standard asset management).

d. Relevant Technologies & Frameworks:
- macOS Cocoa framework (for UI and app lifecycle management).
- IOPMLib for interfacing with system power management.
- Xcode-based build system.
- Homebrew for end-user installation.
- Sandbox for application security.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entity
    User["User / macOS Environment"]:::user

    %% Chai Main Application Subgraph
    subgraph "Chai Main Application"
        direction TB
        UI1["AppDelegate (UI)"]:::UI
        UI2["MainMenu (UI)"]:::UI
        UI3["Assets"]:::UI
        L1["Defaults (Logic)"]:::logic
        L2["State (Logic)"]:::logic
        L3["PowerAssertion (Logic)"]:::logic
        L4["ActivationSpecs (Logic)"]:::logic
        C1["Info.plist"]:::config
        C2["Entitlements"]:::config
    end

    %% ChaiHelper Process Subgraph
    subgraph "ChaiHelper Process"
        direction TB
        H1["Helper AppDelegate (UI)"]:::UI
        H2["Helper MainMenu (UI)"]:::UI
        H3["Helper Info.plist"]:::config
        H4["Helper Entitlements"]:::config
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        direction TB
        E1["IOPMLib & Sandbox"]:::ext
    end

    %% Build & Deployment Pipeline Subgraph
    subgraph "Build & Deployment Pipeline"
        direction TB
        B1["CI Workflow"]:::ci
        B2["CIBuild Script"]:::ci
        B3["Crop-Screenshot Script"]:::ci
        B4["Format Script"]:::ci
    end

    %% Connections
    User -->|"initiates"| UI1
    User --> UI2
    UI1 -->|"triggers"| L1
    UI2 --> L1
    L1 --> L3
    L1 --> L2
    L3 -->|"uses"| E1
    L4 -->|"requires"| E1
    L1 --> L4
    L1 -->|"checks"| C1
    L1 --> C2
    UI1 -->|"launches"| H1
    UI2 --> H2
    B1 ---|"feeds into"| UI1
    B1 --- H1
    B2 --- UI1
    B3 --- UI1
    B4 --- UI1

    %% Styling Classes
    classDef UI fill:#D6E9C6,stroke:#4CAF50,stroke-width:2px;
    classDef logic fill:#C6D9F1,stroke:#3366FF,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef ext fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef ci fill:#E2E3E5,stroke:#6C757D,stroke-width:2px;
    classDef user fill:#F0B27A,stroke:#E67E22,stroke-width:2px;

    %% Click Events for Chai Main Application Components
    click UI1 "https://github.com/lvillani/chai/blob/master/Chai/AppDelegate.swift"
    click UI2 "https://github.com/lvillani/chai/blob/master/Chai/Base.lproj/MainMenu.xib"
    click UI3 "https://github.com/lvillani/chai/blob/master/Chai/Assets.xcassets"
    click L1 "https://github.com/lvillani/chai/blob/master/Chai/Defaults.swift"
    click L2 "https://github.com/lvillani/chai/blob/master/Chai/State.swift"
    click L3 "https://github.com/lvillani/chai/blob/master/Chai/PowerAssertion.swift"
    click L4 "https://github.com/lvillani/chai/blob/master/Chai/ActivationSpecs.swift"
    click C1 "https://github.com/lvillani/chai/blob/master/Chai/Info.plist"
    click C2 "https://github.com/lvillani/chai/blob/master/Chai/Chai.entitlements"

    %% Click Events for ChaiHelper Process Components
    click H1 "https://github.com/lvillani/chai/blob/master/ChaiHelper/AppDelegate.swift"
    click H2 "https://github.com/lvillani/chai/blob/master/ChaiHelper/Base.lproj/MainMenu.xib"
    click H3 "https://github.com/lvillani/chai/blob/master/ChaiHelper/Info.plist"
    click H4 "https://github.com/lvillani/chai/blob/master/ChaiHelper/ChaiHelper.entitlements"

    %% Click Events for Build & Deployment Pipeline Components
    click B1 "https://github.com/lvillani/chai/blob/master/.github/workflows/ci.yml"
    click B2 "https://github.com/lvillani/chai/tree/master/script/cibuild"
    click B3 "https://github.com/lvillani/chai/tree/master/script/crop-screenshot"
    click B4 "https://github.com/lvillani/chai/tree/master/script/format"
```
