Architecture Overview

System Design

PacketPilot is a three-product suite for network diagnostics. Each product is self-hosted and can run independently or together.

Products in Detail

PacketPilot Config (Windows EXE)

A PySide6 desktop application installed on a Windows workstation.

• Runs on: Windows 10/11
• Connectivity to devices: SSH (over LAN/console cable) and serial (USB-to-serial)
• Connectivity required: None — works fully offline
• Data stored locally: SQLite database on the workstation
• Credential storage: Encrypted at rest using a master password set on first launch
• Includes: PacketPilot Registry Docker services via docker compose up

Typical deployment: Install on an engineer's Windows laptop. Connect directly to devices over USB-to-serial or SSH over the local network. Registry starts automatically alongside Config.

PacketPilot Analyze (Docker Stack)

A Docker Compose stack running on a server or workstation.

Services:

| Service | Port | Purpose | |---------|------|---------| | frontend | 3000 | Web UI | | backend | 8000 | REST API | | postgres | 5432 | Case and findings storage | | ollama | 11434 | Local AI inference (Llama 3, Mistral, etc.) | | license-server | 9000 | License validation |

• Runs on: Linux with Docker, or Windows with WSL2 + Docker Desktop
• Connectivity required: None after initial Ollama model download
• AI: Ollama runs entirely locally. No calls to external AI APIs. Models are downloaded once and cached.

Typical deployment: Run on a small server or NUC at your facility. Accessible to engineers on the local network via browser.

PacketPilot Registry (Docker Stack)

A Docker Compose stack for asset inventory management. Bundled with Config and started automatically when Config runs docker compose up.

Services:

| Service | Port | Purpose | |---------|------|---------| | registry-web | 3001 | Web UI | | registry-api | 8001 | REST API | | postgres | 5433 | Asset storage |

• Runs on: Same Docker stack as Config (started automatically)
• Purpose: Persistent asset inventory across all sites. Populated automatically by Config discoveries.
• Value: Without Config, Registry is just a data-entry form. Its value comes from Config pushing discovered devices, sites, and zones automatically.

Typical deployment: Starts automatically when Config runs Docker Compose. Engineers browse assets at localhost:3001.

Deployment Scenarios

Scenario 1: Air-gapped industrial site

[PacketPilot Config] ── USB serial ──► Cisco Switch
       │
       │ (engineer's laptop, no internet)

[PacketPilot Analyze] ── Docker ──► Server (air-gapped)
       │
       │ (same subnet, no outbound)

Both products run without internet. Config connects to devices directly. Analyze stores cases and serves its web UI on the local network.

Scenario 2: Campus or data center

Engineer's Laptop
    │
    ├─► PacketPilot Config ──► SSH ──► Core switches (various vendors)
    │                                        │
    │                           ┌───────────┘
    │                           │ (devices pushed to inventory)
    │                           ▼
    │                     PacketPilot Registry
    │                     (site/zone/asset inventory)
    │                                        │
    │                                        │ findings export
    │                                        ▼
    └──────────────────────────────► PacketPilot Analyze
                                          (server rack)
                                                │
                                                ├──► Ollama (local AI)
                                                ├──► PostgreSQL
                                                └──► License server (local)

Config runs on laptops for on-site visits. Discovered devices populate Registry automatically. Analyze runs permanently in the server room. Engineers upload capture files from Config → Analyze for AI-assisted diagnosis.

License Server

The license server is embedded in the Analyze Docker bundle. It is not a hosted service — it runs as a container inside your stack on port 9000.

License flow:
1. First launch — Analyze generates a hardware ID from the server's MAC + hostname
2. Hardware ID + license key → license server (localhost:9000)
3. License server validates and caches the result locally for 30 days
4. If license server is unreachable: cached license used (grace period = 30 days)
5. After grace period expires: read-only mode until server is reachable again

For Config: the trial is machine-bound (based on Windows MachineGuid). It starts on first launch and cannot be reset by reinstalling. After the 30-day trial, a license key is required.

Data Flow

Config → Registry workflow

1. Engineer runs device discovery in Config
2. Config SSHs to each device, collects hostname, IP, vendor, model, serial
3. One click: push all devices to Registry
4. Devices appear in Registry under the correct site + zone
5. Asset inventory is now searchable and persistent

Config → Analyze workflow

1. Engineer runs bulk config capture in Config
2. Config produces a findings JSON or PDF report
3. Engineer opens Analyze web UI
4. Uploads the findings file as a new case
5. Analyze runs deterministic rules
6. Ollama explains the root cause in plain English
7. Engineer exports PDF report for ticketing

Analyze standalone workflow

1. Engineer captures traffic on a switch span port
2. Saves as .pcap or .pcapng
3. Uploads to Analyze via web UI or REST API
4. Deterministic rules check against CIS/NIST benchmarks
5. Ollama explains anomalies in context of the capture
6. PDF report generated with findings + AI explanation

Registry → Analyze enrichment

1. Config has pushed devices to Registry (site, zone, hostname, IP, vendor)
2. Engineer creates an Analyze case from a capture
3. Engineer references the asset hostname/IP from Registry
4. Analyze case is enriched with full asset context

Security Model

• Credentials: Stored locally in Config's SQLite DB, encrypted with a master password. Never transmitted to any external service.
• Analyze traffic: All internal. Ollama calls stay within the Docker network.
• License validation: Outbound call only to localhost:9000 (the license server container). No external license server.
• pcap files: Never leave the Analyze server. Processed entirely locally.
• Air-gap compatibility: Both products function without any internet connection after installation.