# fintoc-com/fintoc-node architecture

> Architecture diagram of the GitHub repository fintoc-com/fintoc-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fintoc-com/fintoc-node
- Repository: https://github.com/fintoc-com/fintoc-node

## Overview

##### Project Overview and Purpose
- This project is an SDK that provides a natural, API-parallel interface for interacting with the Fintoc API. Its purpose is to make it simple to manage resources such as links, payment intents, webhook endpoints, and the various sub-resources (accounts, movements, invoices, tax returns, etc.) following Fintoc’s API structure.
- The design is built in TypeScript targeting Node.js (requiring Node 10+), and it is structured to mimic the API endpoints as closely as possible, with “manager” objects for CRUD operations.

##### Main Components
a. Fintoc Client Object:
- Central entry point of the SDK.
- Responsible for holding references to the various managers (e.g., links, paymentIntents, webhookEndpoints).

b. Manager Components:
- Each manager (located under src/lib/managers) corresponds to a set of API operations for a specific resource.
- Examples include accountsManager, invoicesManager, linksManager, etc.
- The managers generally provide methods such as “all”, “get”, “create”, “update”, “delete” and are sometimes “attached” to a resource (for example, a Link object exposing an accounts manager).

c. Resource Components:
- These are representations of Fintoc entities (resources) such as Link, Account, Movement, etc.
- Each resource encapsulates its data and operations like “update” or “delete” (often by delegating to the appropriate manager).

d. Mixins and Common Functionality:
- The SDK uses mixins (both managerMixin and resourceMixin) for sharing common patterns and code across managers and resources.
- This modular design allows for code reusability for actions such as serialization and error handling.

e. Supporting Utilities and Types:
- Helper functions (in src/lib/utils.ts) and TypeScript interfaces (in src/interfaces and src/types) define consistent contracts across the system.
- They ensure proper serialization, API request construction, and error mapping.

f. Testing Framework:

##### Relationships and Interactions
- Links Manager
- PaymentIntents Manager
- WebhookEndpoints Manager
- Within the Links Manager, include subordinate managers (as branches) such as:
- Invoices Manager
- TaxReturns Manager
- Subscriptions Manager
- RefreshIntents Manager
- Accounts Manager (which itself connects to the Movements Manager)

