Builder Case Study · AI-Assisted Development

Firewalla Local Manager

Local-only Firewalla management with CLI, TUI, React dashboard, and AI agent SDK — zero cloud dependency after initial pairing.

Active Python FastAPI React Bubble Tea Encipher SDK
13 Sessions
1.97M Tokens
0.55¢ Total Cost
4 Interfaces
The Problem

Bridging the Firewalla Local API Gap

Firewalla's cloud UI offers features — target lists, custom rules, traffic analysis — that are unavailable in the local web UI. The local API is undocumented, the cloud is the only UI for advanced configuration. For users who want local-only management for privacy, latency, or zero cloud dependency, this is a fundamental gap.

The core challenge: reverse-engineer the Encipher protocol used by the Firewalla mobile app for local API communication, build a comprehensive Python SDK, then layer a CLI, TUI, and web UI on top — all while maintaining feature parity with the cloud interface.

Industry Parallels: Local-first (DWeb) · SDK-first (Stripe/Twilio)

Approach & Architecture

Four-Layer Design

The system decomposes into four independent layers, each serving a distinct use case while sharing a common protocol foundation: 

# CLI — list all devices
firewalla devices list --json

# Python SDK — query alarms asynchronously
from firewalla_sdk import FirewallaClient
client = FirewallaClient(host="10.0.1.1", api_key="…")
async for alarm in client.stream_alarms(severity="critical"):
    print(f"[{alarm.timestamp}] {alarm.description}")
  1. Python SDK — Encipher protocol implementation for local API communication with Firewalla boxes. Device discovery, session management, encrypted messaging.
  2. CLI — Click-based command-line tool exposing every SDK function: devices, rules, alarms, target lists, system status.
  3. TUI — Go Bubble Tea terminal UI for live monitoring of network traffic, alarms, and device state.
  4. Server + Web UI — FastAPI backend serving a React/TypeScript dashboard for visual management of all Firewalla features.

System Architecture

REACT DASHBOARD TypeScript · Vite FASTAPI SERVER REST API · Async BUBBLE TEA TUI Go · Charmbracelet CLICK CLI Python · Click INTERFACES PYTHON SDK — ENCIPHER PROTOCOL Device Discovery · Session Mgmt · Encrypted Messaging · Rule Engine SDK LAYER ENCIPHER PROTOCOL FIREWALLA PURPLE Local API · Encipher Encrypted Channel NETWORK DEVICE sdk/ cli/ tui/ server/
Data Flow Diagram

Command → Encipher → Firewalla API Pipeline

COMMAND EXECUTION PIPELINE CLI / TUI User Command fwcli status 1 SDK libfw -> API Route Session Mngmt 2 ENCIPHER Local HTTPS Proxy TLS 1.3 3 FIREWALLA API REST Endpoint Network Config 4 Response → CLI output SDK LAYER DETAIL Auth Pairing Flow API Router Method Dispatch Encipher Auth Local TLS Tunnel Rate Limit Request Queue Cache Response Cache Logging Audit Trail N Step Request Flow Response Flow
Component Interaction Diagram

CLI ↔ TUI ↔ Server ↔ SDK ↔ Firewalla

COMPONENT INTERACTION MAP Solid = sync call · Dashed = async/event CLI LAYER cobra CLI Command Parser Bubble Tea TUI Interactive Dashboard Output Formatter JSON / Table View Config Manager fw config SERVER LAYER React Dashboard Local HTTP Server API Gateway REST Endpoints Session Manager Auth Tokens WebSocket Hub Real-time Updates SDK LAYER libfw Library Go Module Encipher Client Local TLS Proxy API Router Method Dispatch Error Handler Retry Logic FIREWALLA REST API HTTPS SSH Tunnel Remote Access mDNS Local Discovery HTTP push sync event REST resp Encipher Tunnel: Local HTTPS Proxy
Technology Stack

Languages & Frameworks

