Tunnels Behind the UI: How One Navigation Link Exposed Full-Stack Architecture

Mapping a Tunnel System: When One Navigation Link Unveils an Entire Architecture

The borisovai-admin project needed a critical feature: visibility into FRP (Fast Reverse Proxy) tunnels running behind the admin panel. The task seemed deceptively simple—add a navigation link to four HTML pages. But peeling back that single requirement revealed a full-stack implementation that would touch server architecture, create a new dashboard page, and update installation scripts.

Starting with the Navigation Trap

The first thing I did was update the HTML templates: index.html, tokens.html, projects.html, and dns.html. Adding a “Tunnels” link to each felt mechanical—until I realized every page needed identical navigation at exactly the same line positions (195–238). One typo, one character misaligned, and users would bounce between inconsistent interfaces. That’s when I understood: even navigation is an architectural decision, not just UI decoration.

The Backend Suddenly Mattered

With the frontend signposts in place, the backend needed to deliver. In server.js, I created two helper functions that became the foundation for everything that followed. readFrpsConfig parses the FRP server’s configuration file, while frpsDashboardRequest handles secure communication with the FRP dashboard. These weren’t just convenience wrappers—they abstracted away HTTP mechanics and created a testable interface.

Then came the endpoints. Four GET routes to feed the frontend: the FRP server health check—is it alive?; the active tunnels list with metadata about each connection; and the current configuration exposed as JSON. These endpoints are simple on the surface but hide a complexity: they talk to FRP’s dashboard API, handle timeouts gracefully, and return data in a shape the frontend expects.

The Installation Plot Twist

Unexpectedly, I discovered FRP wasn’t even installed in the standard deployment. The install-all.sh script needed updating. I made FRP an optional component—not everyone needs tunneling, but those who do should get a complete stack without manual tinkering. This decision reflected a larger philosophy: the system should be flexible enough for different use cases while remaining cohesive.

The Dashboard That Refreshes Itself

The new tunnels.html page became the visual payoff. A status card shows whether FRP is running. Below it, an active tunnels list updates every 10 seconds using simple polling—no WebSockets needed for this scale. And finally, a client config generator: input your parameters, see your ready-to-deploy frpc.toml rendered instantly.

The polling mechanism deserves a note: it’s a pattern many developers avoid, but for admin dashboards with small datasets and <10 second refresh windows, it’s pragmatic. Fewer moving parts, easier debugging, less infrastructure overhead.

What the Journey Taught

This work crystallized something important: small frontend changes often hide large architectural decisions. Investing an hour in upfront planning—mapping dependencies, identifying abstraction points, planning the endpoint contracts—saved days of integration rework later.

The tunnel system works now. But its real value isn’t the feature itself. It’s the pattern: frontend navigation drives backend contracts, which drive installation strategy, which feeds back into the frontend experience. That’s systems thinking in practice.

😄 Why did the FRP tunnel go to therapy? It had too many connections it couldn’t handle!