# xeroapi/xero-node architecture

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

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

## Overview

Based on our analysis of the file tree and README, this project is the official xero-node SDK—a TypeScript/JavaScript library designed to serve as a comprehensive client for interfacing with Xero’s different APIs (Accounting, Assets, Bankfeeds, Files, Projects, and the various Payroll APIs). Its primary purpose is to simplify integration with Xero’s services via OAuth2 (and OpenID Connect) authentication flows and to provide fully generated endpoints and data models based on the Xero OpenAPI specs.

##### Main Components
- Xero Client Initialization & Configuration: Show the configuration aspect where a developer instantiates a XeroClient (as seen in src/XeroClient.ts and src/index.ts) with parameters like clientId, clientSecret, redirectUris, scopes, and optional settings such as timeouts and clock tolerance.
- Building the consent URL (using xero.buildConsentUrl)
- Exchanging a code for a token set via xero.apiCallback
- Refreshing tokens with methods like refreshToken and refreshWithRefreshToken (this is all underpinned by the openid-client library).
- API Clients & Generated Endpoints: This is the heart of the SDK. Under the “src/gen” directory, note the distinct subdirectories:
- “api” contains specific services for Accounting, Assets, Bankfeeds, Files, Projects, and Payroll (AU, NZ, UK).
- “model” contains the corresponding data models (types, interfaces) used by these APIs.
- Helper Methods & Utilities: Include support components such as API error handling, testing utilities (located in src/test) and helper functions found at the root (e.g., token management).
- Documentation & External Channels: Although not part of the runtime, the docs folder and GitHub configuration files (workflows, issue templates, etc.) support project governance and integration/deployment processes.

##### Component Relationships and Data Flow
- The XeroClient component orchestrates the work between authentication and API clients.
- Configuration and initialization trigger the authentication sequence.
- Once authenticated, the client uses the generated API modules (for each API set) to send requests.
- Upon making API calls, the OAuth2 token (or refreshed token) is attached to requests heading toward Xero’s remote endpoints.
- The helper methods wrap around these processes to manage token storage, refresh, and error handling.

##### Architectural Patterns & Design Principles
- Modular Generation: Emphasize that the SDK leverages code generation (from Xero’s OpenAPI specs) to produce a modular structure where each API set is self-contained.
- Separation of Concerns: Highlight that responsibility is split between authentication (handled in XeroClient and openid-client integrations) and business API endpoints (under src/gen/api and src/gen/model).
- Extensibility: Any additional endpoints or integrations can be added through similar patterns, so it is beneficial to show how separation (e.g., by directory/module) aids scalability.

##### Technologies and Frameworks
- TypeScript as the core language (evidenced from tsconfig.json and .ts files).
- openid-client integration for OAuth2.0 and OpenID Connect.
- Testing with Jest (as seen in jest.config.js and src/test).
- GitHub Actions for CI/CD (workflows in .github/workflows).
- Node.js runtime as the base platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        XeroClient["XeroClient (Configuration & Initialization)"]:::core
        AuthModule["Authentication Module (OAuth2/OpenID Connect)"]:::core
    end

    %% Generated Code
    subgraph "Generated Code"
        APIClients["API Clients (Accounting, Assets, Bankfeeds, Files, Projects, Payroll-AU, Payroll-NZ, Payroll-UK)"]:::generated
        DataModels["Data Models (Generated)"]:::generated
    end

    %% Support & Config
    subgraph "Support & Config"
        Helper["Helper Methods & Utilities"]:::support
        Testing["Testing & CI/CD"]:::support
        Docs["Documentation & External Channels"]:::support
    end

    %% External Xero API
    XeroAPI["Xero External API"]:::external

    %% Connections
    XeroClient -->|"initiateAuth"| AuthModule
    XeroClient -->|"configures"| Helper
    Helper -->|"manages_tokens"| AuthModule
    Helper -->|"handles_errors"| APIClients
    AuthModule -->|"provideToken"| APIClients
    APIClients -->|"callAPI"| XeroAPI

    %% Click Events for Xero Client Initialization & Configuration
    click XeroClient "https://github.com/xeroapi/xero-node/blob/master/src/XeroClient.ts"
    click XeroClient "https://github.com/xeroapi/xero-node/blob/master/src/index.ts"

    %% Click Event for OAuth2 / OpenID Connect Authentication Module
    click AuthModule "https://github.com/xeroapi/xero-node/blob/master/src/XeroClient.ts"

    %% Click Event for API Clients & Generated Endpoints
    click APIClients "https://github.com/xeroapi/xero-node/tree/master/src/gen/api/"

    %% Click Event for Data Models for APIs
    click DataModels "https://github.com/xeroapi/xero-node/tree/master/src/gen/model/"

    %% Click Events for Helper Methods & Utilities
    click Helper "https://github.com/xeroapi/xero-node/blob/master/src/model/ApiError.ts"

    %% Click Events for Testing & CI/CD Configuration
    click Testing "https://github.com/xeroapi/xero-node/tree/master/src/test/"
    click Testing "https://github.com/xeroapi/xero-node/blob/master/jest.config.js"
    click Testing "https://github.com/xeroapi/xero-node/tree/master/.github/workflows/"

    %% Click Events for Documentation & External Channels
    click Docs "https://github.com/xeroapi/xero-node/tree/master/docs/"
    click Docs "https://github.com/xeroapi/xero-node/tree/master/.github/ISSUE_TEMPLATE/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef generated fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef support fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
