# conviva/conviva-js-appanalytics architecture

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

- Interactive diagram: https://gitdiagram.com/conviva/conviva-js-appanalytics
- Repository: https://github.com/conviva/conviva-js-appanalytics

## Overview

##### Project type and purpose
- This is a client-side JavaScript SDK (an open-source tool/library) named “Conviva JavaScript ECO SDK.”
- Purpose: to be embedded into web applications (MPAs or SPAs) to auto-collect UX and performance events, track custom events, errors, page views, device metadata, and then send that data to the Conviva backend (Pulse).

##### File structure
- Top-level files only—no “src/” or “lib/” directories:
- conviva-js-appanalytics.js — the compiled SDK bundle (ES5/UMD)
- conviva-js-appanalytics.d.ts — TypeScript definitions
- package.json — SDK metadata, dependencies, build scripts
- README.md, CHANGELOG.md, ConvivaLegalNotice.txt — docs and legal
- There is no “frontend/” or “backend/” directory since this is a library, not an application with UI or server components.
- No tests or examples in this tree, so the focus is purely on the runtime behavior of the distributed bundle.

##### README for additional insights
- Public API surface: convivaAppTracker(), setUserId(), trackPageView(), trackCustomEvent(), setCustomTags(), unsetCustomTags(), trackError(), getClientId(), setClientId()
- Core modules implied: Initialization & Config, Event Collection (auto-collected and custom), Storage (localStorage + optional cookies), Network (XHR/Fetch), Metadata management, Error handling
- External service: Conviva Pulse backend must be called by the SDK

## Diagram (Mermaid)

```mermaid
flowchart TB
    HostApp["Host Web Application\n(MPA/SPA)"]:::consumer

    subgraph "Conviva JavaScript ECO SDK"
        direction TB
        PublicAPI["SDK Public API Layer\n(init, tracking methods)"]:::sdk
        Config["Configuration Manager\n(appId, keys, version)"]:::sdk
        Collector["Event Collector\n(auto & manual events)"]:::sdk
        Metadata["Metadata Manager\n(deviceMetadata, metaTags)"]:::sdk
        Storage{{"Storage Layer\n(localStorage, cookies)"}}:::sdk
        Network["Network Layer\n(batched HTTP calls)"]:::sdk
    end

    subgraph "SDK Package Files"
        direction TB
        TSdefs["TypeScript Definitions"]:::sdk
        Package["Package Metadata & Build Scripts"]:::sdk
        README["SDK Documentation & Usage Guide"]:::sdk
        Changelog["Changelog / Release History"]:::sdk
        Legal["Legal Notice / Licensing"]:::sdk
    end

    BrowserEnvironment["Browser Environment\n(DOM, localStorage, cookies)"]:::external
    Backend["Conviva Pulse Backend"]:::external

    %% Data Flows
    HostApp -->|"init(), track methods"| PublicAPI
    PublicAPI -->|"init(config)"| Config
    PublicAPI -->|"trackEvent() / trackPageView()"| Collector

    BrowserEnvironment -->|"DOM events,\nXHR/fetch hooks"| Collector
    Collector -->|"cache event"| Storage
    Collector -->|"emit events"| Network

    Storage -->|"read/write localStorage"| BrowserEnvironment
    Storage -.->|"sync cookies (optional)"| BrowserEnvironment

    Metadata -.->|"extract meta-tags"| BrowserEnvironment
    Metadata -->|"provide metadata"| Collector

    Network -->|"HTTP POST /events"| Backend
    Backend -->|"response with clientId"| Network
    Network -->|"update state"| Storage

    %% Click Events
    click PublicAPI "https://github.com/conviva/conviva-js-appanalytics/blob/main/conviva-js-appanalytics.js"
    click TSdefs "https://github.com/conviva/conviva-js-appanalytics/blob/main/conviva-js-appanalytics.d.ts"
    click Package "https://github.com/conviva/conviva-js-appanalytics/blob/main/package.json"
    click README "https://github.com/conviva/conviva-js-appanalytics/blob/main/README.md"
    click Changelog "https://github.com/conviva/conviva-js-appanalytics/blob/main/CHANGELOG.md"
    click Legal "https://github.com/conviva/conviva-js-appanalytics/blob/main/ConvivaLegalNotice.txt"

    %% Styles
    classDef consumer fill:#d0e6f7,stroke:#0366d6,color:#0366d6
    classDef sdk fill:#d5f5d5,stroke:#239a3b,color:#239a3b
    classDef external fill:#f9e79f,stroke:#d35400,color:#d35400
```
