# bcastelino/prompt-polish-local-extension architecture

> Architecture diagram of the GitHub repository bcastelino/prompt-polish-local-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bcastelino/prompt-polish-local-extension
- Repository: https://github.com/bcastelino/prompt-polish-local-extension

## Overview

##### Project type and purpose
- This is a browser-extension project (Chrome Extension, Manifest V3) whose sole purpose is to enhance user-supplied AI prompts locally via the OpenRouter API and manage a small prompt library in browser local storage.
- There is no external backend you control—only the OpenRouter API as a third-party service.

##### File structure
Top-level files and folders:
- manifest.json      – extension metadata, permissions, entry points
- background.js      – background service worker, context‐menu handler, message router, API invocations
- content.js/css     – injected content script for “right-click → enhance” within arbitrary pages
- popup.html/js/css  – the UI for manual prompt entry, enhancement, saving, copying
- openrouter_secrets.js – local file holding the API key (gitignored)

Key patterns:
- MV* pattern inside the popup (popup.html is the View, popup.js is the Controller/Model logic).
- Message passing via chrome.runtime.sendMessage / onMessage between popup ↔ background ↔ content.
- Local state persistence via chrome.storage.local.
- External HTTP calls to OpenRouter from the background script only (to keep the secret key out of content/popup).

##### README for additional insights
- All HTTP calls go directly from the extension (background.js) to OpenRouter’s chat/completions endpoint.
- Data flow is strictly: User → popup.js or content.js → background.js → OpenRouter API → background.js → popup.js or content.js → UI → chrome.storage.local.

a. Main components
1. Chrome Browser (host)
2. Extension:
- Popup UI (popup.html/js/css)
- Background Service Worker (background.js)
- Content Script (content.js/css)
- Local Storage (chrome.storage.local)
3. External Service: OpenRouter LLM API

b. Relationships & interactions
2. Popup UI sends “enhance” message to Background
3. Background performs fetch() to OpenRouter using API key
4. Background returns enhanced prompt to Popup UI
5. Popup UI reads/writes saved prompts via chrome.storage.local
6. User right-clicks on any text input → Context menu provided by Background → Content Script runs → forwards request to Background → Background calls API → Content Script displays result inline

c. Architectural patterns & design principles
- Single-page-style UI in popup; separation of concerns between UI (popup.js) and data flow/side effects (background.js).
- Messaging broker pattern via chrome.runtime.
- Local state store using chrome.storage.local (No external database).
- Secure secret handling: Only the background script holds the API key.
- Stateless enhancement: each API call is independent.

d. Key technologies & frameworks
- Chrome Extension APIs (manifest V3, service workers, storage, contextMenus)
- Vanilla JavaScript, HTML, CSS
- OpenRouter LLM REST API
- Optional: postman/cURL for local testing

##### Final advice
- Two user entry points: popup click flow and context-menu flow.
- Every message channel explicitly—this is the crux of extension architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Popup Context"
    direction TB
    PPHTML["popup.html"] 
    PPJS["popup.js"]
    PPCSS["style.css"]
  end

  subgraph "Background Context"
    direction TB
    BGJS["background.js"]
    SECRETS["openrouter_secrets.js"]
  end

  subgraph "Content Context"
    direction TB
    CJ["content.js"]
    CCSS["content.css"]
  end

  Storage["chrome.storage.local"]:::storage
  API["OpenRouter API"]:::external

  subgraph "Project Files"
    direction TB
    Manifest["manifest.json"]
    Icons["icons/"]
    Preview["preview/"]
    README["README.md"]
    License["LICENSE"]
  end

  PPHTML -->|opens Popup UI| PPJS
  PPJS -->|enhancePrompt message| BGJS
  BGJS -->|HTTP POST| API
  API -->|HTTP response| BGJS
  BGJS -->|enhancedPrompt result| PPJS
  PPJS -->|savePrompt/readPrompts| Storage
  CJ -->|contextMenuRequest| BGJS
  BGJS -->|inlineResult| CJ

  click PPHTML "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/popup.html"
  click PPJS "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/popup.js"
  click PPCSS "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/style.css"
  click BGJS "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/background.js"
  click SECRETS "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/openrouter_secrets.js"
  click CJ "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/content.js"
  click CCSS "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/content.css"
  click Manifest "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/manifest.json"
  click Icons "https://github.com/bcastelino/prompt-polish-local-extension/tree/main/icons/"
  click Preview "https://github.com/bcastelino/prompt-polish-local-extension/tree/main/preview/"
  click README "https://github.com/bcastelino/prompt-polish-local-extension/blob/main/README.md"
  click License "https://github.com/bcastelino/prompt-polish-local-extension/tree/main/LICENSE"

  classDef ui fill:#aaf,stroke:#000
  classDef background fill:#afa,stroke:#000
  classDef content fill:#aaf,stroke:#000
  classDef storage fill:#ffa,stroke:#000
  classDef external fill:#fdd,stroke:#000
  classDef static fill:#ddd,stroke:#000

  class PPHTML,PPJS,PPCSS ui
  class BGJS,SECRETS background
  class CJ,CCSS content
  class Manifest,Icons,Preview,README,License static
  class Storage storage
  class API external
```
