# mercoa-finance/react architecture

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

- Interactive diagram: https://gitdiagram.com/mercoa-finance/react
- Repository: https://github.com/mercoa-finance/react

## Overview

##### Project Type and Purpose
- This is a React component library (package name “@mercoa/react”) that provides UI components, utilities, and a context provider (`MercoaSession`) for embedding the Mercoa entity portal in host applications.
- It includes:
- A “src” folder with library source code (components, modules, shared utilities).
- A “docs” folder implementing the public documentation site (Next.js + MDX).
- An “examples” folder with several sample Next.js applications demonstrating library usage.
- Build/config files (Vite, Tailwind, TypeScript) and a GitHub Actions workflow for publishing to npm.

##### File Structure
- Top-level modules:
- src/components – exported React components
- src/modules – domain-driven feature modules (common, counterparties, payables, receivables) each with API queries/mutations, hooks, providers, stores, UI subcomponents
- src/lib – shared utilities, style helpers, react-query wrappers
- docs – Next.js application providing MDX-based component and API documentation
- examples – three standalone Next.js demo apps showing basic integration, advanced Auth flows, styling options
- Config & tooling:
- vite.config.ts – library bundling configuration
- tailwind.config.ts & CSS files – styling pipeline
- .github/workflows/publish.yml – CI/CD publishing pipeline
- tsconfig.json & eslint/prettier – linting/type checking

##### README for Additional Insights
- Emphasizes that the library ships with two CSS files (tailwind.base.css, style.css) and relies on a React Context (`MercoaSession`) that must wrap any host application.
- Points to an external docs site (docs.mercoa.com) generated from the “docs” folder.
- Shows that host apps import components directly from npm, wrap in `MercoaSession`, and consume domain modules (Payables, Receivables, Counterparties, etc.).

##### Main Components and Their Relationships
- Core Library (src/)
- MercoaSession Context Provider
- Domain Modules (common, counterparties, payables, receivables)
- UI Components (e.g., PayablesTable, ReceivablePreview, ApprovalPolicy)
- Utilities & React-Query hooks
- Build & Distribution
- Vite → produces ESM/CJS bundles + CSS assets → npm registry
- GitHub Actions → triggers on tag → runs build/tests → publishes
- Documentation Site
- Next.js + MDX → imports built library locally → renders docs/components examples
- Deployed as static site (docs folder)
- Example Applications
- Three Next.js demo apps → each imports `@mercoa/react` → wraps in `MercoaSession` → uses domain components
- External Dependencies
- React, React-DOM
- React Query
- TailwindCSS
- Next.js (docs & examples)

