# syedkazmi14/squeek architecture

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

- Interactive diagram: https://gitdiagram.com/syedkazmi14/squeek
- Repository: https://github.com/syedkazmi14/squeek

## Overview

Squeek is a cross-device scam-awareness companion. On Windows, the observer reads the selected foreground app; the desktop assesses content locally and optionally with Jev, then presents and speaks advisory warnings. On iPhone, app and extension entry points check shared text, links, calls, messages, and screens; local rules and the shared backend support warnings and synced incidents. The README documents broader account, block-list, and family-helper sync capabilities. Several implementation files were not sampled, so their internal call paths are left unasserted.

Main entry points: [`apps/desktop/src/main/main.ts`](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/main.ts) (Desktop coordinator), [`apps/ios/Squeek/Views/RootView.swift`](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Squeek/Views/RootView.swift) (Squeek app), [`apps/ios/Shared/CheckService.swift`](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Shared/CheckService.swift) (Check service), [`apps/desktop/src/main/observer-client.ts`](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/observer-client.ts) (Observer client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Windows companion"]
  node_observer["Observer helper<br/>[Program.cs]"]
  node_observerclient["Observer client<br/>[observer-client.ts]"]
  node_desktopmain["Desktop coordinator<br/>[main.ts]"]
  node_desktopui["Review panel<br/>[renderer.ts]"]
  node_companion["Cursor companion<br/>[companion.ts]"]
  node_voice["Speech output<br/>[tts.ts]"]
end

subgraph group_detect["Assessment engines"]
  node_review["Action review<br/>[action-review.ts]"]
  node_desktopdetect["Desktop assessment<br/>[index.ts]"]
  node_jevclient["Jev transport<br/>[jev.ts]"]
  node_rulesengine["Shared rules<br/>[engine.ts]"]
  node_iosengine["On-device checks<br/>[LocalChecker.swift]"]
  node_linkanalysis["Link analysis<br/>[LinkAnalyzer.swift]"]
end

subgraph group_ios["iPhone protection"]
  node_iosapp["Squeek app<br/>[RootView.swift]"]
  node_share["Share checks"]
  node_safari["Safari checks"]
  node_screen["Screen guard"]
  node_calls["Call screening"]
  node_messages["SMS filtering"]
  node_checkservice["Check service<br/>[CheckService.swift]"]
  node_sharedstore[("Shared device store<br/>[SharedStore.swift]")]
  node_backend["Backend client<br/>[Backend.swift]"]
end

subgraph group_backend["Shared services"]
  node_supabase[("Supabase services<br/>[context.ts]")]
  node_assess["Text assessment<br/>[index.ts]"]
  node_callwebhook["Call webhook<br/>[index.ts]"]
  node_accounts["Account and sync"]
end

subgraph group_contracts["Shared contracts"]
  node_observationcontract["Observation schema<br/>[observation.ts]"]
end

node_user(("Older adult"))
node_windows["Windows apps"]
node_iosuser(("iPhone user"))

node_user -->|"uses"| node_windows
node_windows -->|"observed by"| node_observer
node_desktopmain -->|"controls"| node_observerclient
node_observerclient -->|"commands"| node_observer
node_observer -->|"emits schema"| node_observationcontract
node_observerclient -->|"parses"| node_observationcontract
node_desktopmain -->|"assesses"| node_desktopdetect
node_desktopmain -->|"configures"| node_jevclient
node_desktopdetect -->|"classifies"| node_jevclient
node_desktopmain -->|"requests review"| node_review
node_desktopmain -.->|"shows warnings"| node_desktopui
node_desktopmain -->|"updates"| node_companion
node_desktopmain -->|"speaks warnings"| node_voice
node_user -->|"uses"| node_iosapp
node_iosuser -->|"shares content"| node_share
node_share -->|"checks text or link"| node_checkservice
node_safari -->|"checks links"| node_checkservice
node_screen -->|"checks screen text"| node_iosengine
node_calls -->|"reads block list"| node_sharedstore
node_messages -.->|"filters unknown senders"| node_sharedstore
node_checkservice -->|"checks locally"| node_iosengine
node_iosengine -->|"analyzes links"| node_linkanalysis
node_checkservice -->|"requests checks"| node_backend
node_backend -.->|"calls assessment"| node_assess
node_assess -->|"uses auth and data"| node_supabase
node_iosapp -.->|"uses shared store"| node_sharedstore
node_iosapp -.->|"syncs account data"| node_accounts
node_supabase -.->|"supports sync"| node_accounts
node_calls -.->|"reports calls"| node_callwebhook
node_callwebhook -->|"uses backend context"| node_supabase
node_iosapp -.->|"shares rule behavior"| node_rulesengine

click node_observer "https://github.com/syedkazmi14/squeek/blob/main/apps/windows-observer/Program.cs"
click node_observerclient "https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/observer-client.ts"
click node_desktopmain "https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/main.ts"
click node_desktopui "https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/renderer/renderer.ts"
click node_companion "https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/companion.ts"
click node_voice "https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/tts.ts"
click node_review "https://github.com/syedkazmi14/squeek/blob/main/packages/detection/src/action-review.ts"
click node_desktopdetect "https://github.com/syedkazmi14/squeek/blob/main/packages/detection/src/index.ts"
click node_jevclient "https://github.com/syedkazmi14/squeek/blob/main/packages/providers/src/jev.ts"
click node_rulesengine "https://github.com/syedkazmi14/squeek/blob/main/packages/rules/src/engine.ts"
click node_iosapp "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Squeek/Views/RootView.swift"
click node_share "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/ShareExtension/ShareViewController.swift"
click node_safari "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SafariExtension/SafariWebExtensionHandler.swift"
click node_screen "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/ScreenGuardExtension/SampleHandler.swift"
click node_calls "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/CallDirectoryExtension/CallDirectoryHandler.swift"
click node_messages "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/MessageFilterExtension/MessageFilterExtension.swift"
click node_checkservice "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Shared/CheckService.swift"
click node_iosengine "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/LocalChecker.swift"
click node_linkanalysis "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/LinkAnalyzer.swift"
click node_sharedstore "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/SharedStore.swift"
click node_backend "https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Shared/Backend.swift"
click node_supabase "https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/_shared/context.ts"
click node_assess "https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/assess-text/index.ts"
click node_callwebhook "https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/call-webhook/index.ts"
click node_accounts "https://github.com/syedkazmi14/squeek/tree/main/supabase/functions"
click node_observationcontract "https://github.com/syedkazmi14/squeek/blob/main/packages/contracts/src/observation.ts"

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_observer,node_observerclient,node_desktopmain,node_desktopui,node_companion,node_voice,node_iosuser toneBlue
class node_review,node_desktopdetect,node_jevclient,node_rulesengine,node_iosengine,node_linkanalysis toneAmber
class node_iosapp,node_share,node_safari,node_screen,node_calls,node_messages,node_checkservice,node_sharedstore,node_backend toneMint
class node_supabase,node_assess,node_callwebhook,node_accounts toneRose
class node_observationcontract,node_user,node_windows toneIndigo
```

## Components

### Windows companion

- [Observer helper](https://github.com/syedkazmi14/squeek/blob/main/apps/windows-observer/Program.cs): `apps/windows-observer/Program.cs`
- [Observer client](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/observer-client.ts): `apps/desktop/src/main/observer-client.ts`
- [Desktop coordinator](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/main.ts): `apps/desktop/src/main/main.ts`
- [Review panel](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/renderer/renderer.ts): `apps/desktop/src/renderer/renderer.ts`
- [Cursor companion](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/companion.ts): `apps/desktop/src/main/companion.ts`
- [Speech output](https://github.com/syedkazmi14/squeek/blob/main/apps/desktop/src/main/tts.ts): `apps/desktop/src/main/tts.ts`

### Assessment engines

- [Action review](https://github.com/syedkazmi14/squeek/blob/main/packages/detection/src/action-review.ts): `packages/detection/src/action-review.ts`
- [Desktop assessment](https://github.com/syedkazmi14/squeek/blob/main/packages/detection/src/index.ts): `packages/detection/src/index.ts`
- [Jev transport](https://github.com/syedkazmi14/squeek/blob/main/packages/providers/src/jev.ts): `packages/providers/src/jev.ts`
- [Shared rules](https://github.com/syedkazmi14/squeek/blob/main/packages/rules/src/engine.ts): `packages/rules/src/engine.ts`
- [On-device checks](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/LocalChecker.swift): `apps/ios/SqueekCore/Sources/SqueekCore/LocalChecker.swift`
- [Link analysis](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/LinkAnalyzer.swift): `apps/ios/SqueekCore/Sources/SqueekCore/LinkAnalyzer.swift`

### iPhone protection

- [Squeek app](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Squeek/Views/RootView.swift): `apps/ios/Squeek/Views/RootView.swift`
- [Share checks](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/ShareExtension/ShareViewController.swift): `apps/ios/ShareExtension/ShareViewController.swift`
- [Safari checks](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SafariExtension/SafariWebExtensionHandler.swift): `apps/ios/SafariExtension/SafariWebExtensionHandler.swift`
- [Screen guard](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/ScreenGuardExtension/SampleHandler.swift): `apps/ios/ScreenGuardExtension/SampleHandler.swift`
- [Call screening](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/CallDirectoryExtension/CallDirectoryHandler.swift): `apps/ios/CallDirectoryExtension/CallDirectoryHandler.swift`
- [SMS filtering](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/MessageFilterExtension/MessageFilterExtension.swift): `apps/ios/MessageFilterExtension/MessageFilterExtension.swift`
- [Check service](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Shared/CheckService.swift): `apps/ios/Shared/CheckService.swift`
- [Shared device store](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/SqueekCore/Sources/SqueekCore/SharedStore.swift): `apps/ios/SqueekCore/Sources/SqueekCore/SharedStore.swift`
- [Backend client](https://github.com/syedkazmi14/squeek/blob/main/apps/ios/Shared/Backend.swift): `apps/ios/Shared/Backend.swift`

### Shared services

- [Supabase services](https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/_shared/context.ts): `supabase/functions/_shared/context.ts`
- [Text assessment](https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/assess-text/index.ts): `supabase/functions/assess-text/index.ts`
- [Call webhook](https://github.com/syedkazmi14/squeek/blob/main/supabase/functions/call-webhook/index.ts): `supabase/functions/call-webhook/index.ts`
- [Account and sync](https://github.com/syedkazmi14/squeek/tree/main/supabase/functions): `supabase/functions`

### Shared contracts

- [Observation schema](https://github.com/syedkazmi14/squeek/blob/main/packages/contracts/src/observation.ts): `packages/contracts/src/observation.ts`

### Other components

- **Older adult**
- **Windows apps**
- **iPhone user**

## Connections

- Older adult → Windows apps: uses (evidence: `README.md`)
- Windows apps → Observer helper: observed by (evidence: `README.md`)
- Desktop coordinator → Observer client: controls (evidence: `apps/desktop/src/main/main.ts`)
- Observer client → Observer helper: commands (evidence: `apps/desktop/src/main/observer-client.ts`)
- Observer helper → Observation schema: emits schema (evidence: `apps/windows-observer/Program.cs`)
- Observer client → Observation schema: parses (evidence: `apps/desktop/src/main/observer-client.ts`)
- Desktop coordinator → Desktop assessment: assesses (evidence: `apps/desktop/src/main/main.ts`)
- Desktop coordinator → Jev transport: configures (evidence: `apps/desktop/src/main/main.ts`)
- Desktop assessment → Jev transport: classifies (evidence: `packages/detection/src/index.ts`)
- Desktop coordinator → Action review: requests review (evidence: `packages/detection/src/action-review.ts`)
- Desktop coordinator → Review panel: shows warnings (evidence: `README.md`)
- Desktop coordinator → Cursor companion: updates (evidence: `apps/desktop/src/main/main.ts`)
- Desktop coordinator → Speech output: speaks warnings (evidence: `apps/desktop/src/main/main.ts`)
- Older adult → Squeek app: uses (evidence: `README.md`)
- iPhone user → Share checks: shares content (evidence: `apps/ios/ShareExtension/ShareViewController.swift`)
- Share checks → Check service: checks text or link (evidence: `apps/ios/ShareExtension/ShareViewController.swift`)
- Safari checks → Check service: checks links (evidence: `apps/ios/SafariExtension/SafariWebExtensionHandler.swift`)
- Screen guard → On-device checks: checks screen text (evidence: `apps/ios/ScreenGuardExtension/SampleHandler.swift`)
- Call screening → Shared device store: reads block list (evidence: `apps/ios/CallDirectoryExtension/CallDirectoryHandler.swift`)
- SMS filtering → Shared device store: filters unknown senders (evidence: `README.md`)
- Check service → On-device checks: checks locally (evidence: `apps/ios/Shared/CheckService.swift`)
- On-device checks → Link analysis: analyzes links (evidence: `apps/ios/SqueekCore/Sources/SqueekCore/LocalChecker.swift`)
- Check service → Backend client: requests checks (evidence: `apps/ios/Shared/CheckService.swift`)
- Backend client → Text assessment: calls assessment (evidence: `README.md`)
- Text assessment → Supabase services: uses auth and data (evidence: `supabase/functions/assess-text/index.ts`)
- Squeek app → Shared device store: uses shared store (evidence: `README.md`)
- Squeek app → Account and sync: syncs account data (evidence: `README.md`)
- Supabase services → Account and sync: supports sync (evidence: `README.md`)
- Call screening → Call webhook: reports calls (evidence: `README.md`)
- Call webhook → Supabase services: uses backend context (evidence: `supabase/functions/call-webhook/index.ts`)
- Squeek app → Shared rules: shares rule behavior (evidence: `README.md`)
