# universal-connect-project/ucw-app architecture

> Architecture diagram of the GitHub repository universal-connect-project/ucw-app, 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/ucw-app
- Repository: https://github.com/universal-connect-project/ucw-app

## Overview

##### Main Components

- Frontend (UI):
- This is located under apps/ui.
- It handles the widget’s user interface and communicates with backend services via REST/HTTP (e.g., API calls from Widget.tsx, api folder).

- Backend (Server):
- Found under apps/server, the backend is an Express-based (or similar Node.js) service that serves the widget and exposes multiple endpoints.
- It contains modules for authentication, data endpoints (including the delete-user endpoint), institutions, connection endpoints, and a collection of utilities and adapters to communicate with aggregator systems.

- Adapters and External Service Connectors:
- The adapters (mx-adapter, sophtron-adapter, test-adapter) under packages provide pluggable integrations; they abstract external aggregator API interactions.
- Each adapter has its own testing strategy (cypress, jest, playwright) and separate configuration to simulate or proxy external services.

- Infrastructure & Shared Libraries:
- Shared modules like the “utils” packages and “typescript-config” offer common functionality across apps.
- There is also a “packages/utils-dev-dependency” that might include development tools for testing/generation of data.

- Testing & CI/CD:
- The plethora of Cypress, Jest, and Playwright configurations spread in the apps and packages directories, plus GitHub workflows under .github/workflows, represent automated testing, continuous integration, and continuous delivery pipelines.

##### Their Relationships and Data Flows

- The Frontend (UI) component sends requests (HTTP calls) to the Backend (Server).
- The widget UI (loaded via an iframe) communicates with the server endpoints for data, authentication, or token retrieval (/widget, /api/token, data endpoints).

- The Backend acts as the orchestrator:
- It exposes endpoints for the widget, handles authentication (using a token middleware via variables in .env files), and routes requests to proper handlers for institution search, credentials, and connections.
- It interacts with the adapters to fetch data from external aggregator services. For example, the adapter modules (mx, sophtron) manage calls to specific external APIs.
- The server also likely uses services such as an ElasticSearch client (in services/ElasticSearchClient) for indexing or search purposes.

- External Integrations:
- The system makes use of containerized services (Docker/Docker Compose) to possibly run ElasticSearch or other dependencies.
- Depending on environment configuration, authentication might integrate with external authorization systems (e.g., auth0).

##### Architectural Patterns and Design Principles

- Monorepo Structure:
- The repository is organized as multiple packages and apps that share common configuration and libraries, supporting a modular design.

- Separation of Concerns:
- Frontend and Backend responsibilities are clearly separated.
- Within the backend, layers such as API endpoints, authentication middleware, service modules, and adapter integrations are isolated.

- Extensibility via Adapters:
- The design naturally supports plugging in additional adapters for integrating with new external systems or aggregators without major changes to the core backend.

- Automated Testing & CI/CD:
- Multiple testing frameworks (Cypress, Jest, Playwright) underscore a well-tested system with automated pipelines (GitHub workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Apps"
        FE("Frontend (UI)"):::frontend
        BE("Backend Server"):::backend
    end

    FE -->|"HTTP_Requests"| BE

    subgraph "Backend Server Components"
        AUTH("Authentication & API_Endpoints"):::backend
        ES("ElasticSearch Client"):::backend
        BE_TA("Test Adapter (Backend)"):::backend
    end
    BE --> AUTH
    BE --> ES
    BE --> BE_TA

    subgraph "External Adapters"
        MX("MX Adapter"):::adapter
        SOP("Sophtron Adapter"):::adapter
        TAD("Test Adapter (Adapter)"):::adapter
    end
    AUTH -->|"Data_Fetch"| MX
    AUTH -->|"Data_Fetch"| SOP
    BE_TA -->|"Test_Calls"| TAD

    subgraph "Shared Components"
        UTIL("Shared Libs & Utilities"):::shared
        TS("TypeScript Config"):::shared
        DEV("Development Utilities"):::shared
    end
    BE -->|"Uses"| UTIL
    FE -->|"Uses"| UTIL
    UTIL --- TS
    UTIL --- DEV

    subgraph "CI/CD & Testing"
        CICD("CI/CD & Testing (GitHub_Workflows, Cypress, Jest, Playwright)"):::cicd
    end
    FE --> CICD
    BE --> CICD
    DEV --> CICD

    subgraph "External Services"
        AUTHZ("Authorization Service (Auth0)"):::external
        DOCKER("Docker/Container Infrastructure"):::external
    end
    AUTH -->|"AuthToken"| AUTHZ
    BE -->|"Deployment"| DOCKER

    click FE "https://github.com/universal-connect-project/ucw-app/tree/main/apps/ui"
    click FE "https://github.com/universal-connect-project/ucw-app/blob/main/apps/ui/src/Widget.tsx"
    click BE "https://github.com/universal-connect-project/ucw-app/tree/main/apps/server"
    click ES "https://github.com/universal-connect-project/ucw-app/tree/main/apps/server/src/services/ElasticSearchClient"
    click BE_TA "https://github.com/universal-connect-project/ucw-app/tree/main/apps/server/src/test-adapter"
    click MX "https://github.com/universal-connect-project/ucw-app/blob/main/packages/mx-adapter/src/adapter.ts"
    click SOP "https://github.com/universal-connect-project/ucw-app/blob/main/packages/sophtron-adapter/src/adapter.ts"
    click UTIL "https://github.com/universal-connect-project/ucw-app/tree/main/packages/utils"
    click TS "https://github.com/universal-connect-project/ucw-app/tree/main/packages/typescript-config"
    click DEV "https://github.com/universal-connect-project/ucw-app/tree/main/packages/utils-dev-dependency"
    click CICD "https://github.com/universal-connect-project/ucw-app/tree/main/.github/workflows"

    classDef frontend fill:#aed6f1,stroke:#1a5276,stroke-width:2px;
    classDef backend fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef adapter fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef shared fill:#fadbd8,stroke:#cb4335,stroke-width:2px;
    classDef cicd fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef external fill:#f5cba7,stroke:#d35400,stroke-width:2px;
```
