# abhinavkshabu/promptizer-ai architecture

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

- Interactive diagram: https://gitdiagram.com/abhinavkshabu/promptizer-ai
- Repository: https://github.com/abhinavkshabu/promptizer-ai

## Overview

1. **Overall shape**
   Promptizer is a two-part system: a **Chrome Extension frontend** and a **Node.js/Express backend**. The browser side lives in `manifest.json`, `content.js`, `background.js`, `popup.html`, and `popup.js`; the server side is `server.js`. The main architectural boundary is between the extension and the backend API, which keeps the Groq API key off the client.

2. **Extension entry points**
   `manifest.json` defines the MV3 extension wiring: which pages get the content script, which file acts as the background/service worker, and which UI is exposed through the popup. This is the central configuration file for how the extension is injected into target sites like ChatGPT, Claude, and Gemini.

3. **Page injection and in-page interaction**
   `content.js` is the code that runs inside the AI websites themselves. Its job is to detect or attach to the prompt input area, add the “Promptize” UI, and later place the generated prompt back into the page. For an architecture diagram, this is the layer that bridges the extension with the host web app DOM.

4. **Background orchestration**
   `background.js` acts as the extension’s coordinator. It likely receives messages from the content script or popup, sends the user’s raw prompt to the backend, and returns the optimized result. This is the main extension-side boundary for network calls and cross-context messaging.

5. **Popup UI**
   `popup.html` and `popup.js` provide the extension’s toolbar popup. Based on the README, the popup is mainly a lightweight extension UI rather than the primary workflow surface. It is separate from the injected in-page controls and is useful to show extension state or trigger actions from the browser toolbar.

6. **Backend prompt optimization service**
   `server.js` is the API layer that receives a prompt from the extension and produces the enhanced version. The README describes it as an Express REST API that talks to Groq. This is the only component that should know about the Groq API key, making it the trust boundary for external AI access.

7. **External AI dependency**
   Groq is the external inference service powering prompt transformation. The data flow is: user text enters the extension, the backend forwards it to Groq, and the optimized output returns back through the extension. No long-term storage is described, so the backend appears stateless and request-driven.

8. **Runtime and deployment split**
   The extension runs in the **Chrome extension runtime** under Manifest V3, while the backend runs in **Node.js** with Express. The README indicates the backend can be local during development or deployed remotely, and the extension’s API URL is configured accordingly in `background.js`.

9. **User interaction flow**
   The operational flow is: user types a basic prompt on a supported AI site, clicks the injected Promptize control, the extension sends text to the backend, the backend returns an improved prompt, and the extension inserts that result back into the host page. The key diagram should show this as a loop between the page DOM, extension layer, and backend API.

10. **Assets and presentation**
   The `icons/` directory and popup files support the branded UI layer, while the README references a custom loading skeleton and “Galaxy Button” behavior that are most likely implemented in the extension-side scripts and markup. These assets do not change the core architecture, but they are part of the user-facing extension surface.

11. **Configuration and secrets**
   The backend reads `GROQ_API_KEY` from environment configuration, not from the browser extension. That separation is important: client-side code should only know the backend endpoint, while server-side code handles credentials and provider integration.

12. **What is not present**
   There is no evidence of a database, message queue, authentication system, or persistent user profile storage. Architecturally, this is a lightweight request/response product: browser injection on the front end, prompt transformation in the middle, and external AI inference behind the server.

