architecture.md

Project Architecture

This repository contains three runtime layers and two generated-output layers. Source code must not depend on generated directories.

HTTPS-Proxy/
├─ openai-proxy.js             Node proxy process entry
├─ hpm-cli.js                  Command-line entry
├─ proxy.{bat,ps1}             Cross-shell proxy control entry points
├─ 启动*.bat                    User-facing Windows launchers
├─ proxy.config.json           Local editable config; generated and ignored
├─ lib/
│  ├─ proxy/                   Proxy application and protocol modules
│  │  ├─ handlers/            Management and protocol request handlers
│  │  └─ runtime/             Process-level runtime boundaries
│  ├─ release/                 Release validation and safety rules
│  └─ governance/              Repository architecture rules
├─ tauri-ui/
│  ├─ index.html               Only frontend document entry
│  ├─ src/
│  │  ├─ main.js               Vite entry
│  │  ├─ app/
│  │  │  ├─ bootstrap.js       Frontend composition and application coordinator
│  │  │  ├─ ux.js              Shared browser UX boundary
│  │  │  ├─ domains/           Independently configured UI domains
│  │  │  ├─ models/            Dependency-free config parsing and normalization
│  │  │  └─ runtime/           Dependency-free state, DOM and timing primitives
│  │  └─ styles/
│  └─ dist/                    Vite output; generated and ignored
├─ src-tauri/                  Native shell, commands, permissions and bundling
│  ├─ src/
│  │  ├─ lib.rs               Tauri application composition
│  │  ├─ desktop_shell.rs     Menu, tray, window and native path UX
│  │  └─ proxy_root.rs        Runtime/resource root discovery
│  └─ icons/                  Canonical desktop and tray icon assets
├─ scripts/                    Build, verification and operational entry scripts
├─ docs/                       Architecture, governance and historical QA records
├─ coverage/                   Disposable test coverage reports
├─ test/
│  ├─ frontend/                Frontend behavior and architecture tests
│  ├─ governance/              Repository and release policy tests
│  └─ *.test.js                Recursively discovered proxy/runtime tests
└─ dist/
   ├─ staging/
   │  ├─ runtime/              Disposable Node runtime for Tauri packaging
   │  └─ portable/             Expanded portable package; never published
   ├─ artifacts/
   │  ├─ installers/           Collected installers and checksums
   │  ├─ portable/             Portable ZIP and checksums only
   │  └─ sbom/                 Release software bills of materials
   └─ archive/                 Local-only legacy artifacts; never uploaded

Frontend dependency direction

flowchart LR
  HTML["index.html"] --> Main["src/main.js"]
  Main --> Styles["styles/app.css"]
  Main --> Bootstrap["app/bootstrap.js"]
  Bootstrap --> UX["app/ux.js"]
  Bootstrap --> Domains["app/domains/*"]
  Bootstrap --> Runtime["app/runtime/*"]
  Runtime --> Domains
  Bootstrap --> Vite["Vite bundle"]
  Vite --> Tauri["Tauri frontendDist"]

Loading

The dependency rules are:

1. main.js is the only Vite entry and contains no business logic. UX services use ESM exports; window.UX and side-effect compatibility globals are forbidden.
2. bootstrap.js owns application startup and domain composition. Its current size budget is enforced by the composition-root governance test and may only decrease.
3. Domain modules do not import bootstrap.js or other domain modules. They receive browser, state and service dependencies through their configure*() boundary.
4. domains/prompts.js owns prompt storage, synchronization and template DOM bindings. domains/rate-limits.js owns limit state, polling and rendering.
5. models/configuration.js parses and normalizes untrusted persisted settings, protocols, entry servers and entry authentication without browser dependencies.
6. Runtime and model modules have no project-relative imports. They expose small, independently tested primitives for shared state, DOM operations, dependency binding and performance scheduling.
7. The frontend ESM graph must remain acyclic.
8. tauri-ui/dist/ is generated only by Vite. The removed dist/tauri-ui/ path must never return.

These rules are enforced by npm run check:architecture and therefore run before every production frontend build.

Generated output lifecycle

• npm run clean:frontend removes only tauri-ui/dist/ and the obsolete dist/tauri-ui/ path.
• npm run clean:coverage removes only coverage reports.
• npm run clean:test-runtime removes only ignored runtime files accidentally left under test/.
• npm run clean:staging removes only disposable release staging.
• npm run clean:artifacts removes only final release deliverables.
• npm run frontend:build runs architecture checks, cleans frontend output, and creates a fresh Vite bundle.
• npm run clean:release removes staging, final artifacts, frontend output and Cargo output. It preserves dist/archive/ and local application state.
• npm run clean:release:cache removes only Cargo target directories.

Generated output is ignored by Git and must not be used as an editable source. Release automation reads and uploads only dist/artifacts/; it never reads dist/archive/. Both installed and portable packages contain only the production lib/proxy/ tree; repository governance, coverage and test-support modules are excluded from releases.

src-tauri/target/ is a disposable Cargo compilation cache and can be large. .hpm-runtime/ is different: it contains local application state and may include generated certificates, so cleanup commands deliberately never remove it.

Verification entry points

• npm test: unit, frontend, thinking persistence and environment tests.
• npm run test:all: npm test plus integration tests.
• npm run verify: formatting, syntax, lint, architecture, CI/release governance, backend and frontend-boundary coverage, integration, frontend build and Rust tests.
• npm run tauri:build: production Tauri build and installer collection.

All composition roots and high-churn protocol/UI modules have non-increasing line budgets in test/governance/composition-roots.test.js and test/governance/module-size-budgets.test.js. Network policy, runtime-root discovery and other independently testable logic must live in dedicated modules rather than being added back to those entries.