# toyfer/fontify architecture

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

- Interactive diagram: https://gitdiagram.com/toyfer/fontify
- Repository: https://github.com/toyfer/fontify

## Overview

##### Project Type and Purpose
- Fontify is a browser extension (Chrome & Firefox, Manifest V3) whose goal is to replace all fonts on the current webpage with a user-specified web font. It provides a popup UI for one-click exclusion, an options page for configuration, and uses content scripts to inject CSS at runtime.

##### File Structure Analysis
- Top-level:
- .github & docs: CI workflows and design/development documentation
- src: extension source
- src/html: static UI pages (popup.html, options.html)
- src/js:
- background.js – service worker handling storage, caching, events
- content.js – runs in page context to traverse DOM and inject @font-face rules
- options.js – logic for the options page (save URL, exclusion list)
- popup.js – logic for the popup (add current site to exclusion list)
- manifest.json: declares permissions, background scripts, content injection, UI pages

##### Key README Insights
- Uses Bulma CSS for UI
- Caches web font files (woff/ttf/otf) for performance
- Supports exclusion list per URL
- Future plans documented in docs/features and docs/development

##### Main Components
a. Browser Host
b. Extension Package
1. Manifest (controls wiring)
2. Background Service Worker (background.js)
3. Content Script Injector (content.js)
4. Popup UI (popup.html + popup.js + Bulma)
5. Options UI (options.html + options.js + Bulma)
6. Cache Storage (IndexedDB or chrome.storage.local)
c. External Web Font Server (remote font URL)
d. Web Page (any site to be fontified)

##### Relationships and Interactions
- On install/startup, the background worker registers event listeners (e.g., chrome.webNavigation, messages).
- When a page loads:
- content.js queries background for active font URL & exclusion status
- background checks exclusion list (chrome.storage)
- if not excluded, content.js downloads/caches the font from the external server (via background) and injects CSS (@font-face + override selectors)
- Popup UI ↔ background: sends message to add current origin to exclusion list
- Options UI ↔ background: CRUD operations on font URL and exclusion list
- Cached fonts live in chrome.storage.local or IndexedDB, managed by background

##### Architectural Patterns and Principles
- Event-driven: background.js responds to browser events and messages
- Separation of concerns:
- UI (popup/options) vs. business logic (background) vs. DOM manipulation (content script)
- Caching layer abstracted behind the background script
- Declarative wiring via manifest.json (permissions, script injection)

- Message flows with arrowheads and callouts (e.g., “getFontUrl() → returns URL from storage”)
- Caching logic (“if font not in cache → fetch & store”)
- Manifest-declared permissions (e.g., “webRequest”, “storage”, “activeTab”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph Browser
        subgraph Extension
            Manifest["manifest.json: Static Configuration"]:::config
            Background["background.js: Service Worker"]:::logic
            Content["content.js: Content Script Injector"]:::logic
            subgraph "UI Components"
                PopupHTML["popup.html: Popup UI"]:::ui
                PopupJS["popup.js: Logic"]:::ui
                OptionsHTML["options.html: Options UI"]:::ui
                OptionsJS["options.js: Logic"]:::ui
            end
            CacheStorage["Cache Storage\n(chrome.storage.local / IndexedDB)"]:::storage
        end
    end

    ExternalFont["External Web Font Server"]:::external
    WebPage["Web Page\n(any site)"]:::external

    WebPage -->|"injects content script"| Content
    Content -->|"message: getFontUrl(), isExcluded()"| Background
    Background -->|"read/write settings & fonts"| CacheStorage
    Background -->|"fetch font if miss"| ExternalFont
    Background -->|"respond font URL"| Content
    Content -->|"inject @font-face CSS"| WebPage
    PopupHTML -->|"message: add to exclusion"| Background
    PopupJS -->|"message: add to exclusion"| Background
    OptionsHTML -->|"CRUD config"| Background
    OptionsJS -->|"CRUD config"| Background

    subgraph "Documentation & CI"
        FeaturesDoc["docs/features/\nFEATURE_PLANNING_SUMMARY.md\nFEATURE_ROADMAP*.md"]:::doc
        DevDoc["docs/development/\nDEVELOPMENT_PLAN.md\nIMPLEMENTATION_CHECKLIST.md"]:::doc
        CIWorkflows[".github/workflows/*.yml"]:::config
        ContributorGuide[".github/copilot-instructions.md"]:::config
    end

    classDef ui fill:#cfe2f3,stroke:#000
    classDef logic fill:#d9ead3,stroke:#000
    classDef config fill:#d9d9d9,stroke:#000
    classDef storage fill:#e7e6f7,stroke:#000
    classDef external fill:#fce5cd,stroke:#000
    classDef doc fill:#fff2cc,stroke:#000

    click Manifest "https://github.com/toyfer/fontify/blob/main/src/manifest.json"
    click Background "https://github.com/toyfer/fontify/blob/main/src/js/background.js"
    click Content "https://github.com/toyfer/fontify/blob/main/src/js/content.js"
    click PopupHTML "https://github.com/toyfer/fontify/blob/main/src/html/popup.html"
    click PopupJS "https://github.com/toyfer/fontify/blob/main/src/js/popup.js"
    click OptionsHTML "https://github.com/toyfer/fontify/blob/main/src/html/options.html"
    click OptionsJS "https://github.com/toyfer/fontify/blob/main/src/js/options.js"
    click FeaturesDoc "https://github.com/toyfer/fontify/blob/main/docs/features/FEATURE_PLANNING_SUMMARY.md"
    click FeaturesDoc "https://github.com/toyfer/fontify/blob/main/docs/features/FEATURE_ROADMAP1.md"
    click FeaturesDoc "https://github.com/toyfer/fontify/blob/main/docs/features/FEATURE_ROADMAP2.md"
    click DevDoc "https://github.com/toyfer/fontify/blob/main/docs/development/DEVELOPMENT_PLAN.md"
    click DevDoc "https://github.com/toyfer/fontify/blob/main/docs/development/IMPLEMENTATION_CHECKLIST.md"
    click CIWorkflows "https://github.com/toyfer/fontify/blob/main/.github/workflows/workflow1.yml"
    click CIWorkflows "https://github.com/toyfer/fontify/blob/main/.github/workflows/workflow2.yml"
    click ContributorGuide "https://github.com/toyfer/fontify/blob/main/.github/copilot-instructions.md"
```
