Quotio - Codebase Summary

Last Updated: December 27, 2024
Swift Version: 6.0
Minimum macOS: 15.0 (Sequoia)

---

Table of Contents

1. Technology Stack
2. Dependencies
3. High-Level Module Overview
4. Key Files and Their Purposes
5. Data Flow Overview
6. Build and Configuration Files

---

Technology Stack

Key Swift 6 Features Used

• @Observable macro for reactive state
• @MainActor for UI-bound classes
• actor for thread-safe services
• Sendable conformance for cross-actor data
• async/await for all asynchronous operations

---

Dependencies

Third-Party Dependencies

System Frameworks

External Binaries

---

High-Level Module Overview

Application Layer

Quotio/
├── QuotioApp.swift          # App entry point, lifecycle management
└── Info.plist               # App metadata and permissions

Models Layer

Quotio/Models/
├── Models.swift             # Core data types (AIProvider, AuthFile, etc.)
├── AgentModels.swift        # CLI agent configuration types
├── AppMode.swift            # App mode management (Full/Quota-Only)
└── MenuBarSettings.swift    # Menu bar configuration and persistence

Services Layer

Quotio/Services/
├── CLIProxyManager.swift        # Proxy process lifecycle
├── ManagementAPIClient.swift    # HTTP client for proxy API
├── StatusBarManager.swift       # NSStatusBar management
├── NotificationManager.swift    # User notification handling
├── UpdaterService.swift         # Sparkle integration
├── AgentDetectionService.swift  # CLI agent detection
├── AgentConfigurationService.swift # Agent config generation
├── ShellProfileManager.swift    # Shell profile updates
├── DirectAuthFileService.swift  # Direct auth file scanning
├── CLIExecutor.swift            # CLI command execution
├── LanguageManager.swift        # Localization management
└── *QuotaFetcher.swift          # Provider-specific quota fetchers (7 files)

ViewModels Layer

Quotio/ViewModels/
├── QuotaViewModel.swift         # Main app state container
└── AgentSetupViewModel.swift    # Agent configuration state

Views Layer

Quotio/Views/
├── Components/
│   ├── AgentCard.swift          # Agent display card
│   ├── AgentConfigSheet.swift   # Agent configuration sheet
│   ├── MenuBarView.swift        # Menu bar popover content
│   ├── ProviderIcon.swift       # Provider icon component
│   ├── QuotaCard.swift          # Quota display card
│   ├── QuotaProgressBar.swift   # Progress bar component
│   └── SidebarView.swift        # Navigation sidebar
└── Screens/
    ├── DashboardScreen.swift    # Main dashboard
    ├── QuotaScreen.swift        # Quota monitoring
    ├── ProvidersScreen.swift    # Provider management
    ├── AgentSetupScreen.swift   # Agent configuration
    ├── APIKeysScreen.swift      # API key management
    ├── LogsScreen.swift         # Log viewer
    └── SettingsScreen.swift     # App settings

Assets

Quotio/Assets.xcassets/
├── AppIcon.appiconset/          # App icons (production)
├── AppIconDev.appiconset/       # App icons (development)
├── MenuBarIcons/                # Provider icons for menu bar
├── ProviderIcons/               # Provider logos
└── AccentColor.colorset/        # Accent color definition

---

Key Files and Their Purposes

Entry Point

Core Data Types

Services

Quota Fetchers

ViewModels

---

Data Flow Overview

Application Startup Flow

1. QuotioApp.init()
   │
   ├─▶ @State viewModel = QuotaViewModel()
   │   └─▶ CLIProxyManager.shared initialized
   │
   ├─▶ Check onboarding status
   │   └─▶ Show ModePickerView if not completed
   │
   └─▶ initializeApp()
       ├─▶ Apply appearance settings
       ├─▶ Mode-based initialization
       │   ├─▶ Full Mode: Start proxy if autoStart enabled
       │   └─▶ Quota-Only: Load direct auth files, fetch quotas
       │
       └─▶ Update status bar

Full Mode Data Flow

┌──────────────────┐
│   User Action    │
│ (Start Proxy)    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ QuotaViewModel   │
│  .startProxy()   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐       ┌────────────────────┐
│ CLIProxyManager  │──────▶│   CLIProxyAPI      │
│    .start()      │       │   (Binary)         │
└────────┬─────────┘       └────────────────────┘
         │
         ▼
┌──────────────────┐
│ ManagementAPI    │
│    Client        │ ◀─── HTTP requests to localhost:8317
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Auto-Refresh    │ ──── Every 15 seconds
│    Task          │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ UI Updates via   │
│  @Observable     │
└──────────────────┘

Quota Fetching Flow

┌──────────────────────────────────────────────────────┐
│                  refreshAllQuotas()                   │
└────────────────────────┬─────────────────────────────┘
                         │
    ┌────────────────────┼────────────────────┐
    │                    │                    │
    ▼                    ▼                    ▼
┌─────────┐        ┌─────────┐         ┌─────────┐
│Antigrav │        │ OpenAI  │         │ Copilot │
│ Fetcher │        │ Fetcher │         │ Fetcher │
└────┬────┘        └────┬────┘         └────┬────┘
    │                   │                    │
    ▼                   ▼                    ▼
┌─────────────────────────────────────────────────┐
│           providerQuotas: [AIProvider:         │
│                 [String: ProviderQuotaData]]   │
└─────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│           StatusBarManager.updateStatusBar()    │
└─────────────────────────────────────────────────┘

OAuth Authentication Flow

┌──────────────┐     ┌───────────────┐     ┌─────────────────┐
│    User      │────▶│ QuotaViewModel │────▶│ Management API  │
│ Clicks Auth  │     │  .startOAuth() │     │ Client          │
└──────────────┘     └───────┬───────┘     └────────┬────────┘
                             │                      │
                             │     GET /xxx-auth-url
                             │◀─────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Open Browser   │
                    │   (OAuth URL)   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Poll Status    │
                    │  (every 2s)     │
                    └────────┬────────┘
                             │
                    Success? ─┴─ Continue polling
                             │
                             ▼
                    ┌─────────────────┐
                    │  Refresh Data   │
                    └─────────────────┘

Agent Configuration Flow

┌─────────────────┐     ┌──────────────────────┐
│  AgentSetup     │────▶│ AgentSetupViewModel   │
│   Screen        │     │  .applyConfiguration()│
└─────────────────┘     └──────────┬───────────┘
                                   │
                                   ▼
                       ┌───────────────────────┐
                       │ AgentConfiguration    │
                       │      Service          │
                       └──────────┬────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐     ┌─────────────────┐
│  Write Config   │    │  Update Shell   │     │   Copy to       │
│   JSON/TOML     │    │    Profile      │     │   Clipboard     │
└─────────────────┘    └─────────────────┘     └─────────────────┘

---

Build and Configuration Files

Xcode Project

Build Configurations

Build Scripts

App Configuration

---

Runtime File Locations

Application Support

~/Library/Application Support/Quotio/
├── CLIProxyAPI          # Downloaded proxy binary
└── config.yaml          # Proxy configuration

Auth Files Directory

~/.cli-proxy-api/
├── gemini-cli-*.json    # Gemini auth files
├── claude-*.json        # Claude auth files
├── codex-*.json         # Codex auth files
├── github-copilot-*.json # Copilot auth files
└── ...                  # Other provider auth files

User Defaults Keys

---

Localization Structure

Quotio/
└── Resources/
    ├── en.lproj/
    │   └── Localizable.strings
    └── vi.lproj/
        └── Localizable.strings

Localization Key Patterns