# soulcodeagency/bexio-chrome-extension architecture

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

- Interactive diagram: https://gitdiagram.com/soulcodeagency/bexio-chrome-extension
- Repository: https://github.com/soulcodeagency/bexio-chrome-extension

## Overview

##### Main Components

- Chrome Extension Core (packages/chrome-extension):
– Integrates directly with bexio’s time tracking page.
– Contains entry point files, event listeners, apps (like bexioProjectList and bexioTimetrackingTemplates), selectors, and utilities for DOM manipulation and form filling.

- Side Panel Application (packages/sidePanel-import):
– Provides the user interface for managing templates and importing entries.
– Built on a modern framework (e.g., React, as indicated by the .tsx files) and implements context/state management for template data.

- Shared Modules (packages/shared):
– Holds common functionalities and helper functions (e.g., chromeStorage, utility functions for template handling).
– Provides reusable types and functions that both the chrome-extension and side panel rely upon.

- Build and Configuration:
– npm workspace configuration (package.json at the root level)
– Build scripts and release management (Build.ps1, CreateRelease.ps1, cliff.toml, etc.)
– GitHub Actions workflows (*.github/workflows)

- Assets and Branding:
– Assets like logos, screenshots, and other UI images (assets directory) used in the extension and published on the Chrome webstore.

##### Establish Relationships and Data Flow

- User interactions on the bexio page trigger the chrome-extension’s event listeners (in packages/chrome-extension/src/eventListeners).
- From the event triggers, there is a data flow to:
– The “apps” layer (which organizes different functionalities like auto-filling templates in bexioProjectList and bexioTimetrackingTemplates)
– The “selectors” layer and “utils” that manipulate the DOM or handle data operations such as reading form data, triggering fields, or managing loaders.
- The shared module supplies services such as chromeStorage to persist, load, or sync templates and settings.
- The sidePanel-import package functions as the management UI:
– It uses its own set of components (TemplateEntries, TemplateModal, TemplateSelect, etc.) to display and let users interact with stored data.
– It interacts with the shared modules to fetch and update template data.
- The build configuration and scripts coordinate releases, testing, and continuous integration via tools (e.g., GitHub Actions).

##### Architectural Patterns and Technologies

- Modularity: The project is modularized into distinct packages (chrome-extension, sidePanel-import, shared) under a monorepo managed by npm workspaces.
- Separation of Concerns:
– UI Logic is separated (side panel vs. in-page functionalities)
– Shared functions are isolated in a common library.
- Event-driven Interactions:
– Using event listeners to capture chrome extension messages and DOM changes.
- Modern Web Development:
– Use of TypeScript in both the extension and side panel (indicated by *.ts, *.tsx and tsconfig files)
– Usage of Vite for development/build in some packages.
- Integration with External Tools:
– Import functionality from ManicTime, applying templates and filling forms accordingly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Chrome Extension (packages/chrome-extension)"
        direction TB
        CE1["Event Listeners"]:::extension
        CE2["Apps (bexioProjectList, bexioTimetrackingTemplates)"]:::extension
        CE3["Selectors"]:::extension
        CE4["Utils"]:::extension
        CE5["Public Assets & Manifest"]:::extension
    end

    subgraph "Side Panel Application (packages/sidePanel-import)"
        direction TB
        SP1["UI Components (/src/components)"]:::ui
        SP2["TemplateContext.ts"]:::ui
        SP3["TemplateProvider.tsx"]:::ui
        SP4["Entry Point: index.html"]:::ui
        SP5["Main TSX (main.tsx)"]:::ui
    end

    subgraph "Shared Modules (packages/shared)"
        direction TB
        SM1["chromeStorage & Utility Functions"]:::shared
    end

    subgraph "Build & Configuration"
        direction TB
        BC1["Monorepo & npm workspace (package.json)"]:::config
        BC2["Build Scripts & Release (Build.ps1, CreateRelease.ps1, cliff.toml)"]:::config
        BC3["CI/CD Workflows (.github/workflows)"]:::config
    end

    subgraph "Assets & Branding"
        direction TB
        A1["Images, Logos, Screenshots"]:::assets
    end

    User["User Interaction"]:::external

    %% Data flow arrows
    User -->|"Triggers"| CE1
    CE1 -->|"ProcessesEvent"| CE2
    CE2 -->|"UsesSelectors"| CE3
    CE2 -->|"UtilizesUtils"| CE4
    CE2 -->|"CallsStorage"| SM1
    SP1 -->|"ManagesTemplates"| SM1
    User -->|"Interacts"| SP1

    %% Build & deployment interactions
    CE1 & CE2 & CE3 & CE4 & CE5 -->|"BuiltUsing"| BC2
    SP1 & SP2 & SP3 & SP4 & SP5 -->|"BuiltWithVite"| BC2
    SM1 -->|"SharedBy"| CE2
    SM1 -->|"SharedBy"| SP1
    BC3 -->|"Automates"| BC2

    %% Integration with assets
    SP1 -->|"UsesBranding"| A1
    CE5 -->|"UsesBranding"| A1

    %% Click events for Chrome Extension Core
    click CE1 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/chrome-extension/src/eventListeners"
    click CE2 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/chrome-extension/src/apps"
    click CE3 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/chrome-extension/src/selectors"
    click CE4 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/chrome-extension/src/utils"
    click CE5 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/chrome-extension/public"

    %% Click events for Side Panel Application
    click SP1 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/sidePanel-import/src/components"
    click SP2 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/packages/sidePanel-import/src/TemplateContext.ts"
    click SP3 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/packages/sidePanel-import/src/TemplateProvider.tsx"
    click SP4 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/packages/sidePanel-import/index.html"
    click SP5 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/packages/sidePanel-import/src/main.tsx"

    %% Click event for Shared Modules
    click SM1 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/packages/shared"

    %% Click events for Build and Configuration
    click BC1 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/package.json"
    click BC2 "https://github.com/soulcodeagency/bexio-chrome-extension/blob/main/Build.ps1"
    click BC3 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/.github/workflows"

    %% Click event for Assets
    click A1 "https://github.com/soulcodeagency/bexio-chrome-extension/tree/main/assets"

    %% Style definitions
    classDef extension fill:#f9c,stroke:#333,stroke-width:2px;
    classDef ui fill:#bbf,stroke:#333,stroke-width:2px;
    classDef shared fill:#afa,stroke:#333,stroke-width:2px;
    classDef config fill:#ffb,stroke:#333,stroke-width:2px;
    classDef assets fill:#fcc,stroke:#333,stroke-width:2px;
    classDef external fill:#9f9,stroke:#333,stroke-width:2px;
```
