# proxy — Architecture

> 22 modules | 193 functions | 36 classes

## How It Works

`proxy` analyzes source code via a multi-stage pipeline:

```
Source files  ──►  code2llm (tree-sitter + AST)  ──►  AnalysisResult
                                                          │
              ┌───────────────────────────────────────────┘
              ▼
    ┌─────────────────────┐
    │   12 Generators     │
    │  ─────────────────  │
    │  README.md          │
    │  docs/api/          │
    │  docs/modules/      │
    │  docs/architecture   │
    │  docs/coverage      │
    │  examples/          │
    │  mkdocs.yml         │
    │  CONTRIBUTING.md    │
    └─────────────────────┘
```

**Analysis algorithms:**

1. **AST parsing** — language-specific parsers (tree-sitter) extract syntax trees
2. **Cyclomatic complexity** — counts independent code paths per function
3. **Fan-in / fan-out** — measures module coupling (how many modules import/are imported by each)
4. **Docstring extraction** — parses Google/NumPy/Sphinx-style docstrings into structured data
5. **Pattern detection** — identifies design patterns (Factory, Singleton, Observer, etc.)
6. **Dependency scanning** — reads pyproject.toml / requirements.txt / setup.py

## Architecture Layers

```mermaid
graph TD
    Other["Other<br/>20 modules"]
    Config["Config<br/>1 modules"]
    API___CLI["API / CLI<br/>1 modules"]
    Other --> Config
    Config --> API___CLI
```

### Other

- `frontend.proxym-dashboard`
- `project`
- `scripts.jetson-entrypoint`
- `scripts.setup`
- `src.proxym`
- `src.proxym.accounts`
- `src.proxym.cache`
- `src.proxym.ctl`
- `src.proxym.dashboard`
- `src.proxym.dashboard.panel`
- `src.proxym.main`
- `src.proxym.middleware`
- `src.proxym.providers`
- `src.proxym.router`
- `src.proxym.router.strategy`
- `src.proxym.virt`
- `src.proxym.virt.browser_profiles`
- `src.proxym.virt.clonebox_adapter`
- `src.proxym.virt.profiles`
- `src.proxym.watch`

### Config

- `src.proxym.config`

### API / CLI

- `src.proxym.watch.client`

## Module Dependency Graph

```mermaid
graph LR
    note[No internal dependencies detected]
```

## Key Classes

```mermaid
classDiagram
    class VMOrchestrator {
        -__init__(self, config_dir, images_dir) None
        -_load_configs(self) None
        -_save_config(self, vm) None
        -_get_clonebox(self) None
        -_resolve_backend(self, config) None
        +create_vm(self, config) None
        -_create_vm_clonebox(self, config) None
        -_create_vm_virsh(self, config) None
        ... +14 more
    }
    class CloneBoxAdapter {
        -__init__(self, profiles_dir) None
        +is_available(self) None
        +version(self) None
        +create_vm(self, name, profile_path) None
        +start_vm(self, name) None
        +stop_vm(self, name) None
        +snapshot(self, name, snapshot_name) None
        +restore_snapshot(self, name, snapshot_name) None
        ... +9 more
    }
    class AccountManager {
        -__init__(self, config_path) None
        -_load(self) None
        -_save(self) None
        +add_account(self, account) None
        +remove_account(self, account_id) None
        +get_account(self, account_id) None
        +list_accounts(self, provider, tag) None
        +find_cheapest_active(self, provider) None
        ... +6 more
    }
    class DeltaBuffer {
        -__init__(self, watch_dir, max_context_tokens) None
        +scan(self) None
        +compute_delta(self) None
        -_build_full_context(self, snapshots) None
        -_estimate_tokens(self, text) None
        +get_stats(self) None
    }
    class CostLedger {
        -__init__(self, daily_limit, monthly_limit) None
        -_rotate_keys(self) None
        +can_spend(self, estimated_usd) None
        +record(self, actual_usd) None
        +src.proxym.router.strategy.CostLedger.daily_remaining()
        +src.proxym.router.strategy.CostLedger.monthly_remaining()
    }
    class Router {
        -__init__(self, available_providers, ledger) None
        +route(self, analysis, explicit_model) None
        +record_latency(self, model_id, latency_s) None
        +record_cost(self, cost_usd) None
    }
    class DeltaWatchClient {
        -__init__(self, watch_dir, proxy_url) None
        +push_delta(self) None
        +run(self) None
        +close(self) None
    }
    class Account {
        +src.proxym.accounts.Account.is_active()
        +src.proxym.accounts.Account.is_over_budget()
        +status_summary(self) None
    }
    class AuthMiddleware {
        -__init__(self, app, master_key) None
        +dispatch(self, request, call_next) None
    }
    class AccountLimits {
        +is_over_budget(self, metrics) None
        +budget_remaining(self, metrics) None
    }
    class FileSnapshot {
        +from_path(path) None
    }
    class DeltaPayload {
        +src.proxym.cache.DeltaPayload.payload()
    }
    class CostTrackingMiddleware {
        +dispatch(self, request, call_next) None
    }
    class BrowserProfile {
        +to_dict(self) None
    }
    class ProjectsConfig {
        +filter_projects(self, projects) None
    }
```

