# tftc-holdings-inc/opportunity-cost architecture

> Architecture diagram of the GitHub repository tftc-holdings-inc/opportunity-cost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tftc-holdings-inc/opportunity-cost
- Repository: https://github.com/tftc-holdings-inc/opportunity-cost

## Overview

##### Project type and purpose
- This is a hybrid full-stack project consisting of:
- A browser extension (Chrome & Firefox) that scans any webpage for fiat prices, fetches current Bitcoin rates, and replaces or augments those prices in situ.
- A marketing/demo website (Next.js) with a serverless API endpoint (`/api/bitcoin-price`) that also returns live Bitcoin rates.
- The README confirms the goals: “See the True Cost of Everything in Bitcoin,” privacy-first local processing, and a customizable popup/options UI.

##### File structure
Top-level directories:
- `/extension` – source + packaging for multiple targets
– `chrome/` (manifest.json only – final package)
– `firefox-extension-submission/` (React/TSX code, Vite configs, manifest for Firefox submission)
– `firefox/` (manifest.json only – final package)
– `shared/` (common React/TSX code and Vite build configs used by both targets)
- `/web` – Next.js application
– `src/app/api/bitcoin-price/route.ts` – serverless function
– `src/app/...` – demo pages, install page, privacy policy, etc.
– `components/` – landing-page & UI components
– `public/` – static assets, packaged extension ZIPs
Configuration/build files: Vite configs, Next.js configs, ESLint, tsconfig, package.json, pnpm/yarn lockfiles.

##### README for insights
- Confirms extension fetches rates from an API (could be the `/api/bitcoin-price` endpoint or a third-party service).
- Describes runtime flow: scan DOM via content script + MutationObserver, calculate local conversions, no user data sent out.
- Describes the popup/options UI for settings, and the live dual-display vs BTC-only modes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Extension"
        manifestChrome["Chrome Manifest"]:::extension
        manifestFirefox["Firefox Manifest"]:::extension
        sourceFirefox["Firefox Submission Source"]:::extension
        sharedModules["Shared Source Modules"]:::extension
        contentScript["Content Script"]:::extension
        backgroundScript["Background Script"]:::extension
        popupUI["Popup UI"]:::extension
        optionsUI["Options UI"]:::extension
    end

    subgraph "Web Application"
        nextFrontend["Next.js Frontend"]:::web
        apiRoute["Serverless API Route"]:::web
    end

    subgraph "External Services"
        externalAPI["External Bitcoin Price Service"]:::external
    end

    subgraph "CI/CD & Distribution"
        ci["CI/CD Pipeline"]:::cicd
        distChrome["Chrome Package"]:::dist
        distFirefox["Firefox Package"]:::dist
        chromeStore["Chrome Web Store"]:::dist
        firefoxStore["Firefox Add-ons"]:::dist
    end

    contentScript -->|"chrome.runtime.sendMessage"| backgroundScript
    backgroundScript -->|"HTTP GET Price"| externalAPI
    externalAPI --> backgroundScript
    backgroundScript -->|"send response"| contentScript
    popupUI -->|"browser.storage.get/set"| sharedModules
    optionsUI -->|"browser.storage.get/set"| sharedModules
    nextFrontend -->|"GET /api/bitcoin-price"| apiRoute
    apiRoute -->|"HTTP GET Price"| externalAPI
    externalAPI --> apiRoute
    apiRoute -->|"return JSON"| nextFrontend

    ci -->|"builds"| manifestChrome
    ci -->|"builds"| manifestFirefox
    ci -->|"builds"| sourceFirefox
    ci -->|"builds"| distChrome
    ci -->|"builds"| distFirefox
    ci -->|"deploys"| nextFrontend

    distChrome -.->|available on| chromeStore
    distFirefox -.->|available on| firefoxStore

    click manifestChrome "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/chrome/manifest.json"
    click manifestFirefox "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox/manifest.json"
    click sourceFirefox "https://github.com/tftc-holdings-inc/opportunity-cost/tree/main/extension/firefox-extension-submission/"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/tree/main/extension/shared/"
    click contentScript "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/lib/content.ts"
    click contentScript "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/lib/content.ts"
    click backgroundScript "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/lib/background.ts"
    click backgroundScript "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/lib/background.ts"
    click popupUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/index.tsx"
    click popupUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/index.html"
    click popupUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/index.tsx"
    click popupUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/index.html"
    click optionsUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/options.tsx"
    click optionsUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/options.html"
    click optionsUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/options.tsx"
    click optionsUI "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/options.html"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/lib/constants.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/lib/storage.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/src/lib/utils.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/lib/constants.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/lib/storage.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/src/lib/utils.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/vite.config.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/vite.background.config.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/firefox-extension-submission/vite.content.config.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/vite.config.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/vite.background.config.ts"
    click sharedModules "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/extension/shared/vite.content.config.ts"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/tree/main/web/src/app/"
    click apiRoute "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/src/app/api/bitcoin-price/route.ts"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/tree/main/web/src/components/landing-page/"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/tree/main/web/src/components/ui/"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/next.config.ts"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/eslint.config.mjs"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/postcss.config.mjs"
    click nextFrontend "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/tsconfig.json"
    click distChrome "https://github.com/tftc-holdings-inc/opportunity-cost/blob/main/web/public/extension/*.zip"

    classDef extension fill:#d0e7ff,stroke:#0366d6;
    classDef web fill:#d5f5d5,stroke:#28a745;
    classDef external fill:#f0f0f0,stroke:#6c757d;
    classDef cicd fill:#fff4ce,stroke:#d39e00;
    classDef dist fill:#f0f0f0,stroke:#6c757d;
```
