Contributing

ProxyPro is a personal project, but PRs are welcome.

Repo layout

proxypro/
├── proto/                       # gRPC contracts (engine <-> main)
├── engine/                      # Go daemon
│   ├── go.mod
│   ├── cmd/proxypro-engine/     # main package
│   └── internal/
│       ├── ca/                  # root + leaf cert minting
│       ├── ipc/                 # gRPC server + IPC types
│       ├── mobile/              # iOS .mobileconfig builder
│       ├── network/             # LAN IP detection
│       ├── protocols/http1/     # gzip decompress + h1 helpers
│       ├── proxy/               # main MITM logic
│       ├── rules/               # rule store + Map Local
│       ├── storage/             # ring buffer + body LRU
│       └── version/             # ldflags-stamped build metadata
├── app/                         # Electron + React + Vite client
│   ├── electron.vite.config.ts
│   ├── src/
│   │   ├── main/                # Node-side: engine supervisor + grpc client
│   │   ├── preload/             # contextBridge API
│   │   ├── renderer/src/        # React UI
│   │   └── shared/              # types + IPC channels shared across processes
│   ├── e2e/                     # Playwright Electron tests
│   └── package.json
├── scripts/
│   ├── gen-proto.sh             # protoc Go + ts-proto
│   ├── build-engine.sh
│   └── package-app.sh
├── docs/                        # in-repo design docs (architecture, standards)
├── plans/                       # implementation plans + reports
├── site/                        # this Astro Starlight docs site
├── Makefile                     # top-level build orchestration
└── .github/workflows/           # CI + GH Pages deploy

Local development

make bootstrap   # install protoc plugins + pnpm deps
make proto       # regenerate bindings
make engine      # macOS universal binary; Linux native binary
make dev         # launch Electron with HMR
make test        # Go unit + integration tests
make dist        # production .app

For app-only iteration:

cd app
pnpm typecheck      # TypeScript strict
pnpm test           # Vitest renderer + main
pnpm test:e2e       # Playwright Electron end-to-end
pnpm build          # Vite production build

Testing conventions

Layer	Framework	Where
Go pure functions	`go test`	colocated `*_test.go`
Go integration (proxy round-trip)	`go test` + `httptest`	`engine/internal/proxy/*_test.go`
Renderer pure functions	Vitest	colocated `*.test.ts`
Main process logic	Vitest with mocked Node APIs	`app/src/main/*.test.ts`
Electron end-to-end	Playwright `_electron.launch`	`app/e2e/*.spec.ts`

Smoke tests (*.smoke.ts) live alongside main process code but are excluded from typecheck and run manually via tsx.

Plan files

Non-trivial features go through a plan document at plans/<date>-<slug>/phase-XX-name.md. Each phase doc has:

Frontmatter with status, completion date
Requirements / architecture / implementation steps / todo list
Success criteria + risks

See plans/260521-2144-proxypro-foundations/ for the v0.1.0 set. Polish backlog items use a .5 suffix (P02.5, P03.5, …) when they extend an already-shipped phase.

Commit message convention

Conventional commits. The project uses:

feat(engine): / feat(app): for new functionality
fix(engine): / fix(app): for bug fixes
test: for test-only changes
chore: for build / tooling / config
docs: for documentation

No AI references in commit messages.

CI

GitHub Actions runs on every push to main + every PR. The Ubuntu job generates bindings, typechecks and tests the app, runs all Go tests, builds the native Linux engine and npm harness bundle, then boots them together and completes a real MCP/browser round trip: proxied Chromium renders a local fixture and the harness correlates its captured request back to the browser action. Publishing a GitHub release triggers a separate matrix job that builds and attaches linux-amd64 and linux-arm64 artifacts.

Playwright E2E is not in CI yet (needs macOS runner with display forwarding); it’s manually verified before tagged releases.

Where things live in my head

Proxy plumbing → engine/internal/proxy/
Rules → engine/internal/rules/
gRPC IPC → engine/internal/ipc/ + proto/
UI components → app/src/renderer/src/features/
Engine lifecycle / process supervision → app/src/main/engine-supervisor.ts
System integration (proxy toggle, cert install, file pickers) → app/src/main/*.ts

Source

github.com/trongitnlu/proxypro