Main entry points: [`background.js`](https://github.com/abhinavkshabu/promptizer-ai/blob/main/background.js) (Orchestrator), [`content.js`](https://github.com/abhinavkshabu/promptizer-ai/blob/main/content.js) (Page injector), [`server.js`](https://github.com/abhinavkshabu/promptizer-ai/blob/main/server.js) (API server), [`manifest.json`](https://github.com/abhinavkshabu/promptizer-ai/blob/main/manifest.json) (Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome Extension"]
  node_manifest["Manifest<br/>mv3 config<br/>[manifest.json]"]
  node_content["Page injector<br/>content script<br/>[content.js]"]
  node_background["Orchestrator<br/>service worker<br/>[background.js]"]
  node_popup_ui["Popup UI<br/>extension popup<br/>[popup.html]"]
  node_popup_logic["Popup logic<br/>ui script<br/>[popup.js]"]
  node_host_page["Host page<br/>ai website DOM"]
end

subgraph group_backend["Backend API"]
  node_api["API server<br/>express service<br/>[server.js]"]
  node_optimizer["Prompt engine<br/>prompt transform"]
  node_secrets["Secrets<br/>env config"]
end

subgraph group_external["External AI"]
  node_groq["Groq<br/>inference api"]
end

node_manifest -->|"injects"| node_content
node_manifest -->|"registers"| node_background
node_manifest -->|"exposes"| node_popup_ui
node_popup_ui -->|"loads"| node_popup_logic
node_content -->|"attaches to"| node_host_page
node_content -->|"sends prompt"| node_background
node_background -->|"calls"| node_api
node_popup_logic -->|"triggers"| node_background
node_api -->|"orchestrates"| node_optimizer
node_api -->|"reads"| node_secrets
node_optimizer -->|"requests"| node_groq
node_groq -->|"returns output"| node_api
node_api -->|"responds"| node_background
node_background -->|"delivers result"| node_content
node_content -->|"inserts result"| node_host_page

click node_manifest "https://github.com/abhinavkshabu/promptizer-ai/blob/main/manifest.json"
click node_content "https://github.com/abhinavkshabu/promptizer-ai/blob/main/content.js"
click node_background "https://github.com/abhinavkshabu/promptizer-ai/blob/main/background.js"
click node_popup_ui "https://github.com/abhinavkshabu/promptizer-ai/blob/main/popup.html"
click node_popup_logic "https://github.com/abhinavkshabu/promptizer-ai/blob/main/popup.js"
click node_api "https://github.com/abhinavkshabu/promptizer-ai/blob/main/server.js"

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_manifest,node_content,node_background,node_popup_ui,node_popup_logic,node_host_page toneBlue
class node_api,node_optimizer,node_secrets toneAmber
class node_groq toneMint
```

## Components

### Chrome Extension

Manifest V3 frontend that injects controls into supported AI sites and mediates user actions.

- [Manifest](https://github.com/abhinavkshabu/promptizer-ai/blob/main/manifest.json): mv3 config · Declares extension permissions, content scripts, popup, and background worker wiring. · `manifest.json`
- [Page injector](https://github.com/abhinavkshabu/promptizer-ai/blob/main/content.js): content script · Runs inside supported AI sites, attaches Promptize UI, and writes optimized prompts back into the page. · `content.js`
- [Orchestrator](https://github.com/abhinavkshabu/promptizer-ai/blob/main/background.js): service worker · Coordinates extension messages and forwards prompt requests to the backend API. · `background.js`
- [Popup UI](https://github.com/abhinavkshabu/promptizer-ai/blob/main/popup.html): extension popup · Toolbar entry point for lightweight extension interaction. · `popup.html`
- [Popup logic](https://github.com/abhinavkshabu/promptizer-ai/blob/main/popup.js): ui script · Handles popup behavior and user actions in the extension UI. · `popup.js`
- **Host page**: ai website DOM · The embedded target site where prompts are edited and results are inserted.

### Backend API

Node.js/Express service that transforms prompts and keeps API credentials off the client.

- [API server](https://github.com/abhinavkshabu/promptizer-ai/blob/main/server.js): express service · Receives prompts from the extension and returns optimized prompts. · `server.js`
- **Prompt engine**: prompt transform · Core server-side logic that prepares the request for the model and formats the response.
- **Secrets**: env config · Provides the Groq API key to the backend at runtime, outside the browser extension.

### External AI

Third-party inference provider used for prompt optimization.

- **Groq**: inference api · External model provider used to rewrite and enhance prompts.

## Connections

- Manifest → Page injector: injects · Manifest declares where the content script runs.
- Manifest → Orchestrator: registers · Manifest wires the background/service worker entry point.
- Manifest → Popup UI: exposes · Manifest makes the popup available in the browser toolbar.
- Popup UI → Popup logic: loads · Popup markup is driven by its script.
- Page injector → Host page: attaches to · Content script interacts with the target site DOM.
- Page injector → Orchestrator: sends prompt · Page UI actions are handed to the extension coordinator.
- Orchestrator → API server: calls · Background forwards raw prompts to the backend endpoint.
- Popup logic → Orchestrator: triggers · Popup actions are routed into the extension workflow.
- API server → Prompt engine: orchestrates · Express endpoint delegates prompt transformation work.
- API server → Secrets: reads · Backend loads the Groq key from environment configuration.
- Prompt engine → Groq: requests · Server-side logic sends the prompt to Groq for rewriting.
- Groq → API server: returns output · Model response is sent back to the backend.
- API server → Orchestrator: responds · Optimized prompt returns to the extension.
- Orchestrator → Page injector: delivers result · Background passes the improved prompt back for insertion.
- Page injector → Host page: inserts result · Optimized text is written back into the site input or prompt area.
