# churchtools/churchtools-js-client architecture

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

- Interactive diagram: https://gitdiagram.com/churchtools/churchtools-js-client
- Repository: https://github.com/churchtools/churchtools-js-client

## Overview

##### Main components
- Core Library Module: Represent the primary functionality implemented in the src/ folder. This includes:
- churchtoolsClient (src/churchtoolsClient.ts): The gateway for setting the base URL, making API calls (get, post, put, etc.), and handling the login process.
- Logging (src/logging.ts): Handles log activation and possibly debugging output.
- Error Handling (src/errorHelper.ts and src/NoJSONError.ts): Utility functions for managing errors.
- URL Helpers (src/urlHelper.ts): Functions to validate and manipulate ChurchTools URLs.
- Examples: Indicate the two practical usage scenarios provided - one in Browser (examples/Browser) and one in Node.js (examples/Node.js) – to demonstrate how clients integrate the library.
- Test Suite: The tests contained in the test/ directory show how the library is expected to behave across its modules.
- Build & Config Components: Files like tsconfig.json, webpack.config.js, and configuration files (babel, eslint, prettier, etc.) which aren’t runtime components but show the compiled and coding standard architecture.
- External Dependencies: Based on the README, note dependencies such as axios, axios-cookiejar-support, and tough-cookie (for Node.js) that are needed when integrating the library in a Node.js environment.

##### Relationships and interactions
- At the core, the churchtoolsClient module acts as the interface between client applications and the ChurchTools API.
- How the client:
- Sets the base URL using setBaseUrl.
- Manages session cookies and authentication (with optional cookie jar support for Node.js).
- Automatically handles login renewal when sessions expire.
- Flow of API requests through exported HTTP methods (get, post, put, patch, deleteApi) which eventually communicate with ChurchTools’ REST API.
- Browser Integration: Illustrate that the bundled script is loaded into a web page and interacts with a ChurchTools instance.

##### Architectural patterns and design principles
- Abstraction: The library abstracts the complexities of API interactions and session management.
- Modularity: Separation in directories (src for source logic, test for validations, examples for integration), which clarifies component responsibilities.
- Extensibility: The design supports multiple instances through object instantiation (see example with ChurchtoolsClient in the README), so include a note on how multiple client objects can manage simultaneous API connections.
- Environment-specific configuration: Different handling for browser versus Node.js, indicating dependency injection and environment detection.

##### Relevant technologies and frameworks
- JavaScript/TypeScript as the main language.
- Build tools like webpack and TypeScript Compiler (tsconfig.json) that compile the source.
- ESLint, Prettier, and Babel for code quality and transformation.
- External libraries such as axios (for HTTP requests) and cookie-related modules in the Node.js context.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Applications
    subgraph "Client Applications"
        BrowserApp["Browser Application"]:::client
        NodeApp["Node.js Application"]:::client
    end

    %% Core Library Modules (src folder)
    subgraph "Core Library (src)"
        LC["Library Core"]:::library
        CT["churchtoolsClient (API Client)"]:::library
        LOG["Logging Module"]:::library
        EH["ErrorHelper"]:::library
        NE["NoJSONError"]:::library
        URL["URL Helpers"]:::library
        
        LC --> CT
        LC --> LOG
        LC --> EH
        LC --> NE
        LC --> URL

        %% Indicate internal module usage
        CT --> LOG
        CT --> EH
        CT --> NE
        CT --> URL
    end

    %% Relationships between Client Applications and Core Library
    BrowserApp -->|"uses"| CT
    NodeApp -->|"uses"| CT

    %% External Communications
    CT -->|"APIcalls"| API["ChurchTools REST API"]:::external
    NodeApp -->|"integrates"| EXTD["External Dependencies (axios,axios-cookiejar-support,tough-cookie)"]:::external

    %% Development Infrastructure
    subgraph "Dev Infrastructure"
        TestSuite["Test Suite"]:::infra
        BuildConfig["Build & Config\n(tsconfig.json,webpack.config.js,.babelrc,.eslintrc.json,.prettierrc)"]:::infra
    end

    BuildConfig -->|"builds"| LC
    TestSuite -->|"validates"| LC

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef library fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

    %% Click Events
    click LC "https://github.com/churchtools/churchtools-js-client/tree/master/src/"
    click CT "https://github.com/churchtools/churchtools-js-client/blob/master/src/churchtoolsClient.ts"
    click LOG "https://github.com/churchtools/churchtools-js-client/blob/master/src/logging.ts"
    click EH "https://github.com/churchtools/churchtools-js-client/blob/master/src/errorHelper.ts"
    click NE "https://github.com/churchtools/churchtools-js-client/blob/master/src/NoJSONError.ts"
    click URL "https://github.com/churchtools/churchtools-js-client/blob/master/src/urlHelper.ts"
    click BrowserApp "https://github.com/churchtools/churchtools-js-client/tree/master/examples/Browser"
    click NodeApp "https://github.com/churchtools/churchtools-js-client/blob/master/examples/Node.js"
    click TestSuite "https://github.com/churchtools/churchtools-js-client/tree/master/test/"
    click BuildConfig "https://github.com/churchtools/churchtools-js-client/blob/master/tsconfig.json"
```