Languages
Python 3.11 Go TypeScript
Frameworks
FastAPI Click Bubble Tea React 18
Protocol
Encipher Reverse-Engineered
Frontend
React 18 TypeScript Vite
Architecture Decision Records

Key Decisions

ADR-001
Python for SDK over Go
Decision: Python 3.11

Firewalla's own tools use Python; Encipher protocol examples are Python-native; faster prototyping for API reverse-engineering. Go would add compilation complexity during the research phase.

ADR-002
Four Separate Interfaces
Decision: Decoupled UI layers

Separates concerns. CLI works offline with no display server. TUI provides real-time monitoring on headless boxes. Dashboard offers visual management from a browser. SDK enables agent automation independent of any UI.

ADR-003
FastAPI over Flask
Decision: FastAPI

Async-native for long-polling device events. Auto-generated OpenAPI spec enables direct agent tool generation from the API schema — critical for AI agent SDK consumers.

ADR-004
Bubble Tea TUI over Rich/Textual
Decision: Bubble Tea (Go)

Go binary compiles to a static ARM binary with no Python runtime dependency on constrained devices. Essential for running the TUI on Firewalla boxes themselves or Raspberry Pi gateways.

Session Timeline

How It Was Built

Session 1
Replicate Cloud Behavior Locally
244 messages · 745K tokens · $0.21

Understanding the Encipher protocol, mapping cloud features to local API. Reverse-engineered the mobile app's encrypted channel to discover endpoints for target lists, custom rules, and traffic analysis.

Session 2
TUI: Find Reusable OSS
206 messages · 298K tokens · $0.10

Searching for Bubble Tea component inspirations, evaluating terminal UI libraries. Compared Bubble Tea, Rich, Textual, and tui-rs for the live monitoring interface.

Session 3
CLI with TUI and Web UI
165 messages · 712K tokens · $0.20

Designing the comprehensive CLI that serves all three interfaces: Click-based commands for every SDK function, TUI for live monitoring, FastAPI server for the React dashboard.

Session 4
Add to GitHub DeepThink-Arch
44 messages · 58K tokens · $0.01

Project setup and GitHub publishing. Repository structuring, monorepo layout decisions, README documentation, and CI configuration.

Session 5
Research Internal APIs
24 messages · 154K tokens · $0.03

Deep research into Firewalla's undocumented internal API endpoints. Discovered additional monitoring data, box-to-cloud sync internals, and local-only diagnostic endpoints.

Outcome & Impact

Delivered Assets

Thirteen dedicated sessions produced a comprehensive local-only Firewalla management ecosystem. The SDK, CLI, TUI, and web UI are all functional and under active development. The Encipher protocol implementation enables any Python-based tool or AI agent to interact with Firewalla devices locally.

13
Sessions Dedicated
9
Key Decisions
1.97M
Tokens
0.55¢
Total Cost
SDK
Device/Rules/Targets
CLI
Full SDK Surface
TUI
Live Monitoring
Web UI
React Dashboard
Related Projects

Similar Case Studies

Security
Firewalla Local HA

Home Assistant integration for Firewalla. High-availability setup with automatic failover and redundant routing.

 Distributed Systems
Pan

Personal Area Network. Bootstraps a mesh of devices running Syncthing, NATS, SilverBullet, self-hosted git.

 Distributed Systems
Pollen

Self-organising mesh where workloads seed into cluster and organically scale without central coordinator.

 Enterprise Pattern
Local-First Architecture

Industry alignment: DWeb and Local-First movement — data stays on device, cloud is optional, user controls access.

For Enterprises

Want to Know How This Was Built?

This project represents reverse-engineering a closed protocol into a clean multi-interface SDK. Let's discuss how the same approach applies to your integration challenges.

Schedule a Strategy Consultation
or

For Founders

Building Local-First Infrastructure?

The patterns here — protocol reverse-engineering, multi-interface SDK design, local-first architecture — are directly applicable to your IoT or edge computing products.

Discuss Your Startup's AI Vision