# universal-connect-project/ucp-hosted-app architecture

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

## Overview

##### Project Type and Purpose
- This is a monorepo managed with TurboRepo that consolidates multiple UCP-hosted services and applications. It is not a customer-hosted service but supports integration with a separate customer-hosted UCW-App.
- The README lists three primary applications:
– Authentication Service: Manages authentication and API key management (leverages Auth0).
– Institution Service: Manages CRUD operations on an institution list and handles institution data.
– UCP UI: A dashboard web application that interacts with the backend services for account management and service operations.
- There’s also a Performance Service (and likely additional shared packages like backend-utils and shared-utils) that provides metrics or specialized functions, which should be included if it’s part of the deployed architecture.

##### Main Components and Their Structure
- Backend Services (Microservices):
– Authentication Service (located in apps/authentication-service): Contains configuration files, middleware (e.g., error handling, auth middleware), and resources for handling clients, users, and token utilities.
– Institution Service (located in apps/institution-service): Includes controllers, models, routes, migrations, seeders, and services for handling institutions and aggregator integrations.
– Performance Service (located in apps/performance-service): Manages event handling, performance metrics, and integrates with external systems (such as InfluxDB and Redis) for storing and retrieving performance data.
- Frontend Application:
– UCP UI (located in apps/ucp-ui): A React-based dashboard application with multiple modules (e.g., Institutions, Authentication Wrapper, shared UI components) that interacts with the backend.
- Shared and Utility Packages:
– packages/backend-utils: Contains shared functions (e.g., access token management, validation functions) used across backend services.
– packages/shared-utils: Provides common constants and utilities.
- Supporting Files and Configuration:
– CI/CD configurations in the .github/workflows directory indicate rigorous testing (e2e, unit, linting, performance) ensuring each component is verified.
– Deployment files (Procfile, app.json, nodemon.json, etc.) present in various apps indicate how these services are deployed and managed.
– TurboRepo configuration (turbo.json) for managing build and dependency processes.

##### Relationships and Interactions
- Data Flow:
– The UCP UI (frontend) sends HTTP requests or REST API calls to the Authentication and Institution services.
– The Authentication Service provides API key management and ensures that only validated users interact with other services.
– The Institution Service receives requests from both the UI and other systems (like the external UCW-App) and interacts with the database (shown by the migrations, seeders, and defined models).
– The Performance Service collects and exposes performance-related metrics, likely interfacing with data stores like Redis (for caching/storage) and InfluxDB (for time-series metrics).
- Shared utilities or libraries are used by multiple services ensuring consistent validation, token handling, and configuration across services.

##### Architectural Patterns and Design Principles
- Microservices Architecture: Each application (Authentication, Institution, Performance) is relatively self-contained with its own routing, controllers, middleware, and testing suites. They expose APIs for interaction, following separation of concerns and scalability.
- Modular UI Development: The UCP UI is structured with clear component boundaries, feature modules (like Institution management, API key management, etc.), and uses React ecosystem conventions.
- Shared Code Reusability: Common functionalities encapsulated in packages (backend-utils, shared-utils) reduce code duplication and enforce standard practices.
- CI/CD Integration: Extensive GitHub workflows reflect automated testing, linting, and performance monitoring.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    UCWApp["UCW-App"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        UcpUI["UCP UI Dashboard"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        Auth["Authentication Service"]:::backend
        Inst["Institution Service"]:::backend
        Perf["Performance Service"]:::backend
        DB["Database"]:::db
        Redis["Redis Cache"]:::db
        Influx["InfluxDB"]:::db
    end

    %% Shared Packages
    subgraph "Shared Packages"
        BackendUtils["Shared Backend Utilities"]:::package
        SharedUtils["Shared Utilities"]:::package
    end

    %% CI/CD Pipeline
    CiCd["CI/CD Pipeline"]:::ci

    %% Data Flow Connections
    UcpUI -->|"APIRequest"| Auth
    UcpUI -->|"APIRequest"| Inst
    UCWApp -->|"RESTCall"| Inst
    Auth -->|"TokenValidation"| Inst
    Inst -->|"CRUD"| DB
    Perf -->|"StoreMetrics"| Redis
    Perf -->|"StoreMetrics"| Influx

    %% Shared Utilities Usage (dotted for shared dependency)
    Auth ---|"uses"| BackendUtils
    Inst ---|"uses"| BackendUtils
    Perf ---|"uses"| BackendUtils
    Auth ---|"uses"| SharedUtils
    Inst ---|"uses"| SharedUtils
    Perf ---|"uses"| SharedUtils

    %% CI/CD Integration
    CiCd ---|"Deploys/Tests"| UcpUI
    CiCd ---|"Deploys/Tests"| Auth
    CiCd ---|"Deploys/Tests"| Inst
    CiCd ---|"Deploys/Tests"| Perf

    %% Click Events
    click UcpUI "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/apps/ucp-ui"
    click Auth "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/apps/authentication-service"
    click Inst "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/apps/institution-service"
    click Perf "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/apps/performance-service"
    click BackendUtils "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/packages/backend-utils"
    click SharedUtils "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/packages/shared-utils"
    click CiCd "https://github.com/universal-connect-project/ucp-hosted-app/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef package fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef ci fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef db fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
```
