# utkarshthedev/webpresence architecture

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

- Interactive diagram: https://gitdiagram.com/utkarshthedev/webpresence
- Repository: https://github.com/utkarshthedev/webpresence

## Overview

##### Project Type and Purpose
- Web Presence is a full‐stack application combining a browser extension (client) with a backend server.

##### High‐Level Components
A. Client (Browser Extension)
1. Chrome Extension (Manifest V3)
- popup.html/css/js: UI for toggle and status
- background.js: listens for tab changes, sends events to server
2. Firefox Extension (Manifest V2)
- same structure as Chrome, with Firefox APIs
B. Server (Bun/Node.js)
- websocket.ts: WebSocket server to receive client events
- discord.ts: Uses discord-rpc package to update Rich Presence
- config.ts: Holds Discord Client ID and configuration
C. Assets
D. Scripts (Offline Tools)
E. External Services
- Discord Desktop App (RPC endpoint)

##### Relationships and Data Flows
2. Background script
→ Captures active tab URL & favicon
→ Opens/maintains WebSocket connection to server
→ Sends “presence_on/off” and “tab_update” events
3. WebSocket server
→ Receives events, validates via config.ts
4. Discord RPC client
→ Receives event payload
→ Calls Discord’s local RPC socket to update Rich Presence
5. Scripts run separately to populate assets before deployment

##### Architectural Patterns & Principles
- Event‐driven: client emits events, server reacts asynchronously
- Pub/Sub style: each tab update is published via WebSocket
- Separation of Concerns:
- UI (popup) vs. background logic in extension
- WebSocket handling vs. Discord RPC logic in server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client" 
        direction TB
        subgraph "Chrome Extension" 
            direction TB
            ChromeUI["Browser UI<br/>(popup.html/css/js)"]:::client
            ChromeBG["Background Script<br/>(background.js)"]:::client
            ChromeUI -->|"User toggles presence"| ChromeBG
        end
        subgraph "Firefox Extension" 
            direction TB
            FirefoxUI["Browser UI<br/>(popup.html/css/js)"]:::client
            FirefoxBG["Background Script<br/>(background.js)"]:::client
            FirefoxUI -->|"User toggles presence"| FirefoxBG
        end
    end

    %% Server Layer
    subgraph "Server" 
        direction TB
        subgraph "Real-time Engine" 
            direction TB
            WS["WebSocket Server<br/>(websocket.ts)"]:::server
            RPC["Discord RPC Client<br/>(discord.ts)"]:::server
            IconMgr["Icon Manager<br/>(siteIcons.ts)"]:::server
            Config["Configuration Module<br/>(config.ts)"]:::server
            WS -->|"onTabUpdate(event)"| RPC
            RPC -->|"resolve iconKey → load PNG"| IconMgr
            WS -->|"uses config"| Config
        end
    end

    %% External Service
    DiscordApp["Discord Desktop App"]:::external

    %% Assets & Scripts
    Scripts["Asset‐Generation Scripts"]:::scripts
    Assets["Site Icons<br/>(assets/site-icons)"]:::scripts

    %% Connections
    ChromeBG -->|"WebSocket (ws://…)"| WS
    FirefoxBG -->|"WebSocket (ws://…)"| WS
    RPC -->|"RPC UpdatePresence()"| DiscordApp
    Scripts -.->|"populate assets"| Assets

    %% Click Events
    click ChromeUI "https://github.com/utkarshthedev/webpresence/blob/main/client/chrome/popup.html"
    click ChromeBG "https://github.com/utkarshthedev/webpresence/blob/main/client/chrome/background.js"
    click FirefoxUI "https://github.com/utkarshthedev/webpresence/blob/main/client/firefox/popup.html"
    click FirefoxBG "https://github.com/utkarshthedev/webpresence/blob/main/client/firefox/background.js"
    click WS "https://github.com/utkarshthedev/webpresence/blob/main/server/websocket.ts"
    click RPC "https://github.com/utkarshthedev/webpresence/blob/main/server/discord.ts"
    click Config "https://github.com/utkarshthedev/webpresence/blob/main/server/config.ts"
    click IconMgr "https://github.com/utkarshthedev/webpresence/blob/main/server/siteIcons.ts"
    click Assets "https://github.com/utkarshthedev/webpresence/tree/main/assets/site-icons/"
    click Scripts "https://github.com/utkarshthedev/webpresence/blob/main/scripts/icon-collector.js"

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000
    classDef server fill:#d4edda,stroke:#28a745,color:#000
    classDef scripts fill:#e2e3e5,stroke:#6c757d,color:#000,stroke-dasharray: 2 2
    classDef external fill:#f5e6ff,stroke:#9b59b6,color:#000
```
