# frankoslaw/stopslop architecture

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

- Interactive diagram: https://gitdiagram.com/frankoslaw/stopslop
- Repository: https://github.com/frankoslaw/stopslop

## Overview

StopSlop is an AI request-control product: clients send chat input through either a synchronous in-process transport or an HTTP gateway; policy enforcement evaluates input, manages permissions and quotas, forwards permitted requests, and checks replies. Separate capabilities include semantic classification, local or trusted fallback routing, policy administration, scripted demos, and a read-only operations dashboard. The graph follows documented and indexed relationships; unsampled implementation details are represented only where the README identifies the capability.

Main entry points: [`packages/stopslop/src/stopslop/policy.py`](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy.py) (Policy enforcement), [`packages/stopslop_demo/src/stopslop_demo/cli.py`](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/cli.py) (Chat demo), [`packages/stopslop/src/stopslop/router.py`](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/router.py) (SDK transport), [`packages/stopslop_proxy/src/stopslop_proxy/app.py`](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_proxy/src/stopslop_proxy/app.py) (HTTP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_sdk_transport["SDK transport<br/>[router.py]"]
  node_gateway["HTTP gateway<br/>[app.py]"]
end

subgraph group_policy["Policy and assessment"]
  node_enforcement["Policy enforcement<br/>[policy.py]"]
  node_policy_config["Policy definition<br/>[policy_file.py]"]
  node_policy_loader["Policy loading<br/>[policy_loader.py]"]
  node_policy_format["Policy formats<br/>[policy_format.py]"]
  node_policy_schema["Policy schema<br/>[policy_schema.py]"]
  node_rules["Pattern detection<br/>[rules.py]"]
  node_semantic["Semantic evaluation<br/>[evaluators.py]"]
  node_jev["Jev classifier<br/>[jev.py]"]
  node_laya["Laya classifier<br/>[laya.py]"]
  node_output["Output controls<br/>[output.py]"]
  node_permissions["Agent permissions<br/>[permissions.py]"]
end

subgraph group_state["Runtime state"]
  node_runtime["Quota and telemetry<br/>[runtime.py]"]
  node_repository[("SQLite state<br/>[repository.py]")]
end

subgraph group_ops["Operations and demo"]
  node_admin["Policy administration<br/>[adapt.py]"]
  node_preflight["Startup checks<br/>[preflight.py]"]
  node_demo["Chat demo<br/>[cli.py]"]
  node_scenarios["Demo scenarios<br/>[scenarios.py]"]
  node_spinner["Demo progress<br/>[spinner.py]"]
  node_dashboard["Terminal dashboard<br/>[top.py]"]
end

node_client(("SDK client"))
node_gateway_client(("Gateway client"))
node_upstream["Model provider"]

node_client -->|"sends chat"| node_sdk_transport
node_gateway_client -->|"posts chat"| node_gateway
node_settings -->|"configures"| node_sdk_transport
node_settings -->|"configures"| node_gateway
node_sdk_transport -->|"routes through"| node_enforcement
node_gateway -->|"routes through"| node_enforcement
node_enforcement -->|"loads policy"| node_policy_loader
node_policy_loader -->|"constructs"| node_policy_config
node_policy_loader -->|"reads format"| node_policy_format
node_policy_format -->|"normalizes"| node_policy_schema
node_policy_config -->|"validates"| node_policy_schema
node_enforcement -->|"scans input"| node_rules
node_enforcement -->|"assesses content"| node_semantic
node_jev -->|"implements evaluator"| node_semantic
node_laya -->|"implements evaluator"| node_semantic
node_enforcement -->|"checks replies"| node_output
node_enforcement -->|"authorizes operations"| node_permissions
node_enforcement -->|"reserves quota"| node_runtime
node_runtime -->|"persists state"| node_repository
node_sdk_transport -->|"forwards request"| node_upstream
node_gateway -->|"forwards request"| node_upstream
node_enforcement -.->|"selects fallback route"| node_upstream
node_admin -->|"updates policy"| node_policy_loader
node_admin -->|"stores overlay"| node_repository
node_demo -->|"loads settings"| node_settings
node_demo -->|"uses transport"| node_sdk_transport
node_demo -->|"checks readiness"| node_preflight
node_demo -->|"runs scenarios"| node_scenarios
node_demo -->|"shows progress"| node_spinner
node_dashboard -->|"reads state"| node_repository

click node_settings "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/config.py"
click node_sdk_transport "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/router.py"
click node_gateway "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_proxy/src/stopslop_proxy/app.py"
click node_enforcement "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy.py"
click node_policy_config "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_file.py"
click node_policy_loader "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_loader.py"
click node_policy_format "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_format.py"
click node_policy_schema "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_schema.py"
click node_rules "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/rules.py"
click node_semantic "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/evaluators.py"
click node_jev "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/jev.py"
click node_laya "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/laya.py"
click node_output "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/output.py"
click node_permissions "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/permissions.py"
click node_runtime "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/runtime.py"
click node_repository "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/repository.py"
click node_admin "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/adapt.py"
click node_preflight "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/preflight.py"
click node_demo "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/cli.py"
click node_scenarios "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/scenarios.py"
click node_spinner "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/spinner.py"
click node_dashboard "https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_top/src/stopslop_top/top.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_settings,node_sdk_transport,node_gateway,node_client,node_gateway_client toneBlue
class node_enforcement,node_policy_config,node_policy_loader,node_policy_format,node_policy_schema,node_rules,node_semantic,node_jev,node_laya,node_output,node_permissions toneAmber
class node_runtime,node_repository toneMint
class node_admin,node_preflight,node_demo,node_scenarios,node_spinner,node_dashboard toneRose
class node_upstream toneIndigo
```

## Components

### Client entry points

- [Runtime settings](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/config.py): `packages/stopslop/src/stopslop/config.py`
- [SDK transport](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/router.py): `packages/stopslop/src/stopslop/router.py`
- [HTTP gateway](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_proxy/src/stopslop_proxy/app.py): `packages/stopslop_proxy/src/stopslop_proxy/app.py`

### Policy and assessment

- [Policy enforcement](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy.py): `packages/stopslop/src/stopslop/policy.py`
- [Policy definition](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_file.py): `packages/stopslop/src/stopslop/policy_file.py`
- [Policy loading](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_loader.py): `packages/stopslop/src/stopslop/policy_loader.py`
- [Policy formats](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_format.py): `packages/stopslop/src/stopslop/policy_format.py`
- [Policy schema](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/policy_schema.py): `packages/stopslop/src/stopslop/policy_schema.py`
- [Pattern detection](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/rules.py): `packages/stopslop/src/stopslop/rules.py`
- [Semantic evaluation](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/evaluators.py): `packages/stopslop/src/stopslop/evaluators.py`
- [Jev classifier](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/jev.py): `packages/stopslop/src/stopslop/jev.py`
- [Laya classifier](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/laya.py): `packages/stopslop/src/stopslop/laya.py`
- [Output controls](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/output.py): `packages/stopslop/src/stopslop/output.py`
- [Agent permissions](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/permissions.py): `packages/stopslop/src/stopslop/permissions.py`

### Runtime state

- [Quota and telemetry](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/runtime.py): `packages/stopslop/src/stopslop/runtime.py`
- [SQLite state](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/repository.py): `packages/stopslop/src/stopslop/repository.py`

### Operations and demo

- [Policy administration](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/adapt.py): `packages/stopslop/src/stopslop/adapt.py`
- [Startup checks](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop/src/stopslop/preflight.py): `packages/stopslop/src/stopslop/preflight.py`
- [Chat demo](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/cli.py): `packages/stopslop_demo/src/stopslop_demo/cli.py`
- [Demo scenarios](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/scenarios.py): `packages/stopslop_demo/src/stopslop_demo/scenarios.py`
- [Demo progress](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_demo/src/stopslop_demo/spinner.py): `packages/stopslop_demo/src/stopslop_demo/spinner.py`
- [Terminal dashboard](https://github.com/frankoslaw/stopslop/blob/main/packages/stopslop_top/src/stopslop_top/top.py): `packages/stopslop_top/src/stopslop_top/top.py`

### Other components

- **SDK client**
- **Gateway client**
- **Model provider**

## Connections

- SDK client → SDK transport: sends chat (evidence: `README.md`)
- Gateway client → HTTP gateway: posts chat (evidence: `README.md`)
- Runtime settings → SDK transport: configures (evidence: `packages/stopslop/src/stopslop/router.py`)
- Runtime settings → HTTP gateway: configures (evidence: `packages/stopslop_proxy/src/stopslop_proxy/app.py`)
- SDK transport → Policy enforcement: routes through (evidence: `packages/stopslop/src/stopslop/router.py`)
- HTTP gateway → Policy enforcement: routes through (evidence: `packages/stopslop_proxy/src/stopslop_proxy/app.py`)
- Policy enforcement → Policy loading: loads policy (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Policy loading → Policy definition: constructs (evidence: `packages/stopslop/src/stopslop/policy_loader.py`)
- Policy loading → Policy formats: reads format (evidence: `packages/stopslop/src/stopslop/policy_loader.py`)
- Policy formats → Policy schema: normalizes (evidence: `packages/stopslop/src/stopslop/policy_format.py`)
- Policy definition → Policy schema: validates (evidence: `packages/stopslop/src/stopslop/policy_file.py`)
- Policy enforcement → Pattern detection: scans input (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Policy enforcement → Semantic evaluation: assesses content (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Jev classifier → Semantic evaluation: implements evaluator (evidence: `packages/stopslop/src/stopslop/jev.py`)
- Laya classifier → Semantic evaluation: implements evaluator (evidence: `packages/stopslop/src/stopslop/laya.py`)
- Policy enforcement → Output controls: checks replies (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Policy enforcement → Agent permissions: authorizes operations (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Policy enforcement → Quota and telemetry: reserves quota (evidence: `packages/stopslop/src/stopslop/policy.py`)
- Quota and telemetry → SQLite state: persists state (evidence: `packages/stopslop/src/stopslop/runtime.py`)
- SDK transport → Model provider: forwards request (evidence: `README.md`)
- HTTP gateway → Model provider: forwards request (evidence: `README.md`)
- Policy enforcement → Model provider: selects fallback route (evidence: `README.md`)
- Policy administration → Policy loading: updates policy (evidence: `packages/stopslop/src/stopslop/adapt.py`)
- Policy administration → SQLite state: stores overlay (evidence: `packages/stopslop/src/stopslop/adapt.py`)
- Chat demo → Runtime settings: loads settings (evidence: `packages/stopslop_demo/src/stopslop_demo/cli.py`)
- Chat demo → SDK transport: uses transport (evidence: `packages/stopslop_demo/src/stopslop_demo/cli.py`)
- Chat demo → Startup checks: checks readiness (evidence: `packages/stopslop_demo/src/stopslop_demo/cli.py`)
- Chat demo → Demo scenarios: runs scenarios (evidence: `packages/stopslop_demo/src/stopslop_demo/cli.py`)
- Chat demo → Demo progress: shows progress (evidence: `packages/stopslop_demo/src/stopslop_demo/cli.py`)
- Terminal dashboard → SQLite state: reads state (evidence: `packages/stopslop_top/src/stopslop_top/top.py`)