## Detected Patterns

- **recursion_merge_profiles** (recursion) — confidence: 90%, functions: `src.proxym.virt.profiles.merge_profiles`

## Public Entry Points

- `src.proxym.ctl.cmd_serve` — Start the proxy server (delegates to proxym.main:cli).
- `src.proxym.ctl.cmd_status`
- `src.proxym.ctl.cmd_accounts_list`
- `src.proxym.ctl.cmd_accounts_add`
- `src.proxym.ctl.cmd_accounts_costs`
- `src.proxym.ctl.cmd_vm_list`
- `src.proxym.ctl.cmd_vm_create`
- `src.proxym.ctl.cmd_vm_switch`
- `src.proxym.ctl.cmd_vm_open` — Open SPICE viewer for a VM (virt-viewer).
- `src.proxym.ctl.cmd_vm_ssh` — SSH into a VM (auto-detect IP via dashboard).
- `src.proxym.ctl.cmd_vm_logs` — Show cloud-init logs and tool logs from a VM.
- `src.proxym.ctl.cmd_browser_list` — List detected browser profiles on the host.
- `src.proxym.ctl.cmd_browser_assign` — Assign a browser profile to an account.
- `src.proxym.ctl.cmd_browser_sync` — Sync browser profile host ↔ VM.
- `src.proxym.ctl.cmd_browser_snapshot` — Save browser state from VM as snapshot.
- `src.proxym.ctl.cmd_models`
- `src.proxym.ctl.main`
- `src.proxym.virt.browser_profiles.generate_app_data_sync` — Generate an AppDataSync config for copying a profile into a VM.
- `src.proxym.providers.cheapest_model` — Return the single cheapest model that satisfies constraints.
- `src.proxym.watch.cli` — CLI entry point for proxym-client.
- `src.proxym.virt.profiles.get_builtin_profile` — Get the path to a built-in profile YAML for a tool.
- `src.proxym.virt.profiles.list_builtin_profiles` — List all available built-in profile names.
- `src.proxym.virt.profiles.load_profile_yaml` — Load a YAML profile, with graceful fallback if PyYAML is not installed.
- `frontend.proxym-dashboard.pct`
- `frontend.proxym-dashboard.color`
- `frontend.proxym-dashboard.handleCreate`
- `frontend.proxym-dashboard.refresh`
- `frontend.proxym-dashboard.h`
- `src.proxym.dashboard.panel.pct`
- `src.proxym.dashboard.panel.color`
- `src.proxym.dashboard.panel.handleCreate`
- `src.proxym.dashboard.panel.refresh`
- `src.proxym.dashboard.panel.h`
- `src.proxym.dashboard.list_accounts`
- `src.proxym.dashboard.create_account`
- `src.proxym.dashboard.get_account`
- `src.proxym.dashboard.delete_account`
- `src.proxym.dashboard.bind_tool`
- `src.proxym.dashboard.cost_summary` — Aggregate cost dashboard across all accounts.
- `src.proxym.dashboard.cost_detailed` — Per-account cost breakdown.
- `src.proxym.dashboard.list_vms`
- `src.proxym.dashboard.create_vm`
- `src.proxym.dashboard.start_vm`
- `src.proxym.dashboard.stop_vm`
- `src.proxym.dashboard.pause_vm`
- `src.proxym.dashboard.resume_vm`
- `src.proxym.dashboard.snapshot_vm`
- `src.proxym.dashboard.switch_project`
- `src.proxym.dashboard.delete_vm`
- `src.proxym.dashboard.dashboard_root` — Dashboard root - redirects to system status.
- `src.proxym.main.lifespan`
- `src.proxym.main.health`
- `src.proxym.main.dashboard_ui` — Serve the React dashboard UI.
- `src.proxym.main.dashboard_jsx` — Serve the React dashboard JSX file.
- `src.proxym.main.list_models` — List available models (OpenAI-compatible).
- `src.proxym.main.budget_status` — Return current budget usage.
- `src.proxym.main.context_stats` — Return delta buffer statistics.
- `src.proxym.main.receive_delta` — Receive context delta from the file watcher client.
- `src.proxym.main.chat_completions` — OpenAI-compatible chat completions with intelligent routing.
- `src.proxym.main.cli`

## Metrics Summary

| Metric | Value |
|--------|-------|
| Modules | 22 |
| Functions | 193 |
| Classes | 36 |
| CFG Nodes | 981 |
| Patterns | 1 |
| Avg Complexity | 3.9 |
| Analysis Time | 7.35s |
