# merjoon/merjoon-core architecture

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

- Interactive diagram: https://gitdiagram.com/merjoon/merjoon-core
- Repository: https://github.com/merjoon/merjoon-core

## Overview

##### Project Type and Purpose
- This is a backend/core library (no UI) focused on “integrations.”

##### Main Architectural Components
a. CLI/Entry Point (“verify” module)
b. Service‐Factory & Dispatcher
c. Individual Integration Modules (ClickUp, GitLab, Jira, …)
– Subcomponents per integration: API client, Service logic, Transformer, Consts, Types
d. Common Library Code
– HttpClient (handles HTTP requests/retries)
– MerjoonTransformer (applies shared transformations)
– Shared consts/types
f. Output Sink
– “.transformed” directory

##### Component Relationships and Data Flow
1. Developer runs `npm run verify:<integration>` → invokes `ts‐node src/verify/index.ts`.
2. Entry Point loads environment, then calls ServiceFactory with the chosen IntegrationId.
3. ServiceFactory returns the specific integration‐service instance implementing a common interface.
4. Integration‐Service uses Api module + Common HttpClient to call the external API.
5. Raw API response flows through the integration’s Transformer, producing Merjoon‐standard JSON.
6. The transformed data is written to the `.transformed/<integration>` folder.

##### Architectural Patterns and Principles
- Strategy/Factory Pattern: ServiceFactory selects and returns the correct integration module.
- Layered Architecture per Integration: API → Service → Transformer.
- Shared Infrastructure: common HTTP client and transformation utilities reduce code duplication.
- Plugin‐style extensibility: adding a new integration involves dropping in a new module under `src/verify/services` and wiring it into the factory.

##### Technologies and Frameworks to Annotate
- Node.js + TypeScript
- ts‐node (for CLI execution)
- Jest (for tests, e2e suites for each integration)
- ESLint / Husky (static‐analysis, pre‐commit hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Verify["verify/index.ts"]:::core
    Verify -->|loads env & calls| ServiceFactory

    %% Service Factory
    ServiceFactory["ServiceFactory"]:::core
    ServiceFactory -->|returns| GitLabService
    ServiceFactory -->|returns| OtherServices

    %% Integrations Group
    subgraph "Integrations" 
        direction TB
        GitLabService["GitLabService"]:::integration
        OtherServices["N-1 more integrations"]:::integration
        %% GitLab subcomponents
        subgraph "GitLab Module" 
            direction TB
            GitLabAPI["api.ts"]:::integration
            GitLabServiceLogic["gitlab-service.ts"]:::integration
            GitLabTransformer["transformer.ts"]:::integration
            GitLabConsts["consts.ts"]:::integration
            GitLabTypes["types.ts"]:::integration
        end
        GitLabService -->|uses| GitLabAPI
        GitLabService -->|uses| GitLabServiceLogic
        GitLabService -->|uses| GitLabTransformer
        GitLabService -->|reads| GitLabConsts
        GitLabService -->|reads| GitLabTypes
    end

    %% Common Utilities
    subgraph "Common Library" 
        direction TB
        HttpClient["HttpClient.ts"]:::core
        MerjoonTransformer["MerjoonTransformer.ts"]:::core
        CommonConsts["consts.ts"]:::core
        CommonTypes["types.ts"]:::core
    end

    %% Data Flow
    GitLabAPI -->|calls| ExternalGitLabAPI
    GitLabServiceLogic -->|requests via| HttpClient
    GitLabTransformer -->|calls| MerjoonTransformer
    GitLabTransformer -->|writes| OutputSink
    OtherServices -->|similar flow| OutputSink

    %% External Services
    ExternalGitLabAPI["GitLab API"]:::external
    ExternalClickUpAPI["ClickUp API"]:::external
    ExternalJiraAPI["Jira API"]:::external

    %% Output Sink
    OutputSink[".transformed/<integration>"]:::storage

    %% Connections
    HttpClient -->|HTTP calls to| ExternalGitLabAPI
    HttpClient -->|HTTP calls to| ExternalClickUpAPI
    HttpClient -->|HTTP calls to| ExternalJiraAPI

    %% Click Events
    click Verify "https://github.com/merjoon/merjoon-core/blob/main/src/verify/index.ts"
    click ServiceFactory "https://github.com/merjoon/merjoon-core/blob/main/src/verify/service-factory.ts"
    click OtherServices "https://github.com/merjoon/merjoon-core/blob/main/src/verify/services/*.ts"
    click HttpClient "https://github.com/merjoon/merjoon-core/blob/main/src/common/HttpClient.ts"
    click MerjoonTransformer "https://github.com/merjoon/merjoon-core/blob/main/src/common/MerjoonTransformer.ts"
    click CommonConsts "https://github.com/merjoon/merjoon-core/blob/main/src/common/consts.ts"
    click CommonTypes "https://github.com/merjoon/merjoon-core/blob/main/src/common/types.ts"
    click GitLabAPI "https://github.com/merjoon/merjoon-core/blob/main/src/gitlab/api.ts"
    click GitLabServiceLogic "https://github.com/merjoon/merjoon-core/blob/main/src/gitlab/gitlab-service.ts"
    click GitLabTransformer "https://github.com/merjoon/merjoon-core/blob/main/src/gitlab/transformer.ts"
    click GitLabConsts "https://github.com/merjoon/merjoon-core/blob/main/src/gitlab/consts.ts"
    click GitLabTypes "https://github.com/merjoon/merjoon-core/blob/main/src/gitlab/types.ts"

    %% Styles
    classDef core fill:#d0e6ff,stroke:#3b83f7,color:#000;
    classDef integration fill:#d4f5d4,stroke:#2d9e2d,color:#000;
    classDef external fill:#ffe0b2,stroke:#ff9800,color:#000,stroke-dasharray: 4 2;
    classDef storage fill:#e0e0e0,stroke:#9e9e9e,color:#000;
```
