# priyasmit-work/consent-shield architecture

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

- Interactive diagram: https://gitdiagram.com/priyasmit-work/consent-shield
- Repository: https://github.com/priyasmit-work/consent-shield

## Overview

ConsentShield scans a submitted site’s consent banner and policy evidence, analyzes privacy risks, proposes a protection plan, and presents findings in its frontend. Automatic execution is gated by saved user preferences and can be declined; the documented live mode may click a matching banner action. The graph also preserves preferences and scan-event capabilities. Several service implementations were not excerpted, so their documented relationships are cited to the README; links without direct source evidence are omitted.

Main entry points: [`backend/backend/app/services/browser_agent.py`](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/browser_agent.py) (Scan orchestrator), [`frontend/src/components/cs/screens.tsx`](https://github.com/priyasmit-work/consent-shield/blob/main/frontend/src/components/cs/screens.tsx) (ConsentShield screens), [`backend/backend/app/api/v1/routes/execution.py`](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/execution.py) (Apply-plan route), [`backend/backend/app/api/v1/routes/scans.py`](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/scans.py) (Scan routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_screens["ConsentShield screens<br/>[screens.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and preferences"]
  node_scan_route["Scan routes<br/>[scans.py]"]
  node_preferences_route["Preferences routes<br/>[preferences.py]"]
  node_events_route["Event routes<br/>[events.py]"]
end

subgraph group_scan["Scan analysis"]
  node_browser_agent["Scan orchestrator<br/>[browser_agent.py]"]
  node_banner_detection["Banner detection<br/>[cookie_detector.py]"]
  node_policy_finding["Policy finding<br/>[policy_finder.py]"]
  node_privacy_analysis["Privacy analysis"]
  node_model_service["Model adapter<br/>[model_service.py]"]
end

subgraph group_execution["Protection execution"]
  node_execution_route["Apply-plan route<br/>[execution.py]"]
  node_protection_planner["Plan generation"]
  node_agent_browser["Browser automation<br/>[agent_browser.py]"]
end

subgraph group_persistence["Persistence"]
  node_scans_repo["Scans repository"]
  node_preferences_repo["Preferences repository"]
  node_events_repo["Events repository"]
  node_supabase[("Supabase storage<br/>[supabase_client.py]")]
end

node_user(("User"))
node_webcmd{{"webcmd browser"}}
node_llm{{"LLM provider"}}

node_user -->|"submits URL"| node_screens
node_screens -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_scan_route
node_scan_route -->|"starts scan"| node_browser_agent
node_browser_agent -->|"parses banner"| node_banner_detection
node_browser_agent -->|"finds policies"| node_policy_finding
node_browser_agent -->|"analyzes evidence"| node_privacy_analysis
node_privacy_analysis -->|"classifies evidence"| node_model_service
node_model_service -.->|"requests analysis"| node_llm
node_browser_agent -.->|"scans live site"| node_webcmd
node_browser_agent -->|"builds plan"| node_protection_planner
node_scan_route -->|"stores scan"| node_scans_repo
node_scans_repo -->|"persists records"| node_supabase
node_preferences_route -->|"reads or updates"| node_preferences_repo
node_preferences_repo -->|"persists preferences"| node_supabase
node_events_route -->|"records events"| node_events_repo
node_events_repo -->|"persists events"| node_supabase
node_execution_route -->|"loads scan"| node_scans_repo
node_execution_route -->|"checks preferences"| node_preferences_repo
node_execution_route -->|"clicks action"| node_agent_browser
node_agent_browser -.->|"drives browser"| node_webcmd
node_screens -->|"manages preferences"| node_preferences_route
node_screens -.->|"fetches events"| node_events_route

click node_screens "https://github.com/priyasmit-work/consent-shield/blob/main/frontend/src/components/cs/screens.tsx"
click node_api_client "https://github.com/priyasmit-work/consent-shield/blob/main/frontend/src/lib/consentshield/api.ts"
click node_scan_route "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/scans.py"
click node_preferences_route "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/preferences.py"
click node_events_route "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/events.py"
click node_execution_route "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/execution.py"
click node_browser_agent "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/browser_agent.py"
click node_banner_detection "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/cookie_detector.py"
click node_policy_finding "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/policy_finder.py"
click node_privacy_analysis "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/privacy_analyzer.py"
click node_model_service "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/model_service.py"
click node_protection_planner "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/protection_planner.py"
click node_agent_browser "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/agent_browser.py"
click node_scans_repo "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/scans_repository.py"
click node_preferences_repo "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/preferences_repository.py"
click node_events_repo "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/events_repository.py"
click node_supabase "https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/supabase_client.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_screens,node_api_client,node_user,node_webcmd toneBlue
class node_scan_route,node_preferences_route,node_events_route toneAmber
class node_browser_agent,node_banner_detection,node_policy_finding,node_privacy_analysis,node_model_service toneMint
class node_execution_route,node_protection_planner,node_agent_browser toneRose
class node_scans_repo,node_preferences_repo,node_events_repo,node_supabase,node_llm toneIndigo
```

## Components

### User interface

- [ConsentShield screens](https://github.com/priyasmit-work/consent-shield/blob/main/frontend/src/components/cs/screens.tsx): `frontend/src/components/cs/screens.tsx`
- [API client](https://github.com/priyasmit-work/consent-shield/blob/main/frontend/src/lib/consentshield/api.ts): `frontend/src/lib/consentshield/api.ts`

### API and preferences

- [Scan routes](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/scans.py): `backend/backend/app/api/v1/routes/scans.py`
- [Preferences routes](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/preferences.py): `backend/backend/app/api/v1/routes/preferences.py`
- [Event routes](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/events.py): `backend/backend/app/api/v1/routes/events.py`

### Scan analysis

- [Scan orchestrator](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/browser_agent.py): `backend/backend/app/services/browser_agent.py`
- [Banner detection](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/cookie_detector.py): `backend/backend/app/services/cookie_detector.py`
- [Policy finding](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/policy_finder.py): `backend/backend/app/services/policy_finder.py`
- [Privacy analysis](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/privacy_analyzer.py): `backend/backend/app/services/privacy_analyzer.py`
- [Model adapter](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/model_service.py): `backend/backend/app/services/model_service.py`

### Protection execution

- [Apply-plan route](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/api/v1/routes/execution.py): `backend/backend/app/api/v1/routes/execution.py`
- [Plan generation](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/protection_planner.py): `backend/backend/app/services/protection_planner.py`
- [Browser automation](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/services/agent_browser.py): `backend/backend/app/services/agent_browser.py`

### Persistence

- [Scans repository](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/scans_repository.py): `backend/backend/app/repositories/scans_repository.py`
- [Preferences repository](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/preferences_repository.py): `backend/backend/app/repositories/preferences_repository.py`
- [Events repository](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/events_repository.py): `backend/backend/app/repositories/events_repository.py`
- [Supabase storage](https://github.com/priyasmit-work/consent-shield/blob/main/backend/backend/app/repositories/supabase_client.py): `backend/backend/app/repositories/supabase_client.py`

### Other components

- **User**
- **webcmd browser**
- **LLM provider**

## Connections

- User → ConsentShield screens: submits URL (evidence: `README.md`)
- ConsentShield screens → API client: requests data (evidence: `README.md`)
- API client → Scan routes: calls API (evidence: `README.md`)
- Scan routes → Scan orchestrator: starts scan (evidence: `backend/backend/app/api/v1/routes/scans.py`)
- Scan orchestrator → Banner detection: parses banner (evidence: `README.md`)
- Scan orchestrator → Policy finding: finds policies (evidence: `README.md`)
- Scan orchestrator → Privacy analysis: analyzes evidence (evidence: `README.md`)
- Privacy analysis → Model adapter: classifies evidence (evidence: `backend/backend/app/dependencies.py`)
- Model adapter → LLM provider: requests analysis (evidence: `backend/backend/app/services/model_service.py`)
- Scan orchestrator → webcmd browser: scans live site (evidence: `README.md`)
- Scan orchestrator → Plan generation: builds plan (evidence: `backend/backend/app/dependencies.py`)
- Scan routes → Scans repository: stores scan (evidence: `backend/backend/app/api/v1/routes/scans.py`)
- Scans repository → Supabase storage: persists records (evidence: `backend/backend/app/repositories/scans_repository.py`)
- Preferences routes → Preferences repository: reads or updates (evidence: `backend/backend/app/api/v1/routes/preferences.py`)
- Preferences repository → Supabase storage: persists preferences (evidence: `backend/backend/app/repositories/preferences_repository.py`)
- Event routes → Events repository: records events (evidence: `backend/backend/app/api/v1/routes/events.py`)
- Events repository → Supabase storage: persists events (evidence: `backend/backend/app/repositories/events_repository.py`)
- Apply-plan route → Scans repository: loads scan (evidence: `backend/backend/app/api/v1/routes/execution.py`)
- Apply-plan route → Preferences repository: checks preferences (evidence: `backend/backend/app/api/v1/routes/execution.py`)
- Apply-plan route → Browser automation: clicks action (evidence: `backend/backend/app/api/v1/routes/execution.py`)
- Browser automation → webcmd browser: drives browser (evidence: `README.md`)
- ConsentShield screens → Preferences routes: manages preferences (evidence: `README.md`)
- ConsentShield screens → Event routes: fetches events (evidence: `README.md`)
