# chukssomzzy/adfriend architecture

> Architecture diagram of the GitHub repository chukssomzzy/adfriend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chukssomzzy/adfriend
- Repository: https://github.com/chukssomzzy/adfriend

## Overview

##### Project type and purpose
- This is a Chrome extension built with React, TypeScript, and Vite.
- It injects “quote” and “reminder” replacements into web pages and provides a popup UI (and possibly an options page) to manage reminders.

##### File structure
- Top-level:
- manifest.json (in public/) defines extension configuration
- build artifacts (adfriend.zip, build.crx) are packaged outputs
- index.html + Vite config handle bundling of the React app
- src/
- App.tsx, pages/ (DailyReminder.tsx, QuotePage.tsx) → Popup or Options UI
- components/ (reminderForm.tsx) → reusable UI bits
- scripts/
– content.js → content script that runs in the page context
– service-worker.js → background/service worker for event handling
– replacements/ & utils/ → logic for injecting quotes/reminders and managing state
- utils/ at root → shared helper functions

##### Extract insights from README
- Build steps: npm install → npm build
- After build, load the “build/” folder as an unpacked Chrome extension
- No backend server—entirely client-side and extension‐side logic

##### Detail
- Modules (e.g., quoteReplacement.js, reminderForm.tsx) as sub-components if granularity is needed.
- Don’t overlook the build pipeline (Vite) as it unifies TS → JS and bundles assets for Chrome.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Manifest Layer
    subgraph "Manifest Configuration"
        Manifest["manifest.json"]:::manifest
    end

    %% UI Layer
    subgraph "UI Layer"
        AppShell["App Shell\n(src/main.tsx, src/App.tsx)"]:::ui
        QuotePage["Quote Page\n(src/pages/QuotePage.tsx)"]:::ui
        DailyReminder["Daily Reminder Page\n(src/pages/DailyReminder.tsx)"]:::ui
        ReminderForm["Reminder Form Component\n(src/components/reminderForm.tsx)"]:::ui
        Styling["Styling\n(src/index.css)"]:::ui
    end

    %% Background Layer
    subgraph "Background Layer"
        ServiceWorker["Service Worker\n(src/scripts/service-worker.js)"]:::background
    end

    %% Content Script Layer
    subgraph "Content Script Layer"
        ContentScript["Content Script\n(src/scripts/content.js)"]:::content
        subgraph "Replacement Modules"
            QuoteReplacement["Quote Replacement\n(src/scripts/replacements/quoteReplacement.js)"]:::content
            ReminderReplacement["Reminder Replacement\n(src/scripts/replacements/reminderReplacement.js)"]:::content
        end
        subgraph "Content Helpers"
            ContentUtils1["Content Replacement Utils\n(src/scripts/utils/contentReplacement.js)"]:::content
            ContentUtils2["Content Replacement Manager\n(src/scripts/utils/contentReplacementManager.js)"]:::content
            AdReplacer["Ad Replacer\n(src/scripts/utils/adReplacer.js)"]:::content
            ConfigUtils["Config Utils\n(src/scripts/utils/config.js)"]:::content
            QuotesHelper["Quotes Helper\n(src/scripts/utils/quotes.js)"]:::content
            RemindersHelper["Reminders Helper\n(src/scripts/utils/reminders.js)"]:::content
        end
    end

    %% Data Store
    subgraph "Data Store (Chrome Storage API)"
        StorageAPI["Chrome Storage API"]:::storage
    end

    %% Build Toolchain
    subgraph "Build Toolchain & Config"
        ViteConfig["Vite Config\n(vite.config.ts)"]:::build
        TSConfig["TypeScript Configs\n(tsconfig.json, tsconfig.app.json, tsconfig.node.json)"]:::build
        EnvDecl["Env Declarations\n(src/vite-env.d.ts)"]:::build
    end

    %% Public & Packaging
    subgraph "Public & Packaging"
        HTMLTemplate["HTML Template\n(index.html)"]:::public
        BuildOutputs["Build Outputs\n(adfriend.zip, build.crx)"]:::public
        StaticAssets["Static Assets\n(src/assets/)"]:::public
        ManifestPublic["public/manifest.json"]:::public
    end

    %% Connections
    Manifest -->|"registers"| ServiceWorker
    Manifest -->|"registers"| ContentScript

    AppShell -->|"sendMessage"| ServiceWorker
    QuotePage -->|"sendMessage"| ServiceWorker
    DailyReminder -->|"sendMessage"| ServiceWorker
    ServiceWorker -->|"sendMessageResponse"| AppShell

    ServiceWorker -->|"chrome.storage.*"| StorageAPI
    ServiceWorker -->|"chrome.storage.*"| StorageAPI

    ContentScript -->|"getReminders/Quotes"| ServiceWorker
    ContentScript -->|"getReminders/Quotes"| StorageAPI
    QuoteReplacement --> ContentScript
    ReminderReplacement --> ContentScript
    ContentUtils1 --> ContentScript
    ContentUtils2 --> ContentScript
    AdReplacer --> ContentScript
    ConfigUtils --> ContentScript
    QuotesHelper --> ContentScript
    RemindersHelper --> ContentScript

    ViteConfig -->|compiles| AppShell
    ViteConfig -->|compiles| ServiceWorker
    ViteConfig -->|compiles| ContentScript
    TSConfig -->|type checks| AppShell
    TSConfig -->|type checks| ServiceWorker
    TSConfig -->|type checks| ContentScript
    EnvDecl -->|provides types| ViteConfig

    ViteConfig -->|outputs to| BuildOutputs
    HTMLTemplate -->|bundled into| BuildOutputs
    StaticAssets -->|included in| BuildOutputs
    ManifestPublic -->|packaged into| BuildOutputs

    %% Click Events
    click Manifest "https://github.com/chukssomzzy/adfriend/blob/master/public/manifest.json"
    click AppShell "https://github.com/chukssomzzy/adfriend/blob/master/src/main.tsx"
    click AppShell "https://github.com/chukssomzzy/adfriend/blob/master/src/App.tsx"
    click QuotePage "https://github.com/chukssomzzy/adfriend/blob/master/src/pages/QuotePage.tsx"
    click DailyReminder "https://github.com/chukssomzzy/adfriend/blob/master/src/pages/DailyReminder.tsx"
    click ReminderForm "https://github.com/chukssomzzy/adfriend/blob/master/src/components/reminderForm.tsx"
    click Styling "https://github.com/chukssomzzy/adfriend/blob/master/src/index.css"
    click ServiceWorker "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/service-worker.js"
    click ContentScript "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/content.js"
    click QuoteReplacement "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/replacements/quoteReplacement.js"
    click ReminderReplacement "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/replacements/reminderReplacement.js"
    click ContentUtils1 "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/contentReplacement.js"
    click ContentUtils2 "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/contentReplacementManager.js"
    click AdReplacer "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/adReplacer.js"
    click ConfigUtils "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/config.js"
    click QuotesHelper "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/quotes.js"
    click RemindersHelper "https://github.com/chukssomzzy/adfriend/blob/master/src/scripts/utils/reminders.js"
    click ViteConfig "https://github.com/chukssomzzy/adfriend/blob/master/vite.config.ts"
    click TSConfig "https://github.com/chukssomzzy/adfriend/blob/master/tsconfig.json"
    click EnvDecl "https://github.com/chukssomzzy/adfriend/blob/master/src/vite-env.d.ts"
    click HTMLTemplate "https://github.com/chukssomzzy/adfriend/blob/master/index.html"
    click BuildOutputs "https://github.com/chukssomzzy/adfriend/blob/master/adfriend.zip"
    click BuildOutputs "https://github.com/chukssomzzy/adfriend/blob/master/build.crx"
    click StaticAssets "https://github.com/chukssomzzy/adfriend/tree/master/src/assets/"

    %% Styles
    classDef manifest fill:#F9E79F,stroke:#B7950B,color:#1C2833
    classDef ui fill:#AED6F1,stroke:#2874A6,color:#1B2631
    classDef background fill:#ABEBC6,stroke:#239B56,color:#1B2631
    classDef content fill:#FAD7A0,stroke:#D35400,color:#1B2631
    classDef storage fill:#D5D8DC,stroke:#5D6D7E,color:#1B2631
    classDef build fill:#E5CCF2,stroke:#7D3C98,color:#1B2631
    classDef public fill:#F5CBA7,stroke:#CA6F1E,color:#1B2631
```