##### Architectural Patterns and Design Principles
- That the SDK mirrors the RESTful design of the Fintoc API, making use of:
- Composition: The client is composed of many managers.
- Delegation: Resource objects delegate operations to their corresponding manager.
- Asynchronous operation: Indicate that the “all” method returns an async generator.
- Extensibility via mixins: Common logic is reused across different managers and resources.
- A third for shared utilities and mixins.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Fintoc Client (SDK Entry Point)
    FC["Fintoc Client (SDK Entry Point) – Initializes with API key"]:::client

    %% Managers Layer
    subgraph "Managers Layer"
        LM["Links Manager"]:::manager
        PIM["PaymentIntents Manager"]:::manager
        WM["WebhookEndpoints Manager"]:::manager
    end

    %% Links Manager Sub-Managers
    subgraph "Links Manager Sub-Managers"
        IM["Invoices Manager"]:::manager
        TRM["TaxReturns Manager"]:::manager
        SM["Subscriptions Manager"]:::manager
        RIM["RefreshIntents Manager"]:::manager
        AM["Accounts Manager"]:::manager
    end

    %% Accounts Sub-Manager
    AM --> MM["Movements Manager"]:::manager

    %% Resources Layer
    subgraph "Resources Layer"
        LR["Link Resource"]:::resource
        AR["Account Resource"]:::resource
        MR["Movement Resource"]:::resource
        IR["Invoice Resource"]:::resource
        PIR["PaymentIntent Resource"]:::resource
        WR["WebhookEndpoint Resource"]:::resource
        TR["TaxReturn Resource"]:::resource
        SR["Subscription Resource"]:::resource
    end

    %% Mixins & Utilities
    MixinManager["Manager Mixin"]:::mixin
    MixinResource["Resource Mixin"]:::mixin
    UT["Utilities & Types"]:::utility

    %% External API
    API["Fintoc API (External Service)"]:::external

    %% Testing Suite
    subgraph "Testing Suite"
        CT["Client Tests"]:::testing
        MT["Manager Tests"]:::testing
        MiT["Mixin Tests"]:::testing
        RT["Resource & Utility Tests"]:::testing
    end

    %% Connections: Fintoc Client to Managers
    FC -->|"initializes"| LM
    FC -->|"initializes"| PIM
    FC -->|"initializes"| WM

    %% Links Client to External API
    FC ---|"HTTP calls"| API

    %% Connections: Links Manager to its Sub-Managers
    LM -->|"manages"| IM
    LM -->|"manages"| TRM
    LM -->|"manages"| SM
    LM -->|"manages"| RIM
    LM -->|"manages"| AM

    %% Managers to Resources
    LM -->|"calls CRUD"| LR
    PIM -->|"calls CRUD"| PIR
    WM -->|"calls CRUD"| WR
    IM -->|"calls CRUD"| IR
    TRM -->|"calls CRUD"| TR
    SM -->|"calls CRUD"| SR
    AM -->|"calls CRUD"| AR
    MM -->|"calls CRUD"| MR

    %% Mixins integrated with Managers and Resources via utility
    MixinManager ---|"injects"| LM
    MixinManager ---|"injects"| PIM
    MixinManager ---|"injects"| WM
    MixinManager ---|"injects"| IM
    MixinManager ---|"injects"| TRM
    MixinManager ---|"injects"| SM
    MixinManager ---|"injects"| RIM
    MixinManager ---|"injects"| AM
    MixinManager ---|"injects"| MM

    MixinResource ---|"injects"| LR
    MixinResource ---|"injects"| AR
    MixinResource ---|"injects"| MR
    MixinResource ---|"injects"| IR
    MixinResource ---|"injects"| PIR
    MixinResource ---|"injects"| WR
    MixinResource ---|"injects"| TR
    MixinResource ---|"injects"| SR

    UT ---|"supports"| FC
    UT ---|"supports"| LM
    UT ---|"supports"| WM
    UT ---|"supports"| PIM
    UT ---|"supports"| IM
    UT ---|"supports"| TRM
    UT ---|"supports"| SM
    UT ---|"supports"| RIM
    UT ---|"supports"| AM
    UT ---|"supports"| MM
    UT ---|"supports"| LR
    UT ---|"supports"| AR
    UT ---|"supports"| MR
    UT ---|"supports"| IR
    UT ---|"supports"| PIR
    UT ---|"supports"| WR
    UT ---|"supports"| TR
    UT ---|"supports"| SR

    %% Testing Suite Connections
    FC ---|"verified by"| CT
    LM ---|"verified by"| MT
    PIM ---|"verified by"| MT
    WM ---|"verified by"| MT
    IM ---|"verified by"| MT
    TRM ---|"verified by"| MT
    SM ---|"verified by"| MT
    RIM ---|"verified by"| MT
    AM ---|"verified by"| MT
    MM ---|"verified by"| MT
    MixinManager ---|"verified by"| MiT
    MixinResource ---|"verified by"| MiT
    LR ---|"verified by"| RT
    AR ---|"verified by"| RT
    MR ---|"verified by"| RT
    IR ---|"verified by"| RT
    PIR ---|"verified by"| RT
    WR ---|"verified by"| RT
    TR ---|"verified by"| RT
    SR ---|"verified by"| RT
    UT ---|"verified by"| RT

    %% Click Events
    click FC "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/client.ts"
    click LM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/linksManager.ts"
    click PIM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/paymentIntentsManager.ts"
    click WM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/webhookEndpointsManager.ts"
    click IM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/invoicesManager.ts"
    click TRM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/taxReturnsManager.ts"
    click SM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/subscriptionsManager.ts"
    click RIM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/refreshIntentsManager.ts"
    click AM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/accountsManager.ts"
    click MM "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/managers/movementsManager.ts"
    click LR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/link.ts"
    click AR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/account.ts"
    click MR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/movement.ts"
    click IR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/invoice.ts"
    click PIR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/paymentIntent.ts"
    click WR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/webhookEndpoint.ts"
    click TR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/taxReturn.ts"
    click SR "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/resources/subscription.ts"
    click MixinManager "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/mixins/managerMixin.ts"
    click MixinResource "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/mixins/resourceMixin.ts"
    click UT "https://github.com/fintoc-com/fintoc-node/blob/master/src/lib/utils.ts"
    click CT "https://github.com/fintoc-com/fintoc-node/tree/master/src/spec/client"
    click MT "https://github.com/fintoc-com/fintoc-node/tree/master/src/spec/managers"
    click MiT "https://github.com/fintoc-com/fintoc-node/tree/master/src/spec/mixins"
    click RT "https://github.com/fintoc-com/fintoc-node/tree/master/src/spec/resources & src/spec/utils"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef manager fill:#C6E0B4,stroke:#006400,stroke-width:2px;
    classDef resource fill:#FFD8B1,stroke:#FF8C00,stroke-width:2px;
    classDef mixin fill:#E6E6FA,stroke:#4B0082,stroke-width:2px;
    classDef utility fill:#B0E0E6,stroke:#4682B4,stroke-width:2px;
    classDef testing fill:#F4CCCC,stroke:#CC0000,stroke-width:2px;
    classDef external fill:#F0F0F0,stroke:#808080,stroke-dasharray: 5, 5,stroke-width:2px;
```
