# ruxailab/heatmap-app architecture

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

- Interactive diagram: https://gitdiagram.com/ruxailab/heatmap-app
- Repository: https://github.com/ruxailab/heatmap-app

## Overview

##### Main Components
- Electron Main Process: Found under the “electron-src” directory, this includes the main.js file (which likely starts the application), the preload scripts (preload.js, preloadView.js) for securing communication between processes, and sub-folders such as “mainWindow” which might handle window management.
- Web Contents and IPC Handlers: The “electron-src/webContentsView” folder containing handlers.js suggests that there is specific logic for managing web content events or IPC communications.
- Vue Frontend (Renderer Process): The “src” directory contains Vue components, views, layouts, controllers (e.g., AuthController, UserController), and routers. This is the application’s UI layer which interacts with the user.
- Additional Supporting Components:
- Firebase integration (located in the “src/firebase” directory) for backend services or user authentication.
- Vue plugins (e.g., vuetify.js, i18n.js) and state management via “src/stores” which indicate use of the Vue ecosystem for smoother UI and state synchronization.

##### Understand the Interactions and Data Flow
- The Electron Main Process initializes the application, creates the main window, and loads the Vue renderer (via index.html).
- Preload scripts ensure secure, controlled communication between the Electron main process and the renderer process.
- The Trackers (clicks, mouse) in the Electron layer capture user interaction events and then pass this data to the TrackerManager for processing and possibly for passing on to the Vue frontend or storing analytics.
- The Vue frontend (inside “src”) manages the application’s views (Dashboard, Results, Sign In/Up, etc.), components (task components, url forms, dashboards), and uses controllers to manage business logic, including authentication and user data.
- Integration with Firebase indicates that after capturing data, user authentication and possibly analytics storage or retrieval might occur via backend services.
- Communication between Electron and Vue might use IPC or the preload scripts to send data (for user events or analytics) from the desktop shell to the UI layer.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly divides the Electron aspect (desktop wrapper, event tracking) from the Vue frontend (UI and UX). Each layer has distinct responsibilities.
- Modularization: The “trackers” folder, organized into subdirectories for different event types (clicks, mouse), promotes modular event handling.
- Use of MVC/MVVM Pattern: The Vue directory structure shows distinct folders for components, views, controllers, and stores, which reinforces a separation between presentation, logic, and data.
- Extensibility: With clearly separated tracking logic (BaseTracker and TrackerManager) and Vue components, adding more trackers or UI features should be straightforward.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Layer
    subgraph "Electron Layer (Desktop Shell)"
        EMP("Electron Main Process (main.js)"):::electron
        P1("Preload Script (preload.js)"):::electron
        P2("Preload Script (preloadView.js)"):::electron
        TW("Window Management (mainWindow)"):::electron
        IPC("Web Contents & IPC Handlers (handlers.js)"):::electron
        subgraph "Trackers Module"
            BT("BaseTracker & TrackerManager"):::tracker
            CT("ClickTracker"):::tracker
            MT("MouseTracker"):::tracker
        end
    end

    %% Vue Layer
    subgraph "Vue Frontend (Renderer Process)"
        VMain("Vue Main Entry (main.js)"):::vue
        App("App Component (App.vue)"):::vue
        Comp("Vue Components (src/components)"):::vue
        Views("Vue Views (src/views)"):::vue
        Controllers("Vue Controllers (src/controllers)"):::vue
        Plugins("Vue Plugins (vuetify.js, i18n.js)"):::vue
        Stores("Vue Stores (src/stores)"):::vue
    end

    %% External Services
    subgraph "External Services"
        Firebase("Firebase Service (index.js)"):::external
    end

    %% Interactions in Electron Layer
    EMP --> P1
    EMP --> P2
    EMP --> TW
    EMP --> IPC
    IPC --> BT
    BT --> CT
    BT --> MT

    %% Interactions between Electron and Vue Layers
    EMP -->|"initiate_IPC"| VMain
    VMain -->|"send_event_data"| IPC
    P1 ---|"secure_channel"| Controllers
    P2 ---|"secure_channel"| Controllers

    %% Interactions in Vue Layer
    VMain --> App
    App --> Comp
    App --> Views
    Views --> Controllers
    Controllers -->|"auth/data"| Firebase
    Controllers --> Stores
    Plugins --> Stores

    %% Processing Flow
    BT -->|"process_user_events"| Controllers

    %% Click Events for Electron Components
    click EMP "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/main.js"
    click TW "https://github.com/ruxailab/heatmap-app/tree/main/electron-src/mainWindow/"
    click P1 "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/preload.js"
    click P2 "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/preloadView.js"
    click BT "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/trackers/BaseTracker.js"
    click BT "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/trackers/TrackerManager.js"
    click CT "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/trackers/clicks/ClickTracker.js"
    click MT "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/trackers/mouse/MouseTracker.js"
    click IPC "https://github.com/ruxailab/heatmap-app/blob/main/electron-src/webContentsView/handlers.js"

    %% Click Events for Vue Components
    click VMain "https://github.com/ruxailab/heatmap-app/blob/main/src/main.js"
    click App "https://github.com/ruxailab/heatmap-app/blob/main/src/App.vue"
    click Comp "https://github.com/ruxailab/heatmap-app/tree/main/src/components/"
    click Views "https://github.com/ruxailab/heatmap-app/tree/main/src/views/"
    click Controllers "https://github.com/ruxailab/heatmap-app/tree/main/src/controllers/"
    click Plugins "https://github.com/ruxailab/heatmap-app/blob/main/src/plugins/vuetify.js"
    click Plugins "https://github.com/ruxailab/heatmap-app/blob/main/src/plugins/i18n.js"
    click Stores "https://github.com/ruxailab/heatmap-app/tree/main/src/stores/"

    %% Click Event for External Service
    click Firebase "https://github.com/ruxailab/heatmap-app/blob/main/src/firebase/index.js"

    %% Styles
    classDef electron fill:#f9b19b,stroke:#d08770,stroke-width:2px;
    classDef tracker fill:#ede574,stroke:#eab676,stroke-width:2px;
    classDef vue fill:#8ec07c,stroke:#458588,stroke-width:2px;
    classDef external fill:#83a598,stroke:#689d6a,stroke-width:2px;
```
