# universal-connect-project/universal-connect-widget architecture

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

- Interactive diagram: https://gitdiagram.com/universal-connect-project/universal-connect-widget
- Repository: https://github.com/universal-connect-project/universal-connect-widget

## Overview

##### Main architectural areas
- Frontend / Client
- This includes the widget UI and other consumer‐facing elements.
- In the “application/src”, you see many React components, Redux store files and hooks. Also note the mobile-specific directories under “application/android” and “application/ios” that use Capacitor.
- Backend / Server
- The “application/server” directory shows an Express‐based Node.js backend that provides API endpoints (connectApiExpress.js, server.js) and routes requests from the widget.
- The server code also contains middleware and utilities (infra, logger, utils) to support routing, error handling, and connection setup.
- Integration / Service Clients
- Look at “application/server/serviceClients” – each subfolder (e.g., akoyaClient, finicityClient, mxClient, etc.) implements a client for a third‐party provider.
- In “application/server/providers”, integration “adapters” for each provider are implemented. These abstract the underlying APIs so that which provider is used can be transparently switched based on performance, cost, or availability.
- Shared / Reusable Components
- The “application/shared” directory holds common elements used by both frontend and backend (for example, shared contracts, connection procedures, and utilities).
- API Specification / Documentation
- The “openapi” directory contains the API definitions and component contracts which are important for the integration point and communication standards.
- Example / Quick Integration
- The “example” directory is used to show how to embed the widget into an application, which can be highlighted as an “integration sample” component.

##### Out the relationships and data flows
- A User or a third-party application embeds the Universal Connect Widget (Frontend) into their website or mobile app.
- The Widget (running primarily in the browser or inside a mobile container) communicates with the backend API (Node server) via HTTP(s) calls.
- The backend API processes the requests, and based on the client’s data and performance needs, it calls one or more service clients.
- The Service Clients communicate with external data providers (MX, Finicity, Sophtron, Akoya, etc.) to retrieve, process, and relay financial data (accounts, transactions, etc.).
- Both frontend and backend share common data contracts (using Verifiable Credentials and FDX standards as noted in the README) ensuring data is formatted consistently regardless of provider.
- The API uses asynchronous flows, error handling (with fallback or reroute for fault tolerance), and logging/monitoring to maintain performance and reliability.

##### Important architectural patterns and principles
- Separation of concerns – clearly separated layers between client (UI), server (API), and integration (service clients).
- Modularity – each third-party provider is handled by its own module (see separate directories under “providers” and “serviceClients”).
- Platform versatility – separate configurations and implementations exist for Android and iOS in addition to the web-based widget.
- Resiliency and Performance – built-in routing (even at connection selection level) and fault tolerance to select the fastest/cheapest provider.
- Use of standards – implementation of the WC3 Verifiable Credentials and data models ensures consistent, secure data handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User / Client Application"]:::client

    subgraph "Frontend / Client"
        Widget["Universal Connect Widget (React/Redux)"]:::frontend
        MobileAndroid["Mobile App (Android) - Capacitor"]:::mobile
        MobileiOS["Mobile App (iOS) - Capacitor"]:::mobile
    end

    subgraph "Backend / Server"
        APIServer["API Server (Express/Node.js)"]:::backend
        Infrastructure["Infrastructure"]:::backend
        Utilities["Utilities"]:::backend
        %% Integration / Service Clients Subgraph
        subgraph "Integration / Service Clients"
            Akoya["Akoya Service Client"]:::integration
            Finicity["Finicity Service Client"]:::integration
            MX["MX Service Client"]:::integration
            Sophtron["Sophtron Service Client"]:::integration
            Providers["Providers / Adapters"]:::integration
        end
    end

    Shared["Shared Components & API Specifications"]:::shared
    Example["Quick Integration Example"]:::example
    External["External Data Providers (MX, Finicity, Sophtron, Akoya)"]:::external

    %% Relationships
    User -->|"embeds"| Widget
    Widget -->|"HTTP/REST"| APIServer
    APIServer -->|"calls"| Akoya
    APIServer -->|"calls"| Finicity
    APIServer -->|"calls"| MX
    APIServer -->|"calls"| Sophtron
    Akoya -->|"fetches"| External
    Finicity -->|"fetches"| External
    MX -->|"fetches"| External
    Sophtron -->|"fetches"| External
    APIServer -->|"utilizes"| Infrastructure
    APIServer -->|"utilizes"| Utilities
    Widget -->|"shares"| Shared
    APIServer -->|"shares"| Shared
    Example -->|"demonstrates"| Widget

    %% Click Events
    click Widget "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/src"
    click MobileAndroid "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/android"
    click MobileiOS "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/ios"
    click APIServer "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server"
    click Infrastructure "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/infra"
    click Utilities "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/utils"
    click Akoya "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/serviceClients/akoyaClient"
    click Finicity "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/serviceClients/finicityClient"
    click MX "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/serviceClients/mxClient"
    click Sophtron "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/serviceClients/sophtronClient"
    click Providers "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/server/providers"
    click Shared "https://github.com/universal-connect-project/universal-connect-widget/tree/main/application/shared"
    click Shared "https://github.com/universal-connect-project/universal-connect-widget/tree/main/openapi"
    click Example "https://github.com/universal-connect-project/universal-connect-widget/tree/main/example"

    %% Styles
    classDef client fill:#F5A623,stroke:#333,stroke-width:2px;
    classDef frontend fill:#4FC3F7,stroke:#333,stroke-width:2px;
    classDef mobile fill:#81D4FA,stroke:#333,stroke-width:2px;
    classDef backend fill:#AED581,stroke:#333,stroke-width:2px;
    classDef integration fill:#FFB74D,stroke:#333,stroke-width:2px;
    classDef shared fill:#FFF176,stroke:#333,stroke-width:2px;
    classDef example fill:#FF8A65,stroke:#333,stroke-width:2px;
    classDef external fill:#B0BEC5,stroke:#333,stroke-width:2px;
```
