# starsmash29/fr_os-pblk architecture

> Architecture diagram of the GitHub repository starsmash29/fr_os-pblk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starsmash29/fr_os-pblk
- Repository: https://github.com/starsmash29/fr_os-pblk

## Overview

FR_OS is a local firewall-router operating system. Its main management workflow runs from an operator using the WebUI, through the unprivileged application and validated helper socket, to privileged configuration application and kernel/service enforcement. The graph also preserves documented security, monitoring, discovery, and network capabilities. Some branches are connected only where the README or SOURCE INDEX supports the relationship; unsampled implementations are represented by their existing paths.

Main entry points: [`src/frfw/helper/server.py`](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/helper/server.py) (Apply helper), [`src/frfw/webui/app.py`](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/app.py) (WebUI app), [`src/frfw/nft/builder.py`](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/nft/builder.py) (nftables rules), [`src/frfw/webui/routes`](https://github.com/starsmash29/fr_os-pblk/tree/main/src/frfw/webui/routes) (WebUI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Management plane"]
  node_webui["WebUI app<br/>[app.py]"]
  node_routes["WebUI routes"]
  node_config["Config loader<br/>[loader.py]"]
  node_webhelper["WebUI helper client<br/>[helper_client.py]"]
end

subgraph group_privilege["Privileged control"]
  node_socketclient["Socket client<br/>[client.py]"]
  node_helper["Apply helper<br/>[server.py]"]
  node_apply["Config apply<br/>[apply.py]"]
end

subgraph group_enforcement["Network enforcement"]
  node_nft["nftables rules<br/>[builder.py]"]
  node_xdp["XDP SNI filter<br/>[xdp_sni_filter.c]"]
  node_dns["DNS filtering<br/>[dns_service.py]"]
  node_wireguard["WireGuard VPN<br/>[wireguard.py]"]
end

subgraph group_security["Security services"]
  node_ztna["ZTNA access<br/>[ztna.py]"]
  node_aiids["Local AI IDS<br/>[engine.py]"]
  node_tlsfp["TLS fingerprinting<br/>[daemon.py]"]
  node_accounts["Accounts and MFA<br/>[admin_account.py]"]
  node_audit["Audit log<br/>[audit.py]"]
end

subgraph group_operations["Network operations"]
  node_iot["IoT discovery<br/>[scanner.py]"]
  node_metrics["Metrics exporter<br/>[metrics.py]"]
  node_surface["Attack surface<br/>[surface.py]"]
  node_appid["App identification<br/>[daemon.py]"]
end

node_operator(("Router operator"))

node_operator -->|"manages router"| node_webui
node_webui -->|"registers routes"| node_routes
node_routes -.->|"requests privileged actions"| node_webhelper
node_webhelper -->|"delegates socket calls"| node_socketclient
node_socketclient -->|"sends JSON requests"| node_helper
node_helper -->|"validates saved config"| node_config
node_helper -->|"invokes apply"| node_apply
node_apply -->|"validates configuration"| node_config
node_apply -->|"builds ruleset"| node_nft
node_helper -->|"configures enforcement"| node_nft
node_helper -.->|"controls DNS service"| node_dns
node_helper -.->|"controls XDP filtering"| node_xdp
node_helper -->|"authorizes clients"| node_ztna
node_nft -.->|"enforces timed access"| node_ztna
node_helper -->|"handles VPN actions"| node_wireguard
node_webui -->|"authenticates accounts"| node_accounts
node_webui -->|"records changes"| node_audit
node_aiids -.->|"quarantines sources"| node_nft
node_tlsfp -->|"receives ClientHello"| node_xdp
node_iot -.->|"isolates devices"| node_nft
node_appid -->|"observes DNS names"| node_dns
node_webui -.->|"exports metrics"| node_metrics
node_webui -.->|"presents exposure view"| node_surface
node_routes -->|"displays app usage"| node_appid

click node_webui "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/app.py"
click node_routes "https://github.com/starsmash29/fr_os-pblk/tree/main/src/frfw/webui/routes"
click node_config "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/config/loader.py"
click node_webhelper "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/helper_client.py"
click node_socketclient "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/helper/client.py"
click node_helper "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/helper/server.py"
click node_apply "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/apply.py"
click node_nft "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/nft/builder.py"
click node_xdp "https://github.com/starsmash29/fr_os-pblk/blob/main/bpf/xdp_sni_filter.c"
click node_dns "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/adblock/dns_service.py"
click node_wireguard "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/wireguard.py"
click node_ztna "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/ztna.py"
click node_aiids "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/ai_ids/engine.py"
click node_tlsfp "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/tlsfp/daemon.py"
click node_accounts "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/admin_account.py"
click node_audit "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/audit.py"
click node_iot "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/iot/scanner.py"
click node_metrics "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/metrics.py"
click node_surface "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/surface.py"
click node_appid "https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/appid/daemon.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_routes,node_config,node_webhelper toneBlue
class node_socketclient,node_helper,node_apply toneAmber
class node_nft,node_xdp,node_dns,node_wireguard,node_operator toneMint
class node_ztna,node_aiids,node_tlsfp,node_accounts,node_audit toneRose
class node_iot,node_metrics,node_surface,node_appid toneIndigo
```

## Components

### Management plane

- [WebUI app](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/app.py): `src/frfw/webui/app.py`
- [WebUI routes](https://github.com/starsmash29/fr_os-pblk/tree/main/src/frfw/webui/routes): `src/frfw/webui/routes`
- [Config loader](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/config/loader.py): `src/frfw/config/loader.py`
- [WebUI helper client](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/helper_client.py): `src/frfw/webui/helper_client.py`

### Privileged control

- [Socket client](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/helper/client.py): `src/frfw/helper/client.py`
- [Apply helper](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/helper/server.py): `src/frfw/helper/server.py`
- [Config apply](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/apply.py): `src/frfw/apply.py`

### Network enforcement

- [nftables rules](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/nft/builder.py): `src/frfw/nft/builder.py`
- [XDP SNI filter](https://github.com/starsmash29/fr_os-pblk/blob/main/bpf/xdp_sni_filter.c): `bpf/xdp_sni_filter.c`
- [DNS filtering](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/adblock/dns_service.py): `src/frfw/adblock/dns_service.py`
- [WireGuard VPN](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/wireguard.py): `src/frfw/wireguard.py`

### Security services

- [ZTNA access](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/ztna.py): `src/frfw/ztna.py`
- [Local AI IDS](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/ai_ids/engine.py): `src/frfw/ai_ids/engine.py`
- [TLS fingerprinting](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/tlsfp/daemon.py): `src/frfw/tlsfp/daemon.py`
- [Accounts and MFA](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/admin_account.py): `src/frfw/admin_account.py`
- [Audit log](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/webui/audit.py): `src/frfw/webui/audit.py`

### Network operations

- [IoT discovery](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/iot/scanner.py): `src/frfw/iot/scanner.py`
- [Metrics exporter](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/metrics.py): `src/frfw/metrics.py`
- [Attack surface](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/surface.py): `src/frfw/surface.py`
- [App identification](https://github.com/starsmash29/fr_os-pblk/blob/main/src/frfw/appid/daemon.py): `src/frfw/appid/daemon.py`

### Other components

- **Router operator**

## Connections

- Router operator → WebUI app: manages router (evidence: `README.md`)
- WebUI app → WebUI routes: registers routes (evidence: `src/frfw/webui/app.py`)
- WebUI routes → WebUI helper client: requests privileged actions (evidence: `src/frfw/webui/routes/apps.py`)
- WebUI helper client → Socket client: delegates socket calls (evidence: `src/frfw/webui/helper_client.py`)
- Socket client → Apply helper: sends JSON requests (evidence: `README.md`)
- Apply helper → Config loader: validates saved config (evidence: `src/frfw/helper/server.py`)
- Apply helper → Config apply: invokes apply (evidence: `src/frfw/helper/server.py`)
- Config apply → Config loader: validates configuration (evidence: `src/frfw/apply.py`)
- Config apply → nftables rules: builds ruleset (evidence: `src/frfw/apply.py`)
- Apply helper → nftables rules: configures enforcement (evidence: `README.md`)
- Apply helper → DNS filtering: controls DNS service (evidence: `src/frfw/helper/server.py`)
- Apply helper → XDP SNI filter: controls XDP filtering
- Apply helper → ZTNA access: authorizes clients (evidence: `src/frfw/helper/server.py`)
- nftables rules → ZTNA access: enforces timed access
- Apply helper → WireGuard VPN: handles VPN actions (evidence: `README.md`)
- WebUI app → Accounts and MFA: authenticates accounts (evidence: `src/frfw/webui/app.py`)
- WebUI app → Audit log: records changes (evidence: `src/frfw/webui/app.py`)
- Local AI IDS → nftables rules: quarantines sources (evidence: `README.md`)
- TLS fingerprinting → XDP SNI filter: receives ClientHello (evidence: `README.md`)
- IoT discovery → nftables rules: isolates devices (evidence: `README.md`)
- App identification → DNS filtering: observes DNS names (evidence: `src/frfw/appid/daemon.py`)
- WebUI app → Metrics exporter: exports metrics
- WebUI app → Attack surface: presents exposure view
- WebUI routes → App identification: displays app usage (evidence: `src/frfw/webui/routes/apps.py`)