# created-by-the-creator/surfare-your-digital-safety-assistant architecture

> Architecture diagram of the GitHub repository created-by-the-creator/surfare-your-digital-safety-assistant, 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/created-by-the-creator/surfare-your-digital-safety-assistant
- Repository: https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant

## Overview

Surfare is an offline-first digital safety assistant: users submit messages, links, or images for local risk analysis, with consent-enabled online contextual analysis or reputation checks, then receive a classification and guidance. The repository also includes image/OCR and QR capabilities, feedback, and history/settings UI areas. The detector source supports the analysis flow; the sampled React app is only a placeholder, so UI-to-detector wiring is not established. Some capability links are documented in the README but their implementation was not sampled.

Main entry points: [`detectors/worker/index.js`](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/worker/index.js) (API route dispatcher), [`detectors/client/check-content.js`](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/client/check-content.js) (Content workflow), [`detectors/server/services/image.js`](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/image.js) (Image review service), [`detectors/lib/detection.js`](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/detection.js) (Message and URL detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_react["React app<br/>[App.jsx]"]
  node_analysis_ui["Analysis and results<br/>[Analyze.jsx]"]
  node_history_settings["History and settings<br/>[History.jsx]"]
end

subgraph group_local["Local analysis"]
  node_detector_entry["Detector exports<br/>[index.js]"]
  node_content_check["Content workflow<br/>[check-content.js]"]
  node_content_assess["Content assessment"]
  node_detection["Message and URL detection<br/>[detection.js]"]
  node_signal_evidence["Signals and evidence<br/>[safety-signals.js]"]
  node_sms_model["SMS classification<br/>[sms-model.js]"]
  node_assessment_fusion["Risk and semantic fusion"]
  node_guidance["Safety guidance<br/>[guidance.js]"]
  node_image_tools["Image processing and OCR<br/>[image-tools.js]"]
  node_image_provenance["Image provenance"]
  node_qr["QR analysis"]
end

subgraph group_online["Online analysis"]
  node_worker["API route dispatcher<br/>[index.js]"]
  node_semantic_service["Contextual analysis service<br/>[semantic.js]"]
  node_structured_provider["Structured AI provider<br/>[structured.js]"]
  node_reputation["Threat reputation check<br/>[reputation.js]"]
  node_image_service["Image review service<br/>[image.js]"]
end

subgraph group_support["Feedback and storage"]
  node_feedback_service["Feedback service<br/>[feedback.js]"]
  node_feedback_store["Feedback storage client<br/>[feedback-store.js]"]
end

node_user(("User"))
node_external_ai{{"AI provider"}}
node_external_reputation{{"Threat-checking service"}}
node_feedback_db[("Supabase storage")]

node_user -->|"uses"| node_react
node_react -.->|"presents"| node_analysis_ui
node_analysis_ui -.->|"submits content"| node_content_check
node_detector_entry -->|"exports"| node_content_check
node_content_check -->|"assesses locally"| node_content_assess
node_content_assess -->|"detects indicators"| node_detection
node_detection -->|"uses signals"| node_signal_evidence
node_detection -->|"classifies message"| node_sms_model
node_content_check -->|"fuses results"| node_assessment_fusion
node_assessment_fusion -.->|"guidance capability"| node_guidance
node_content_check -->|"posts optional checks"| node_worker
node_worker -->|"routes assess"| node_semantic_service
node_worker -->|"routes verify"| node_reputation
node_worker -->|"routes image review"| node_image_service
node_semantic_service -->|"generates assessment"| node_structured_provider
node_image_service -->|"generates image review"| node_structured_provider
node_semantic_service -->|"requests analysis"| node_external_ai
node_image_service -->|"requests image review"| node_external_ai
node_reputation -.->|"checks URLs"| node_external_reputation
node_image_tools -.->|"optional online review"| node_image_service
node_image_provenance -.->|"optional review"| node_image_service
node_qr -.->|"evaluates extracted content"| node_content_assess
node_feedback_store -.->|"submits feedback"| node_worker
node_worker -->|"routes feedback"| node_feedback_service
node_feedback_service -->|"writes or withdraws"| node_feedback_db
node_history_settings -.->|"feedback capability"| node_feedback_store

click node_react "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/App.jsx"
click node_analysis_ui "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/pages/Analyze.jsx"
click node_history_settings "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/pages/History.jsx"
click node_detector_entry "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/index.js"
click node_content_check "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/client/check-content.js"
click node_content_assess "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/content-assessment.js"
click node_detection "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/detection.js"
click node_signal_evidence "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/safety-signals.js"
click node_sms_model "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/sms-model.js"
click node_assessment_fusion "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/semantic-assessment.js"
click node_guidance "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/guidance.js"
click node_image_tools "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/image-tools.js"
click node_image_provenance "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/image-provenance.js"
click node_qr "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/tree/main/detectors/lib"
click node_worker "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/worker/index.js"
click node_semantic_service "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/semantic.js"
click node_structured_provider "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/providers/structured.js"
click node_reputation "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/reputation.js"
click node_image_service "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/image.js"
click node_feedback_service "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/feedback.js"
click node_feedback_store "https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/client/feedback-store.js"

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_react,node_analysis_ui,node_history_settings,node_user toneBlue
class node_detector_entry,node_content_check,node_content_assess,node_detection,node_signal_evidence,node_sms_model,node_assessment_fusion,node_guidance,node_image_tools,node_image_provenance,node_qr,node_feedback_db toneAmber
class node_worker,node_semantic_service,node_structured_provider,node_reputation,node_image_service toneMint
class node_feedback_service,node_feedback_store toneRose
class node_external_ai,node_external_reputation toneIndigo
```

## Components

### User experience

- [React app](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/App.jsx): `src/App.jsx`
- [Analysis and results](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/pages/Analyze.jsx): `src/pages/Analyze.jsx`
- [History and settings](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/src/pages/History.jsx): `src/pages/History.jsx`

### Local analysis

- [Detector exports](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/index.js): `detectors/index.js`
- [Content workflow](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/client/check-content.js): `detectors/client/check-content.js`
- [Content assessment](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/content-assessment.js): `detectors/lib/content-assessment.js`
- [Message and URL detection](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/detection.js): `detectors/lib/detection.js`
- [Signals and evidence](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/safety-signals.js): `detectors/lib/safety-signals.js`
- [SMS classification](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/sms-model.js): `detectors/lib/sms-model.js`
- [Risk and semantic fusion](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/semantic-assessment.js): `detectors/lib/semantic-assessment.js`
- [Safety guidance](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/guidance.js): `detectors/lib/guidance.js`
- [Image processing and OCR](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/image-tools.js): `detectors/lib/image-tools.js`
- [Image provenance](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/lib/image-provenance.js): `detectors/lib/image-provenance.js`
- [QR analysis](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/tree/main/detectors/lib): `detectors/lib`

### Online analysis

- [API route dispatcher](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/worker/index.js): `detectors/worker/index.js`
- [Contextual analysis service](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/semantic.js): `detectors/server/services/semantic.js`
- [Structured AI provider](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/providers/structured.js): `detectors/server/providers/structured.js`
- [Threat reputation check](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/reputation.js): `detectors/server/services/reputation.js`
- [Image review service](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/image.js): `detectors/server/services/image.js`

### Feedback and storage

- [Feedback service](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/server/services/feedback.js): `detectors/server/services/feedback.js`
- [Feedback storage client](https://github.com/created-by-the-creator/surfare-your-digital-safety-assistant/blob/main/detectors/client/feedback-store.js): `detectors/client/feedback-store.js`

### Other components

- **User**
- **AI provider**
- **Threat-checking service**
- **Supabase storage**

## Connections

- User → React app: uses
- React app → Analysis and results: presents
- Analysis and results → Content workflow: submits content
- Detector exports → Content workflow: exports (evidence: `detectors/index.js`)
- Content workflow → Content assessment: assesses locally (evidence: `detectors/client/check-content.js`)
- Content assessment → Message and URL detection: detects indicators (evidence: `detectors/lib/content-assessment.js`)
- Message and URL detection → Signals and evidence: uses signals (evidence: `detectors/lib/detection.js`)
- Message and URL detection → SMS classification: classifies message (evidence: `detectors/lib/detection.js`)
- Content workflow → Risk and semantic fusion: fuses results (evidence: `detectors/client/check-content.js`)
- Risk and semantic fusion → Safety guidance: guidance capability
- Content workflow → API route dispatcher: posts optional checks (evidence: `detectors/client/check-content.js`)
- API route dispatcher → Contextual analysis service: routes assess (evidence: `detectors/worker/index.js`)
- API route dispatcher → Threat reputation check: routes verify (evidence: `detectors/worker/index.js`)
- API route dispatcher → Image review service: routes image review (evidence: `detectors/worker/index.js`)
- Contextual analysis service → Structured AI provider: generates assessment (evidence: `detectors/server/services/semantic.js`)
- Image review service → Structured AI provider: generates image review (evidence: `detectors/server/services/image.js`)
- Contextual analysis service → AI provider: requests analysis
- Image review service → AI provider: requests image review
- Threat reputation check → Threat-checking service: checks URLs
- Image processing and OCR → Image review service: optional online review
- Image provenance → Image review service: optional review
- QR analysis → Content assessment: evaluates extracted content (evidence: `README.md`)
- Feedback storage client → API route dispatcher: submits feedback
- API route dispatcher → Feedback service: routes feedback (evidence: `detectors/worker/index.js`)
- Feedback service → Supabase storage: writes or withdraws (evidence: `detectors/server/services/feedback.js`)
- History and settings → Feedback storage client: feedback capability
