AGENTS.md

1# AGENTS.md
2 
3## What This Project Is
4- `proxypin` is a Flutter app with an in-process HTTP(S) proxy core; UI and proxy run in the same app process (`lib/main.dart`, `lib/network/bin/server.dart`).
5- Primary value flows are capture -> mutate -> inspect -> persist traffic, with desktop/mobile UIs sharing the same proxy engine.
6 
7## Architecture You Need First
8- Entry point chooses desktop vs mobile shells and optional multi-window mode (`lib/main.dart`).
9- Proxy server lifecycle is owned by `ProxyServer` (start/stop/restart, system proxy toggling, cert init) (`lib/network/bin/server.dart`).
10- Socket/channel pipeline lives in `Server`/`Network`; TLS MITM handshake and relay fallbacks happen in `Server.ssl` (`lib/network/channel/network.dart`).
11- HTTP request/response routing is centralized in `HttpProxyChannelHandler` and `HttpResponseProxyHandler` (`lib/network/handle/http_proxy_handle.dart`).
12- UI pages implement `EventListener` to receive `onRequest/onResponse/onMessage` events from proxy runtime (`lib/ui/desktop/desktop.dart`, `lib/ui/mobile/mobile.dart`, `lib/network/bin/listener.dart`).
13 
14## Interceptor Model (Core Convention)
15- All traffic mutations use `Interceptor` hooks: `preConnect`, `onRequest`, `execute`, `onResponse`, `onError` (`lib/network/components/interceptor.dart`).
16- Interceptors are sorted by `priority` before registration; changing order changes behavior (`lib/network/bin/server.dart`).
17- Current chain includes hosts, request-map, rewrite, JS script, block, breakpoint, report-server (`lib/network/bin/server.dart`).
18- `execute()` can short-circuit remote calls by returning a synthetic `HttpResponse` (used by request mapping) (`lib/network/components/request_map.dart`).
19 
20## Persistence + Config Patterns
21- Network/runtime config is JSON in app support/home paths (not in repo): `config.cnf`, `request_rewrite.json`, `request_map.json`, `script.json` (`lib/network/bin/configuration.dart`, `lib/network/components/manager/*`).
22- UI preferences are separate from proxy config (`ui_config.json`) (`lib/ui/configuration.dart`).
23- Captured traffic is persisted as HAR-like records via `HistoryStorage` and periodic `HistoryTask` flushes (`lib/storage/histories.dart`, `lib/utils/har.dart`).
24- Favorites intentionally trim websocket/SSE frame count and payload size before persistence (`lib/storage/favorites.dart`).
25 
26## Platform Integration Boundaries
27- iOS method channel: `com.proxypin/method` (local network access + cert trust checks) (`lib/native/native_method.dart`, `ios/Runner/Handlers/MethodHandler.swift`).
28- Android native plugins are registered in `MainActivity` (VPN, PiP, lifecycle, installed apps, process info) (`android/app/src/main/kotlin/com/network/proxy/MainActivity.kt`).
29- Desktop uses `desktop_multi_window`; some managers resolve app support path via window 0 IPC (`lib/network/components/manager/script_manager.dart`, `lib/network/components/manager/request_map_manager.dart`).
30 
31## Developer Workflows That Matter
32- Install deps: `flutter pub get`.
33- Run app: `flutter run -d macos|windows|linux|android|ios` (proxy boot is triggered from UI init, not a separate daemon).
34- Run tests: `flutter test` (see protocol-focused tests in `test/websocket_persistence_test.dart`, `test/http_test.dart`, `test/cert_test.dart`).
35- Localization is generated from `lib/l10n` using `l10n.yaml`; untranslated keys are tracked in `l10n_errors.txt`.
36- Distribution config lives in `distribute_options.yaml`; Linux `.deb` packaging helper is `linux/build.sh`.
37 
38## Project-Specific Guardrails For Agents
39- Do not store runtime defaults in source-only constants if equivalent persisted config exists; update the relevant manager/config serializer too.
40- When adding traffic features, prefer a new/interposed `Interceptor` instead of branching deep inside handlers.
41- Preserve wildcard URL rule semantics (`*` expansion, escaped `?`) used by rewrite/map rule matchers.
42- Keep desktop/mobile parity: shared proxy logic in `lib/network/**`, UI-specific behavior in `lib/ui/desktop/**` or `lib/ui/mobile/**` only.
43- Ignore generated/build artifacts (`build/`, platform build outputs) unless the task explicitly targets packaging.
44 
45