Codebase Map Agent Skill

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.