# jpmorgan-payments/embedded-finance architecture

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

- Interactive diagram: https://gitdiagram.com/jpmorgan-payments/embedded-finance
- Repository: https://github.com/jpmorgan-payments/embedded-finance

## Overview

Based on our file structure and README analysis, this project is a full-stack showcase application for Embedded Finance. It comprises separate but related components: a React-based client UI, a server component that facilitates API calls (either to mocked internal endpoints or the live UAT APIs), an SDK (embedded-finance-sdk) for validation and payment logic, and a collection of embedded UI components (embedded-components) that provide reusable interface elements. There’s also a Postman collection to directly interface with the API endpoints.

##### Main Components
- Client Application (under “app/client”):
– A React front-end written in TypeScript/JavaScript.
– Contains feature-specific directories (Accounts, Authentication, Cases, DebitCards, Onboarding, etc.), state management, hooks, and UI components that interact with the Embedded Finance APIs.
- API Server (under “app/server”):
– A Node/Express (or similar) server that serves as the backend for API calls.
– Handles SSL setup for secure communication with external UAT endpoints (using certificate files as described in the README).
- Embedded Finance SDK (under “embedded-finance-sdk”):
– A separate package that encapsulates validation logic and domain-specific payment schemas.
– Published as a standalone npm package, it represents a critical library dependency.
- Embedded UI Components (under “embedded-components”):
– A library of reusable UI components (with components for form controls, onboarding wizards, linked account setup, etc.) especially crafted for the Embedded Finance user experience.
- External Components:
– Postman Collection (under “postman”) for direct API testing and demonstration.
– External APIs (represented by the live UAT endpoints and ForgeRock authentication service) that the server connects to when not using mocked responses.

##### Relationships & Data Flow
- The Client UI communicates with the API Server for all backend operations (e.g., submitting payment requests, account lookups).
- The API Server (if configured to use live endpoints) securely communicates with external systems (J.P. Morgan’s UAT environment and ForgeRock) using SSL authentication.
- The client makes use of the Embedded Finance SDK to validate data (for payments, debit cards, etc.) before sending requests.
- The UI is built using reusable components from the Embedded Components library—these components interact with stateful hooks and feature-specific modules.
- Mock Service Worker (MSW) is integrated into the client to intercept network calls for testing or demo purposes, as noted in the README.

##### Key Architectural Patterns & Design Principles
- Separation of Concerns: Clearly divide the UI (client), business logic/API interactions (server), and re-usable libraries (SDK and UI components).
- Modular Architecture: Each “feature” (e.g., Authentication, Transactions, Onboarding) is organized in its own folder, indicating a modular or domain-driven design approach.
- Environment Configuration: Use of environment variables and configuration files (e.g., VITE_FR_URL and VITE_FR_CLIENT) to swap between mocked data and live endpoint behavior.
- External Integration: SSL certificate management and secure API calls denote best practices in interfacing with external systems.

##### Final Elements
- Component names and directory mappings (as noted above).
- Annotations noting the use of MSW for service worker-based API mocking and the secure connection setup in the server configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend: Client Application and Feature Modules
    subgraph "Client Application"
        ClientUI["Client UI (React App)"]:::frontend
        subgraph "Feature Modules"
            Accounts["Accounts Module"]:::frontend
            Auth["Authentication Module"]:::frontend
            Cases["Cases Module"]:::frontend
            DebitCards["DebitCards Module"]:::frontend
            Onboarding["Onboarding Module"]:::frontend
        end
    end

    %% Backend: API Server
    API["API Server (Node/Express)"]:::backend

    %% Reusable Libraries
    SDK["Embedded Finance SDK"]:::library
    EmbeddedUI["Embedded UI Components Library"]:::library

    %% External Systems
    External["External Services (J.P. Morgan UAT & ForgeRock)"]:::external

    %% Testing Tool
    Postman["Postman Collection (API Testing)"]:::external

    %% Mock Service Worker
    MSW["MSW (Mock Service Worker)"]:::frontend

    %% Relationships & Data Flow
    ClientUI -->|"APIRequest"| API
    API -->|"SSLSecured"| External
    ClientUI -->|"ValidationCall"| SDK
    ClientUI -->|"UIRendering"| EmbeddedUI
    ClientUI -->|"MockInterception"| MSW
    Postman -->|"APITest"| API

    %% Feature Modules integrate with Client UI
    Accounts -->|"Integrates"| ClientUI
    Auth -->|"Integrates"| ClientUI
    Cases -->|"Integrates"| ClientUI
    DebitCards -->|"Integrates"| ClientUI
    Onboarding -->|"Integrates"| ClientUI

    %% Click Events
    click ClientUI "https://github.com/jpmorgan-payments/embedded-finance/tree/main/app/client/"
    click API "https://github.com/jpmorgan-payments/embedded-finance/tree/main/app/server/"
    click SDK "https://github.com/jpmorgan-payments/embedded-finance/tree/main/embedded-finance-sdk/"
    click EmbeddedUI "https://github.com/jpmorgan-payments/embedded-finance/tree/main/embedded-components/"
    click Postman "https://github.com/jpmorgan-payments/embedded-finance/blob/main/postman/Embedded Payments - Core API Requests.postman_collection.json"

    %% Styles
    classDef frontend fill:#a6cee3,stroke:#0868ac,stroke-width:2px;
    classDef backend fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef external fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef library fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
```
