# starsmash29/fr-os-ai-perimeter architecture

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

- Interactive diagram: https://gitdiagram.com/starsmash29/fr-os-ai-perimeter
- Repository: https://github.com/starsmash29/fr-os-ai-perimeter

## Overview

AI-Perimeter adds a model-assisted layer beside FR_OS: an administrator requests a firewall change or investigates an alert in the webUI; proposals are checked before review, while incident explanations use pseudonymised sensor evidence. The model client supports local and opt-in cloud providers. The README also documents optional per-device upload-byte reporting and evaluation suites, which are represented as separate capabilities. Relationships are limited to README statements and the shown source references; unsampled modules may have additional wiring.

Main entry points: [`src/ai_perimeter/orchestrator/pipeline.py`](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/pipeline.py) (Proposal Pipeline), [`src/ai_perimeter/service.py`](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/service.py) (Assist Service), [`src/ai_perimeter/webui/routes.py`](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/routes.py) (Screen Routes), [`src/ai_perimeter/eval/runner.py`](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/runner.py) (Evaluation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Admin Interface"]
  node_webui["AI-Perimeter Screen<br/>[__init__.py]"]
  node_routes["Screen Routes<br/>[routes.py]"]
  node_server["WebUI Server<br/>[server.py]"]
end

subgraph group_proposal["Change Proposals"]
  node_pipeline["Proposal Pipeline<br/>[pipeline.py]"]
  node_patch_ops["Patch Operations<br/>[ops.py]"]
  node_deny["Deny Rules<br/>[deny.py]"]
  node_prompt["Intent Prompt<br/>[prompt.py]"]
end

subgraph group_incident["Incident Insights"]
  node_evidence["Sensor Evidence<br/>[evidence.py]"]
  node_explain["Incident Explainer<br/>[explain.py]"]
  node_upload["Upload Byte Collector<br/>[collector.py]"]
end

subgraph group_runtime["Model Runtime"]
  node_assist_client["Assist Socket Client<br/>[assist_client.py]"]
  node_service["Assist Service<br/>[service.py]"]
  node_protocol["Socket Protocol<br/>[protocol.py]"]
  node_settings["Service Settings<br/>[settings.py]"]
  node_model_client["Provider Client<br/>[client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation Runner<br/>[runner.py]"]
  node_eval_cases["Intent Cases<br/>[cases.py]"]
  node_eval_generated["Generated Cases<br/>[generated.py]"]
  node_eval_sim["Network Simulator<br/>[sim.py]"]
  node_eval_incidents["Incident Evaluations<br/>[incidents.py]"]
end

node_admin(("Administrator"))
node_model_provider["Model Provider"]
node_fr_validator["FR_OS Validator"]
node_fr_apply["FR_OS Apply Helper"]
node_fr_sensors[("FR_OS Sensors")]

node_admin -->|"requests or reviews"| node_routes
node_webui -->|"registers routes"| node_routes
node_server -->|"registers screen"| node_webui
node_routes -->|"asks service"| node_assist_client
node_assist_client -->|"sends socket task"| node_service
node_assist_client -->|"encodes request"| node_protocol
node_service -->|"handles messages"| node_protocol
node_service -->|"loads settings"| node_settings
node_service -->|"builds proposal"| node_pipeline
node_service -->|"explains incident"| node_explain
node_service -.->|"calls model"| node_model_client
node_model_client -->|"sends chat request"| node_model_provider
node_routes -->|"requests proposal"| node_pipeline
node_pipeline -->|"builds messages"| node_prompt
node_pipeline -->|"parses and applies"| node_patch_ops
node_pipeline -->|"checks proposal"| node_deny
node_pipeline -->|"validates and lints"| node_fr_validator
node_admin -->|"approves change"| node_fr_apply
node_fr_apply -->|"validates before write"| node_fr_validator
node_routes -->|"builds evidence bundle"| node_evidence
node_evidence -->|"reads sensor files"| node_fr_sensors
node_explain -->|"uses bundle schema"| node_evidence
node_routes -->|"requests explanation"| node_explain
node_upload -.->|"collects byte data"| node_fr_sensors
node_eval_runner -->|"loads cases"| node_eval_cases
node_eval_runner -->|"loads generated suite"| node_eval_generated
node_eval_runner -->|"runs incident suite"| node_eval_incidents
node_eval_runner -->|"evaluates proposals"| node_pipeline
node_eval_runner -->|"evaluates providers"| node_model_client
node_eval_cases -->|"checks network behavior"| node_eval_sim
node_eval_generated -->|"checks generated cases"| node_eval_sim
node_eval_incidents -->|"evaluates evidence"| node_evidence
node_eval_incidents -->|"evaluates explanations"| node_explain

click node_webui "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/__init__.py"
click node_routes "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/routes.py"
click node_server "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/server.py"
click node_assist_client "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/assist_client.py"
click node_service "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/service.py"
click node_protocol "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/protocol.py"
click node_settings "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/settings.py"
click node_model_client "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/client.py"
click node_pipeline "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/pipeline.py"
click node_patch_ops "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/ops.py"
click node_deny "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/deny.py"
click node_prompt "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/prompt.py"
click node_evidence "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/incident/evidence.py"
click node_explain "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/incident/explain.py"
click node_upload "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/upload/collector.py"
click node_eval_runner "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/runner.py"
click node_eval_cases "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/cases.py"
click node_eval_generated "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/generated.py"
click node_eval_sim "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/sim.py"
click node_eval_incidents "https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/incidents.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_server toneBlue
class node_pipeline,node_patch_ops,node_deny,node_prompt,node_fr_sensors toneAmber
class node_evidence,node_explain,node_upload toneMint
class node_assist_client,node_service,node_protocol,node_settings,node_model_client toneRose
class node_eval_runner,node_eval_cases,node_eval_generated,node_eval_sim,node_eval_incidents,node_admin,node_model_provider,node_fr_validator,node_fr_apply toneIndigo
```

## Components

### Admin Interface

- [AI-Perimeter Screen](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/__init__.py): `src/ai_perimeter/webui/__init__.py`
- [Screen Routes](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/routes.py): `src/ai_perimeter/webui/routes.py`
- [WebUI Server](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/webui/server.py): `src/ai_perimeter/webui/server.py`

### Change Proposals

- [Proposal Pipeline](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/pipeline.py): `src/ai_perimeter/orchestrator/pipeline.py`
- [Patch Operations](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/ops.py): `src/ai_perimeter/orchestrator/ops.py`
- [Deny Rules](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/deny.py): `src/ai_perimeter/orchestrator/deny.py`
- [Intent Prompt](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/orchestrator/prompt.py): `src/ai_perimeter/orchestrator/prompt.py`

### Incident Insights

- [Sensor Evidence](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/incident/evidence.py): `src/ai_perimeter/incident/evidence.py`
- [Incident Explainer](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/incident/explain.py): `src/ai_perimeter/incident/explain.py`
- [Upload Byte Collector](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/upload/collector.py): `src/ai_perimeter/upload/collector.py`

### Model Runtime

- [Assist Socket Client](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/assist_client.py): `src/ai_perimeter/assist_client.py`
- [Assist Service](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/service.py): `src/ai_perimeter/service.py`
- [Socket Protocol](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/protocol.py): `src/ai_perimeter/protocol.py`
- [Service Settings](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/settings.py): `src/ai_perimeter/settings.py`
- [Provider Client](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/client.py): `src/ai_perimeter/client.py`

### Evaluation

- [Evaluation Runner](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/runner.py): `src/ai_perimeter/eval/runner.py`
- [Intent Cases](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/cases.py): `src/ai_perimeter/eval/cases.py`
- [Generated Cases](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/generated.py): `src/ai_perimeter/eval/generated.py`
- [Network Simulator](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/sim.py): `src/ai_perimeter/eval/sim.py`
- [Incident Evaluations](https://github.com/starsmash29/fr-os-ai-perimeter/blob/main/src/ai_perimeter/eval/incidents.py): `src/ai_perimeter/eval/incidents.py`

### Other components

- **Administrator**
- **Model Provider**
- **FR_OS Validator**
- **FR_OS Apply Helper**
- **FR_OS Sensors**

## Connections

- Administrator → Screen Routes: requests or reviews (evidence: `README.md`)
- AI-Perimeter Screen → Screen Routes: registers routes (evidence: `src/ai_perimeter/webui/__init__.py`)
- WebUI Server → AI-Perimeter Screen: registers screen (evidence: `src/ai_perimeter/webui/server.py`)
- Screen Routes → Assist Socket Client: asks service (evidence: `src/ai_perimeter/webui/routes.py`)
- Assist Socket Client → Assist Service: sends socket task (evidence: `src/ai_perimeter/assist_client.py`)
- Assist Socket Client → Socket Protocol: encodes request (evidence: `src/ai_perimeter/assist_client.py`)
- Assist Service → Socket Protocol: handles messages (evidence: `src/ai_perimeter/service.py`)
- Assist Service → Service Settings: loads settings (evidence: `src/ai_perimeter/service.py`)
- Assist Service → Proposal Pipeline: builds proposal (evidence: `src/ai_perimeter/service.py`)
- Assist Service → Incident Explainer: explains incident (evidence: `src/ai_perimeter/service.py`)
- Assist Service → Provider Client: calls model (evidence: `src/ai_perimeter/service.py`)
- Provider Client → Model Provider: sends chat request (evidence: `README.md`)
- Screen Routes → Proposal Pipeline: requests proposal (evidence: `src/ai_perimeter/webui/routes.py`)
- Proposal Pipeline → Intent Prompt: builds messages (evidence: `src/ai_perimeter/orchestrator/pipeline.py`)
- Proposal Pipeline → Patch Operations: parses and applies (evidence: `src/ai_perimeter/orchestrator/pipeline.py`)
- Proposal Pipeline → Deny Rules: checks proposal (evidence: `src/ai_perimeter/orchestrator/pipeline.py`)
- Proposal Pipeline → FR_OS Validator: validates and lints (evidence: `src/ai_perimeter/orchestrator/pipeline.py`)
- Administrator → FR_OS Apply Helper: approves change (evidence: `README.md`)
- FR_OS Apply Helper → FR_OS Validator: validates before write
- Screen Routes → Sensor Evidence: builds evidence bundle (evidence: `src/ai_perimeter/webui/routes.py`)
- Sensor Evidence → FR_OS Sensors: reads sensor files (evidence: `src/ai_perimeter/incident/evidence.py`)
- Incident Explainer → Sensor Evidence: uses bundle schema (evidence: `src/ai_perimeter/incident/explain.py`)
- Screen Routes → Incident Explainer: requests explanation
- Upload Byte Collector → FR_OS Sensors: collects byte data
- Evaluation Runner → Intent Cases: loads cases (evidence: `src/ai_perimeter/eval/runner.py`)
- Evaluation Runner → Generated Cases: loads generated suite (evidence: `src/ai_perimeter/eval/runner.py`)
- Evaluation Runner → Incident Evaluations: runs incident suite (evidence: `src/ai_perimeter/eval/runner.py`)
- Evaluation Runner → Proposal Pipeline: evaluates proposals (evidence: `src/ai_perimeter/eval/runner.py`)
- Evaluation Runner → Provider Client: evaluates providers (evidence: `src/ai_perimeter/eval/runner.py`)
- Intent Cases → Network Simulator: checks network behavior (evidence: `src/ai_perimeter/eval/cases.py`)
- Generated Cases → Network Simulator: checks generated cases (evidence: `src/ai_perimeter/eval/generated.py`)
- Incident Evaluations → Sensor Evidence: evaluates evidence (evidence: `src/ai_perimeter/eval/incidents.py`)
- Incident Evaluations → Incident Explainer: evaluates explanations (evidence: `src/ai_perimeter/eval/incidents.py`)