--- name: codebase-map description: Where things live in the portal-tunnel repo (sdk/portal/types/utils/cmd/discovery/x402/frontend/extensions) and where new code belongs. Use when locating functionality or deciding where to add code. ---

# portal-tunnel codebase map

Portal is a zero-knowledge tunneling relay + local runtime: exposes local HTTP/TCP/UDP services through self-hosted or public relays with end-to-end tenant TLS, ECH SNI hiding, MITM self-probe, multi-hop routing, and x402 payments.

## Top-level packages - `sdk/` — **client side**. Tunnel exposure and relay API client, listener/session management, HTTP routing + proxying, MITM detection. Entry points: `sdk/expose.go`, `sdk/listener.go`, `sdk/http.go`, `sdk/proxy.go`, `sdk/mitm.go`. x402 route protection is applied here (`sdk/http.go`). - `portal/` — **relay side**. API/server lifecycle (`portal/api_server.go`, `portal/server.go`), leases, proxying, identity, keyless TLS/ECH, overlay transports, policy, telemetry, ACME. - `portal/discovery/` — relay gossip: `announce.go` (rate limiting), `refresher.go` (poll descriptors + `POST /discovery/announce` self-announce + peer refresh), `relayset.go` (validated pool, bans, route-planning state), `relaystate.go`, `mols.go` (route scoring). - `portal/x402/` — payment gating: `handler.go`, `payment.go`, `casper.go`, `x402.go`, embedded browser `client.js`. Facilitator mounts at `/api/x402` only when `X402_ENABLED`. - `types/` — **shared contracts**: protocol/API/data models, identity & transport types, x402 types, and public path constants (`types/paths.go`). `types/types.go` unmarshals the embedded `config.toml`/`registry.json`. Put shared constants and public path strings HERE. - `utils/` — shared **stateless** helpers: API encoding, command dispatch (`utils/cmd.go`), files, paths, HTTP, name/network/TLS normalization, snapshots. - `cmd/` — executables: `cmd/portal-tunnel` (client CLI), `cmd/relay-server` (relay + embedded SPA), `cmd/portal-loadtest` (`make load-test`), plus demo/payment apps. - `frontend/` — React + Tailwind SPA (Vite). Built and embedded into the relay binary at `cmd/relay-server/dist/app` (`//go:embed dist/*`). Dev server at `http://localhost:5173`; point at a live relay with `VITE_PORTAL_API_BASE_URL`. - `docs/` — SvelteKit docs site (`make build-docs`, uses bun). - `extensions/vscode/` — VS Code extension (start/stop tunnel commands, relay/host/name settings).

## Root files - `config.toml` — embedded release version + protocol versions (via `manifest.go`). - `registry.json` — embedded default public relay list → `types.BootstrapRelays`. - `manifest.go` — `//go:embed` of the two files above. - `docker-compose.yml` / `Dockerfile` — relay container build/deploy.

## Where new code belongs (AGENTS.md) - Shared contract / constant / public path → `types/` (one owner, no duplication). - Stateless transform reused across packages → `utils/`. - Stateful/domain logic → its real owner in `sdk/` or `portal/` (resolve complexity in the lowest coherent owner, expose minimum surface). - Avoid speculative abstraction, wrappers with no boundary, and dead fields; remove stale code while nearby.