Architecture

Architecture Overview

High-level architecture of Pi Island
Properties2
Iconi-lucide-boxes
Order40

Pi Island is a native macOS application built with Swift and SwiftUI.

High-Level Architecture

Pi Island (macOS app)
    |
    |--- stdin/stdout JSON protocol
    |
    v
pi --mode rpc (child process)

Core Components

  • PiRPCClient: Actor-based RPC client
  • SessionManager: Multi-session management with delete support
  • NotchViewModel: State management for UI
  • NotchWindowController: NSWindowController for panel with screen updates
  • DisplayMonitor: Monitors display configuration changes
  • UsageMonitorService: AI provider usage tracking across multiple services

File Structure

Sources/PiIsland/
├── Core/
│   ├── DisplayMonitor.swift    # External display handling
│   ├── EventMonitors.swift     # Mouse event tracking
│   ├── NotchGeometry.swift     # Geometry calculations
│   ├── NotchViewModel.swift    # UI state management
│   └── NSScreen+Notch.swift    # Screen extensions
├── UI/
│   ├── NotchView.swift         # Main SwiftUI view
│   ├── NotchShape.swift        # Animatable notch shape
│   ├── NotchWindowController.swift
│   └── PiLogo.swift            # Logo shape
├── RPC/
│   ├── PiRPCClient.swift       # RPC client actor
│   ├── SessionManager.swift    # Multi-session management
│   └── RPCTypes.swift          # Protocol types
└── UsageMonitor/
    ├── Models/
    │   ├── AIProvider.swift    # Provider enumeration
    │   ├── RateWindow.swift    # Quota window model
    │   ├── UsageSnapshot.swift # Usage data snapshot
    │   └── UsageError.swift    # Error types
    ├── Providers/
    │   ├── UsageProvider.swift # Provider protocol
    │   ├── AnthropicProvider.swift
    │   ├── CopilotProvider.swift
    │   ├── GeminiCliProvider.swift
    │   ├── AntigravityProvider.swift
    │   └── SyntheticProvider.swift
    ├── Services/
    │   ├── UsageMonitorService.swift  # Main service
    │   └── CredentialManager.swift    # Credential loading
    └── Views/
        ├── UsageNotchView.swift    # Main usage view
        ├── UsageBarView.swift      # Progress bar component
        └── UsageRowView.swift      # Provider row component

Display Monitoring

Pi Island monitors display configuration changes to handle external monitors:

  1. DisplayMonitor listens for NSApplication.didChangeScreenParametersNotification
  2. When the configuration changes, it determines the target screen (built-in preferred)
  3. NotchWindowController.updateForScreen() repositions the window
  4. NotchViewModel.updateGeometry() recalculates geometry

This ensures the notch UI always appears on the correct screen when:

  • Laptop lid is closed with external monitor connected
  • Laptop lid is reopened
  • External monitor is connected/disconnected