# dhilman/gitowl-extension architecture

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

- Interactive diagram: https://gitdiagram.com/dhilman/gitowl-extension
- Repository: https://github.com/dhilman/gitowl-extension

## Overview

Based on our analysis of the file tree and README, this project is a browser extension (the GitOwl Extension) designed to add a sidebar with contextual insights on sites such as GitHub, NPM, and PyPI. The README clearly divides the code into three primary components:

1. Content Script (in src/content) – This portion runs within the webpage’s context. It is responsible for controlling the sidebar, detecting the current entity (e.g., repository, package), and instantiating the frame via an iframe.
2. Frame Page (in src/frame) – This page hosts the embedded gitowl.dev iframe. Its role is to safely transit messages received from the content script to the external service while handling necessary authentication details.
3. Worker (in src/worker) – Implemented for Chromium, it listens for messages from gitowl.dev and manages the storage of the authentication token.

##### Main Components
- A fourth “External Service” or “gitowl.dev” component since the extension integrates externally.

##### Pattern and Design Principles
- The Content Script works directly in the DOM with the webpage.
- The Frame Page encapsulates the external iframe to avoid cross-origin issues.
- The Worker focuses on background processing (specifically for Chromium).

##### Technologies & Tools
- Mention that build and packaging scripts (in scripts/) facilitate the bundling and releasing process, though they are less central to runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Extension"
        CS["Content Script: Controls sidebar state, identifies current entity, instantiates iframe"]:::inpage
        FP["Frame Page: Embeds external iframe (gitowl.dev), relays messages with auth token"]:::ui
        WK["Worker: Handles authentication token storage (Chromium only)"]:::background
    end

    ES["External Service: gitowl.dev"]:::external

    CS -->|"instantiates_iframe&sends_entity_details"| FP
    FP -->|"relays_messages_with_auth_token"| ES
    ES -->|"sends_authentication_token"| WK
    WK -->|"updates_sidebar_state"| CS

    classDef inpage fill:#FAD02E,stroke:#333,stroke-width:2px;
    classDef ui fill:#A1C349,stroke:#333,stroke-width:2px;
    classDef background fill:#7E7E7E,stroke:#333,stroke-width:2px;
    classDef external fill:#FF6F61,stroke:#333,stroke-width:2px;

    click CS "https://github.com/dhilman/gitowl-extension/tree/master/src/content"
    click FP "https://github.com/dhilman/gitowl-extension/tree/master/src/frame"
    click WK "https://github.com/dhilman/gitowl-extension/tree/master/src/worker"
```
