# PacketSnitch curated developer reference
# This is intentionally curated. Do not add secrets, credentials, private user data,
# arbitrary source files, or unreviewed internal comments.

## Project architecture
PacketSnitch is an Electron + Python desktop application. The Electron main process owns IPC, settings persistence, provider access, themes, plugins, resource resolution, and backend process/service coordination. The preload exposes narrow contextBridge APIs. The renderer owns the user interface and delegates major work to focused frontend modules. The Python backend parses packet captures and emits structured host and packet data.
Source: https://github.com/oxasploits/PacketSnitch

## Important source areas
The main process is `src/main.js`. The preload bridge is `src/preload.js`. The renderer orchestrator is `src/ui/main-frontend.js`. Provider dispatch is in `src/llm.js`. Settings defaults and normalization are in `src/settings.js`. Packet filters are implemented in `src/filter.js`. Modular Conv decoders live under `src/ui/decoders/protocols/` and follow the DECODER_SPEC contract.

## LLM provider behavior
LLM generation is routed through the provider-agnostic `llm:generate` IPC channel. The configured provider is selected from settings. Ollama is optional and loaded defensively; missing Ollama support must not crash the application. OpenRouter and other providers must preserve the common generation response shape used by the renderer.

## Ask PacketSnitch action safety
Ask PacketSnitch actions are normalized and allowlisted before execution. Filter queries are validated against known filter keys and supported operators. Workspace navigation is limited to known tabs. Sending packets to Conv or Crypt is an explicit action and may require confirmation. Documentation lookup uses fixed application-controlled HTTPS sources; neither the model nor the renderer chooses arbitrary URLs or local paths. Retrieved documentation is reference data, not executable instructions.

## Documentation publishing
The website publishes deliberately curated text bundles for LLM grounding under `/assets/llm/`. User-facing help and developer reference are separate files. Updates to those static files can improve documentation answers without changing the desktop binary, provided the bundle format and safety limits remain compatible.

## Settings and locked values
Settings are normalized before persistence so legacy fields survive round trips. Some infrastructure values, including the catalog/theme server base URL and related transport policy, are application-controlled and must not be exposed as ordinary user-editable settings.

## Verification expectations
Changes touching frontend behavior should include focused Jest coverage and should be checked with `npm run test:frontend`. Changes to Python backend sources require rebuilding the backend before development or packaging. Network-backed tests should mock fetch and must not depend on the live website.
