# watashi199/purgeq architecture

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

- Interactive diagram: https://gitdiagram.com/watashi199/purgeq
- Repository: https://github.com/watashi199/purgeq

## Overview

PurgeQ is a browser extension for managing shared FACEIT player banlists. A user signs in through the popup, manages bans there or from FACEIT player cards, and sees cached ban data highlighted on FACEIT pages; popup changes are relayed to open tabs. Supabase provides authentication, shared-list data and server-side protections, while the hosted auth page mediates Discord OAuth and Turnstile. The README also documents import/export, settings, account-data controls and localization. Several backend and popup capabilities are documented but their implementations were not sampled, so those links are documented or left unverified.

Main entry points: [`extension/src/shared/supabase.ts`](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/supabase.ts) (Supabase client), [`extension/src/popup/popup.tsx`](https://github.com/watashi199/purgeq/blob/main/extension/src/popup/popup.tsx) (Popup manager), [`extension/src/shared/banlist-store.ts`](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/banlist-store.ts) (Banlist data layer), [`extension/src/background/service-worker.ts`](https://github.com/watashi199/purgeq/blob/main/extension/src/background/service-worker.ts) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension_ui["Extension experience"]
  node_popup["Popup manager<br/>[popup.tsx]"]
end

subgraph group_extension_runtime["Extension runtime"]
  node_inline_actions["Inline ban actions<br/>[content-script.ts]"]
  node_background["Background worker<br/>[service-worker.ts]"]
  node_banlist_store["Banlist data layer<br/>[banlist-store.ts]"]
  node_settings["User settings<br/>[settings.ts]"]
  node_localization["Extension localization<br/>[i18n.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_db_types["Database types<br/>[db.types.ts]"]
end

subgraph group_backend["Backend services"]
  node_database[("Banlist database")]
  node_stripe_webhook["Pro billing webhook<br/>[index.ts]"]
end

subgraph group_hosted_site["Hosted site"]
  node_landing["Marketing site"]
  node_auth_bridge["Auth bridge"]
end

node_user(("Extension user"))
node_faceit["FACEIT pages"]
node_local_storage[("Extension local storage")]
node_supabase_platform["Supabase platform"]
node_stripe["Stripe"]
node_discord["Discord OAuth"]
node_turnstile["Cloudflare Turnstile"]

node_user -->|"manages bans"| node_popup
node_faceit -->|"hosts cards"| node_inline_actions
node_inline_actions -->|"requests banlist"| node_background
node_background -->|"reads and mutates"| node_banlist_store
node_background -->|"notifies tabs"| node_inline_actions
node_popup -->|"loads banlist"| node_banlist_store
node_popup -->|"loads settings"| node_settings
node_popup -->|"authenticates"| node_supabase_client
node_popup -->|"translates UI"| node_localization
node_settings -->|"uses language defaults"| node_localization
node_banlist_store -->|"queries through"| node_supabase_client
node_supabase_client -->|"types client"| node_db_types
node_banlist_store -->|"caches banlist"| node_local_storage
node_settings -->|"stores preferences"| node_local_storage
node_supabase_client -->|"persists session"| node_local_storage
node_supabase_client -->|"connects to"| node_supabase_platform
node_supabase_platform -->|"serves data"| node_database
node_database -.->|"schema represented by"| node_db_types
node_stripe -->|"sends events"| node_stripe_webhook
node_stripe_webhook -->|"updates profiles"| node_database
node_user -.->|"visits"| node_landing
node_supabase_client -->|"launches auth flow"| node_auth_bridge
node_auth_bridge -->|"runs challenge"| node_turnstile
node_auth_bridge -->|"hands off OAuth"| node_supabase_platform
node_supabase_platform -->|"uses OAuth"| node_discord

click node_popup "https://github.com/watashi199/purgeq/blob/main/extension/src/popup/popup.tsx"
click node_inline_actions "https://github.com/watashi199/purgeq/blob/main/extension/src/content/content-script.ts"
click node_background "https://github.com/watashi199/purgeq/blob/main/extension/src/background/service-worker.ts"
click node_banlist_store "https://github.com/watashi199/purgeq/blob/main/extension/src/shared/banlist-store.ts"
click node_settings "https://github.com/watashi199/purgeq/blob/main/extension/src/shared/settings.ts"
click node_localization "https://github.com/watashi199/purgeq/blob/main/extension/src/shared/i18n.ts"
click node_supabase_client "https://github.com/watashi199/purgeq/blob/main/extension/src/shared/supabase.ts"
click node_db_types "https://github.com/watashi199/purgeq/blob/main/extension/src/shared/db.types.ts"
click node_database "https://github.com/watashi199/purgeq/tree/main/supabase/migrations"
click node_stripe_webhook "https://github.com/watashi199/purgeq/blob/main/supabase/functions/stripe-webhook/index.ts"
click node_landing "https://github.com/watashi199/purgeq/tree/main/landing"
click node_auth_bridge "https://github.com/watashi199/purgeq/tree/main/landing/auth"

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_popup,node_user toneBlue
class node_inline_actions,node_background,node_banlist_store,node_settings,node_localization,node_supabase_client,node_db_types,node_local_storage toneAmber
class node_database,node_stripe_webhook toneMint
class node_landing,node_auth_bridge toneRose
class node_faceit,node_supabase_platform,node_stripe,node_discord,node_turnstile toneIndigo
```

## Components

### Extension experience

- [Popup manager](https://github.com/watashi199/purgeq/blob/main/extension/src/popup/popup.tsx): `extension/src/popup/popup.tsx`

### Extension runtime

- [Inline ban actions](https://github.com/watashi199/purgeq/blob/main/extension/src/content/content-script.ts): `extension/src/content/content-script.ts`
- [Background worker](https://github.com/watashi199/purgeq/blob/main/extension/src/background/service-worker.ts): `extension/src/background/service-worker.ts`
- [Banlist data layer](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/banlist-store.ts): `extension/src/shared/banlist-store.ts`
- [User settings](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/settings.ts): `extension/src/shared/settings.ts`
- [Extension localization](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/i18n.ts): `extension/src/shared/i18n.ts`
- [Supabase client](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/supabase.ts): `extension/src/shared/supabase.ts`
- [Database types](https://github.com/watashi199/purgeq/blob/main/extension/src/shared/db.types.ts): `extension/src/shared/db.types.ts`

### Backend services

- [Banlist database](https://github.com/watashi199/purgeq/tree/main/supabase/migrations): `supabase/migrations`
- [Pro billing webhook](https://github.com/watashi199/purgeq/blob/main/supabase/functions/stripe-webhook/index.ts): `supabase/functions/stripe-webhook/index.ts`

### Hosted site

- [Marketing site](https://github.com/watashi199/purgeq/tree/main/landing): `landing`
- [Auth bridge](https://github.com/watashi199/purgeq/tree/main/landing/auth): `landing/auth`

### Other components

- **Extension user**
- **FACEIT pages**
- **Extension local storage**
- **Supabase platform**
- **Stripe**
- **Discord OAuth**
- **Cloudflare Turnstile**

## Connections

- Extension user → Popup manager: manages bans (evidence: `README.md`)
- FACEIT pages → Inline ban actions: hosts cards (evidence: `README.md`)
- Inline ban actions → Background worker: requests banlist (evidence: `extension/src/content/content-script.ts`)
- Background worker → Banlist data layer: reads and mutates (evidence: `extension/src/background/service-worker.ts`)
- Background worker → Inline ban actions: notifies tabs (evidence: `extension/src/background/service-worker.ts`)
- Popup manager → Banlist data layer: loads banlist (evidence: `extension/src/popup/popup.tsx`)
- Popup manager → User settings: loads settings (evidence: `extension/src/popup/popup.tsx`)
- Popup manager → Supabase client: authenticates (evidence: `extension/src/popup/popup.tsx`)
- Popup manager → Extension localization: translates UI (evidence: `extension/src/popup/popup.tsx`)
- User settings → Extension localization: uses language defaults (evidence: `extension/src/shared/settings.ts`)
- Banlist data layer → Supabase client: queries through (evidence: `extension/src/shared/banlist-store.ts`)
- Supabase client → Database types: types client (evidence: `extension/src/shared/supabase.ts`)
- Banlist data layer → Extension local storage: caches banlist (evidence: `extension/src/shared/banlist-store.ts`)
- User settings → Extension local storage: stores preferences (evidence: `extension/src/shared/settings.ts`)
- Supabase client → Extension local storage: persists session (evidence: `extension/src/shared/supabase.ts`)
- Supabase client → Supabase platform: connects to (evidence: `README.md`)
- Supabase platform → Banlist database: serves data (evidence: `README.md`)
- Banlist database → Database types: schema represented by
- Stripe → Pro billing webhook: sends events (evidence: `supabase/functions/stripe-webhook/index.ts`)
- Pro billing webhook → Banlist database: updates profiles (evidence: `supabase/functions/stripe-webhook/index.ts`)
- Extension user → Marketing site: visits (evidence: `README.md`)
- Supabase client → Auth bridge: launches auth flow (evidence: `extension/src/shared/supabase.ts`)
- Auth bridge → Cloudflare Turnstile: runs challenge (evidence: `README.md`)
- Auth bridge → Supabase platform: hands off OAuth (evidence: `README.md`)
- Supabase platform → Discord OAuth: uses OAuth (evidence: `README.md`)
