# team-arpanet/project architecture

> Architecture diagram of the GitHub repository team-arpanet/project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/team-arpanet/project
- Repository: https://github.com/team-arpanet/project

## Overview

This browser extension describes images aloud. The user holds an image briefly for a short description or longer for a detailed one; the content script requests analysis, the background script fetches the image and sends it to the server, and the returned text is spoken. The popup configures hold durations. The server validates uploads and tokens, builds a prompt, and calls OpenAI. README documentation identifies additional server credentials and prompt configuration; those files were not sampled, so their internal behavior is not expanded here.

Main entry points: [`extension/background.js`](https://github.com/team-arpanet/project/blob/master/extension/background.js) (Background dispatch), [`server/server.js`](https://github.com/team-arpanet/project/blob/master/server/server.js) (Upload validation), [`extension/content.js`](https://github.com/team-arpanet/project/blob/master/extension/content.js) (Analysis request and speech), [`extension/popup.js`](https://github.com/team-arpanet/project/blob/master/extension/popup.js) (Hold settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser extension"]
  node_page_interaction["Image hold interaction<br/>[content.js]"]
  node_content_analysis["Analysis request and speech<br/>[content.js]"]
  node_settings["Hold settings<br/>[popup.js]"]
  node_background_dispatch["Background dispatch<br/>[background.js]"]
  node_speech["Spoken description<br/>[content.js]"]
end

subgraph group_server["Analysis server"]
  node_server_endpoint["Upload endpoint<br/>[server.js]"]
  node_upload_handling["Upload validation<br/>[server.js]"]
  node_prompt_config["Prompt configuration<br/>[AIParams.json]"]
  node_auth_tokens["Auth tokens<br/>[authenticated.json]"]
  node_description["Image description<br/>[server.js]"]
  node_api_key["OpenAI API key"]
  node_user_credentials["Server credentials"]
end

subgraph group_ai["AI service"]
  node_openai["OpenAI vision"]
end

node_user(("User"))
node_image["Web image"]
node_chrome_storage[("Chrome sync storage")]

node_user -->|"holds image"| node_page_interaction
node_image -->|"selects target"| node_page_interaction
node_page_interaction -->|"triggers analysis"| node_content_analysis
node_user -->|"sets durations"| node_settings
node_settings -->|"saves durations"| node_chrome_storage
node_chrome_storage -->|"loads durations"| node_page_interaction
node_content_analysis -->|"sends request"| node_background_dispatch
node_background_dispatch -->|"fetches image"| node_image
node_background_dispatch -->|"posts image"| node_server_endpoint
node_server_endpoint -->|"routes upload"| node_upload_handling
node_upload_handling -->|"checks token"| node_auth_tokens
node_upload_handling -->|"selects prompt"| node_prompt_config
node_upload_handling -->|"sends image prompt"| node_openai
node_api_key -.->|"authenticates"| node_openai
node_user_credentials -.->|"configures TLS"| node_server_endpoint
node_openai -->|"returns text"| node_description
node_description -->|"returns JSON"| node_background_dispatch
node_background_dispatch -->|"returns text"| node_content_analysis
node_content_analysis -->|"speaks result"| node_speech
node_speech -->|"plays audio"| node_user

click node_page_interaction "https://github.com/team-arpanet/project/blob/master/extension/content.js"
click node_content_analysis "https://github.com/team-arpanet/project/blob/master/extension/content.js"
click node_settings "https://github.com/team-arpanet/project/blob/master/extension/popup.js"
click node_background_dispatch "https://github.com/team-arpanet/project/blob/master/extension/background.js"
click node_server_endpoint "https://github.com/team-arpanet/project/blob/master/server/server.js"
click node_upload_handling "https://github.com/team-arpanet/project/blob/master/server/server.js"
click node_prompt_config "https://github.com/team-arpanet/project/blob/master/server/AIParams.json"
click node_auth_tokens "https://github.com/team-arpanet/project/blob/master/server/authenticated.json"
click node_description "https://github.com/team-arpanet/project/blob/master/server/server.js"
click node_speech "https://github.com/team-arpanet/project/blob/master/extension/content.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_page_interaction,node_content_analysis,node_settings,node_background_dispatch,node_speech,node_user toneBlue
class node_server_endpoint,node_upload_handling,node_prompt_config,node_auth_tokens,node_description,node_api_key,node_user_credentials,node_chrome_storage toneAmber
class node_openai toneMint
class node_image toneIndigo
```

## Components

### Browser extension

- [Image hold interaction](https://github.com/team-arpanet/project/blob/master/extension/content.js): `extension/content.js`
- [Analysis request and speech](https://github.com/team-arpanet/project/blob/master/extension/content.js): `extension/content.js`
- [Hold settings](https://github.com/team-arpanet/project/blob/master/extension/popup.js): `extension/popup.js`
- [Background dispatch](https://github.com/team-arpanet/project/blob/master/extension/background.js): `extension/background.js`
- [Spoken description](https://github.com/team-arpanet/project/blob/master/extension/content.js): `extension/content.js`

### Analysis server

- [Upload endpoint](https://github.com/team-arpanet/project/blob/master/server/server.js): `server/server.js`
- [Upload validation](https://github.com/team-arpanet/project/blob/master/server/server.js): `server/server.js`
- [Prompt configuration](https://github.com/team-arpanet/project/blob/master/server/AIParams.json): `server/AIParams.json`
- [Auth tokens](https://github.com/team-arpanet/project/blob/master/server/authenticated.json): `server/authenticated.json`
- [Image description](https://github.com/team-arpanet/project/blob/master/server/server.js): `server/server.js`
- **OpenAI API key**
- **Server credentials**

### AI service

- **OpenAI vision**

### Other components

- **User**
- **Web image**
- **Chrome sync storage**

## Connections

- User → Image hold interaction: holds image (evidence: `extension/content.js`)
- Web image → Image hold interaction: selects target (evidence: `extension/content.js`)
- Image hold interaction → Analysis request and speech: triggers analysis (evidence: `extension/content.js`)
- User → Hold settings: sets durations (evidence: `extension/popup.js`)
- Hold settings → Chrome sync storage: saves durations (evidence: `extension/popup.js`)
- Chrome sync storage → Image hold interaction: loads durations (evidence: `extension/content.js`)
- Analysis request and speech → Background dispatch: sends request (evidence: `extension/content.js`)
- Background dispatch → Web image: fetches image (evidence: `extension/background.js`)
- Background dispatch → Upload endpoint: posts image (evidence: `extension/background.js`)
- Upload endpoint → Upload validation: routes upload (evidence: `server/server.js`)
- Upload validation → Auth tokens: checks token (evidence: `server/server.js`)
- Upload validation → Prompt configuration: selects prompt (evidence: `server/server.js`)
- Upload validation → OpenAI vision: sends image prompt (evidence: `server/server.js`)
- OpenAI API key → OpenAI vision: authenticates
- Server credentials → Upload endpoint: configures TLS
- OpenAI vision → Image description: returns text (evidence: `server/server.js`)
- Image description → Background dispatch: returns JSON (evidence: `extension/background.js`)
- Background dispatch → Analysis request and speech: returns text (evidence: `extension/background.js`)
- Analysis request and speech → Spoken description: speaks result (evidence: `extension/content.js`)
- Spoken description → User: plays audio (evidence: `extension/content.js`)