# nguyenphutrong/quotio architecture

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

- Interactive diagram: https://gitdiagram.com/nguyenphutrong/quotio
- Repository: https://github.com/nguyenphutrong/quotio

## Overview

Quotio combines a native macOS command center with a Rust CLI for quota visibility, account management, local proxy/agent setup, and automation. The main user journey is to provide or discover provider credentials, fetch quota usage, then inspect it in the app, terminal, JSON, or local API. The map also preserves proxy lifecycle, agent configuration, and tunnel capabilities. The README and tree establish these product areas; sampled excerpts support only selected runtime links, so uncertain wiring is omitted.

Main entry points: [`Packages/QuotioCore/Sources/QuotioPresentation/Quota/QuotaFeatureController.swift`](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Quota/QuotaFeatureController.swift) (Quota refresh), [`apps/cli/src/fetch.rs`](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/fetch.rs) (Usage collection), [`apps/cli/src/main.rs`](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/main.rs) (CLI commands), [`Packages/QuotioCore/Sources/QuotioPresentation/Screens`](https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Screens) (App screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mac["macOS app"]
  node_macui["App screens"]
  node_dashboard["Dashboard and menu bar"]
end

subgraph group_core["Shared app core"]
  node_quota_feature["Quota refresh"]
  node_account_service["Account management"]
  node_quota_fetchers["Quota fetchers"]
  node_agent_setup["Agent setup"]
  node_proxy_lifecycle["Proxy lifecycle"]
  node_proxy_process["Proxy process"]
  node_tunnel["Remote tunnel"]
end

subgraph group_cli["CLI runtime"]
  node_cli_entry["CLI commands<br/>[main.rs]"]
  node_collector["Usage collection<br/>[fetch.rs]"]
  node_cli_accounts["Saved accounts<br/>[service.rs]"]
  node_cli_output["Text and JSON<br/>[mod.rs]"]
  node_api["Loopback REST API<br/>[server.rs]"]
end

subgraph group_providers["Provider integrations"]
  node_cli_providers["Provider catalog<br/>[mod.rs]"]
  node_cli_adapters["Provider adapters"]
end

subgraph group_state["Credentials and state"]
  node_credentials["Account credentials"]
  node_local_state[("Local credential sources<br/>[sources.rs]")]
end

node_user(("User"))
node_cli_user(("Terminal user"))
node_external_providers(("AI providers"))

node_user -->|"uses"| node_macui
node_macui -->|"requests refresh"| node_quota_feature
node_quota_feature -->|"reloads accounts"| node_account_service
node_quota_feature -->|"refreshes quota"| node_quota_fetchers
node_quota_feature -->|"publishes updates"| node_dashboard
node_user -->|"configures agents"| node_agent_setup
node_user -->|"controls proxy"| node_proxy_lifecycle
node_proxy_lifecycle -->|"starts and stops"| node_proxy_process
node_user -->|"controls tunnel"| node_tunnel
node_account_service -->|"manages credentials"| node_credentials
node_cli_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"collects usage"| node_collector
node_collector -->|"uses account data"| node_cli_accounts
node_collector -->|"selects providers"| node_cli_providers
node_collector -->|"fetches usage"| node_cli_adapters
node_cli_adapters -->|"requests quota"| node_external_providers
node_cli_entry -->|"renders reports"| node_cli_output
node_cli_user -.->|"calls API"| node_api
node_cli_accounts -->|"reads and writes"| node_local_state

click node_macui "https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Screens"
click node_dashboard "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Dashboard/DashboardScreenModel.swift"
click node_quota_feature "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Quota/QuotaFeatureController.swift"
click node_account_service "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Accounts/AccountService.swift"
click node_quota_fetchers "https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioInfrastructure/Quota"
click node_agent_setup "https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Agents"
click node_proxy_lifecycle "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Proxy/ProxyLifecycleController.swift"
click node_proxy_process "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioInfrastructure/Process/ProxyProcessController.swift"
click node_tunnel "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Tunnel/TunnelLifecycleController.swift"
click node_credentials "https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Accounts/AuthFileRepository.swift"
click node_cli_entry "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/main.rs"
click node_collector "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/fetch.rs"
click node_cli_accounts "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/accounts/service.rs"
click node_cli_providers "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/providers/catalog/mod.rs"
click node_cli_adapters "https://github.com/nguyenphutrong/quotio/tree/v0.x/apps/cli/src/providers"
click node_cli_output "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/output/mod.rs"
click node_api "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/server.rs"
click node_local_state "https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/accounts/sources.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_macui,node_dashboard,node_user,node_cli_user toneBlue
class node_quota_feature,node_account_service,node_quota_fetchers,node_agent_setup,node_proxy_lifecycle,node_proxy_process,node_tunnel toneAmber
class node_cli_entry,node_collector,node_cli_accounts,node_cli_output,node_api toneMint
class node_cli_providers,node_cli_adapters toneRose
class node_credentials,node_local_state,node_external_providers toneIndigo
```

## Components

### macOS app

- [App screens](https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Screens): `Packages/QuotioCore/Sources/QuotioPresentation/Screens`
- [Dashboard and menu bar](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Dashboard/DashboardScreenModel.swift): `Packages/QuotioCore/Sources/QuotioPresentation/Dashboard/DashboardScreenModel.swift`

### Shared app core

- [Quota refresh](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioPresentation/Quota/QuotaFeatureController.swift): `Packages/QuotioCore/Sources/QuotioPresentation/Quota/QuotaFeatureController.swift`
- [Account management](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Accounts/AccountService.swift): `Packages/QuotioCore/Sources/QuotioApplication/Accounts/AccountService.swift`
- [Quota fetchers](https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioInfrastructure/Quota): `Packages/QuotioCore/Sources/QuotioInfrastructure/Quota`
- [Agent setup](https://github.com/nguyenphutrong/quotio/tree/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Agents): `Packages/QuotioCore/Sources/QuotioApplication/Agents`
- [Proxy lifecycle](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Proxy/ProxyLifecycleController.swift): `Packages/QuotioCore/Sources/QuotioApplication/Proxy/ProxyLifecycleController.swift`
- [Proxy process](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioInfrastructure/Process/ProxyProcessController.swift): `Packages/QuotioCore/Sources/QuotioInfrastructure/Process/ProxyProcessController.swift`
- [Remote tunnel](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Tunnel/TunnelLifecycleController.swift): `Packages/QuotioCore/Sources/QuotioApplication/Tunnel/TunnelLifecycleController.swift`

### CLI runtime

- [CLI commands](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/main.rs): `apps/cli/src/main.rs`
- [Usage collection](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/fetch.rs): `apps/cli/src/fetch.rs`
- [Saved accounts](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/accounts/service.rs): `apps/cli/src/accounts/service.rs`
- [Text and JSON](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/output/mod.rs): `apps/cli/src/output/mod.rs`
- [Loopback REST API](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/server.rs): `apps/cli/src/server.rs`

### Provider integrations

- [Provider catalog](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/providers/catalog/mod.rs): `apps/cli/src/providers/catalog/mod.rs`
- [Provider adapters](https://github.com/nguyenphutrong/quotio/tree/v0.x/apps/cli/src/providers): `apps/cli/src/providers`

### Credentials and state

- [Account credentials](https://github.com/nguyenphutrong/quotio/blob/v0.x/Packages/QuotioCore/Sources/QuotioApplication/Accounts/AuthFileRepository.swift): `Packages/QuotioCore/Sources/QuotioApplication/Accounts/AuthFileRepository.swift`
- [Local credential sources](https://github.com/nguyenphutrong/quotio/blob/v0.x/apps/cli/src/accounts/sources.rs): `apps/cli/src/accounts/sources.rs`

### Other components

- **User**
- **Terminal user**
- **AI providers**

## Connections

- User → App screens: uses
- App screens → Quota refresh: requests refresh
- Quota refresh → Account management: reloads accounts
- Quota refresh → Quota fetchers: refreshes quota
- Quota refresh → Dashboard and menu bar: publishes updates
- User → Agent setup: configures agents
- User → Proxy lifecycle: controls proxy
- Proxy lifecycle → Proxy process: starts and stops
- User → Remote tunnel: controls tunnel
- Account management → Account credentials: manages credentials
- Terminal user → CLI commands: runs commands
- CLI commands → Usage collection: collects usage
- Usage collection → Saved accounts: uses account data
- Usage collection → Provider catalog: selects providers
- Usage collection → Provider adapters: fetches usage
- Provider adapters → AI providers: requests quota
- CLI commands → Text and JSON: renders reports
- Terminal user → Loopback REST API: calls API
- Saved accounts → Local credential sources: reads and writes