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      # build universal Go 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:

1. engine job on ubuntu-latest — go vet, go test, cross-compile for darwin/arm64 + darwin/amd64.
2. app job on macos-latest — pnpm install, pnpm typecheck, pnpm build.

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