##### Architectural Patterns & Design Principles
- Domain-Driven Modularization: each domain (Payables, Receivables, Counterparties) lives in its own folder with API layer, hooks, providers, stores, and UI components.
- Context-Based Configuration: a single `MercoaSession` context provider supplies authentication and global settings to all components.
- Pluggable UI Library: separated into sub-directories under `src/components` and `src/modules`, promoting tree-shaking and selective imports.
- Documentation as Code: documentation lives alongside source in “docs” and uses MDX to mix examples with narrative.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        REACT["React"]:::external
        REACTDOM["React-DOM"]:::external
        RQUERY["React Query"]:::external
        TWCSS["TailwindCSS"]:::external
        NEXTJS["Next.js"]:::external
    end

    %% Core Library
    subgraph "Core Library (@mercoa/react)" 
        direction TB
        MS["MercoaSession Context Provider"]:::library
        GUC["Generic UI Components"]:::library
        SU["Shared Utilities & React-Query Wrappers"]:::library
        subgraph "Domain Modules" 
            direction TB
            DM1["Common"]:::library
            DM2["Counterparties"]:::library
            DM3["Payables"]:::library
            DM4["Receivables"]:::library
        end
    end

    %% Build & CI/CD
    subgraph "Build & CI/CD Pipeline"
        direction TB
        VITE["Vite Bundler Configuration"]:::ci
        GH["GitHub Actions Publish Workflow"]:::ci
    end

    %% Artifacts
    NPM["npm Registry (ESM/CJS + CSS)"]:::ci

    %% Documentation Site
    subgraph "Documentation Site (docs)"
        direction TB
        DOCSAPP["Next.js + MDX Site"]:::docs
        DOCSHELP["docs/components/helpers.tsx\n& docs/mockData.ts"]:::docs
        DOCTHEME["docs/theme.config.tsx"]:::docs
    end

    %% Example Applications
    subgraph "Example Applications"
        direction TB
        EX1["nextjs-basic"]:::examples
        EX2["nextjs-react-v2-demo"]:::examples
        EX3["nextjs-standard-demo"]:::examples
    end

    %% Relationships
    REACT -->|used by| MS
    REACTDOM -->|used by| MS
    RQUERY -->|used by| SU
    TWCSS -->|styles for| GUC
    NEXTJS -->|runs| DOCSAPP
    MS -->|part of| GUC
    MS -->|provides context| DM1
    MS -->|provides context| DM2
    MS -->|provides context| DM3
    MS -->|provides context| DM4

    GUC -->|imports| SU
    DM1 -->|uses| SU
    DM2 -->|uses| SU
    DM3 -->|uses| SU
    DM4 -->|uses| SU

    MS & GUC & SU & DM1 & DM2 & DM3 & DM4 -->|source code| VITE
    MS & GUC & SU & DM1 & DM2 & DM3 & DM4 -->|source code| GH
    VITE -->|builds artifacts| NPM
    GH -->|publishes| NPM

    NPM -->|consumed by| DOCSAPP
    NPM -->|consumed by| EX1
    NPM -->|consumed by| EX2
    NPM -->|consumed by| EX3

    DOCSHELP -->|used in| DOCSAPP
    DOCTHEME -->|configures| DOCSAPP

    EX1 -->|wraps with| MS
    EX2 -->|wraps with| MS
    EX3 -->|wraps with| MS

    EX1 -->|calls hooks| DM3
    EX1 -->|calls hooks| DM4
    EX2 -->|calls hooks| DM2
    EX2 -->|calls hooks| DM3
    EX3 -->|calls hooks| DM1
    EX3 -->|calls hooks| DM4

    %% Click Events
    click MS "https://github.com/mercoa-finance/react/blob/main/src/index.tsx"
    click GUC "https://github.com/mercoa-finance/react/tree/main/src/components/"
    click DM1 "https://github.com/mercoa-finance/react/tree/main/src/modules/common/"
    click DM2 "https://github.com/mercoa-finance/react/tree/main/src/modules/counterparties/"
    click DM3 "https://github.com/mercoa-finance/react/tree/main/src/modules/payables/"
    click DM4 "https://github.com/mercoa-finance/react/tree/main/src/modules/receivables/"
    click SU "https://github.com/mercoa-finance/react/tree/main/src/lib/"
    click VITE "https://github.com/mercoa-finance/react/blob/main/vite.config.ts"
    click GH "https://github.com/mercoa-finance/react/blob/main/.github/workflows/publish.yml"
    click NPM "https://github.com/mercoa-finance/react/tree/main/n/a"
    click DOCSAPP "https://github.com/mercoa-finance/react/tree/main/docs/"
    click DOCSHELP "https://github.com/mercoa-finance/react/blob/main/docs/components/helpers.tsx"
    click DOCSHELP "https://github.com/mercoa-finance/react/blob/main/docs/mockData.ts"
    click DOCTHEME "https://github.com/mercoa-finance/react/blob/main/docs/theme.config.tsx"
    click EX1 "https://github.com/mercoa-finance/react/tree/main/examples/nextjs-basic/"
    click EX2 "https://github.com/mercoa-finance/react/tree/main/examples/nextjs-react-v2-demo/"
    click EX3 "https://github.com/mercoa-finance/react/tree/main/examples/nextjs-standard-demo/"

    %% Styles
    classDef library fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef ci fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef docs fill:#D1FFD6,stroke:#333,stroke-width:1px
    classDef examples fill:#E5D4FF,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
```
