# turancannb02/revenuecat-telegram-notifier architecture

> Architecture diagram of the GitHub repository turancannb02/revenuecat-telegram-notifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turancannb02/revenuecat-telegram-notifier
- Repository: https://github.com/turancannb02/revenuecat-telegram-notifier

## Overview

##### Project type and purpose
- This is an event-driven “integration template” (open-source tool) built on top of the BuildShip serverless/workflow platform.
- It receives webhooks from RevenueCat, transforms key subscription events into formatted messages, and pushes them to a Telegram bot.
- It supports both BuildShip Cloud deployment and local development via Node.js/tsx.

##### File structure
Top-level:
- package.json, tsconfig.json – Node.js + TypeScript build and dependency config
- scripts/*.cjs – user-customizable formatting scripts (extension points)
src/buildship:
- execute-tool.ts / execute-tool-proxy.ts – the BuildShip “executor” entry points that invoke your workflow code
- files/, http.ts, storage.ts, utils.ts – BuildShip SDK modules for file handling, HTTP calls, environment/key storage, and helpers
src/revenueCatTelegramNotifier:
- index.ts – main workflow logic (event parsing, orchestration)
- nodes.ts – reusable workflow “nodes” (map RevenueCat payload to message fields)
- test-runner.ts – local dev entry point simulating a RevenueCat event via tsx
src/mcp.ts – (if present) cross-cutting utilities or multi-cloud proxy entry (minor role here)

##### README for additional insights
- Confirms the purpose: forward events like TRIAL_STARTED, RENEWAL, CANCELLATION.
- Shows environment setup (BuildShip Auth Keys or .env), local testing with tsx.
- Mentions that scripts/<script-id>.cjs can be edited to customize the Telegram message format.
- Workflow triggered by an HTTP POST from RevenueCat Webhooks.

- Clear, consistent labels for each component (e.g., “RevenueCat Webhook,” “BuildShip Executor,” “Event Parser Node,” “Telegram API”)
– Platform/SDK modules in another (BuildShip)
– Custom business logic in a third (revenueCatTelegramNotifier, scripts)
- Configuration sources: .env or BuildShip Auth Keys for the Telegram Bot Token

##### Final recommendations
- Critical interactions (HTTP POST, function invocation, script override).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        RC["RevenueCat Webhook"]:::external
        TG["Telegram Bot API"]:::external
    end

    %% BuildShip Platform
    subgraph "BuildShip Platform"
        direction TB
        HE["BuildShip HTTP Endpoint\n(executeWorkflow/<workflowId>)"]:::platform
        EP["Execute Proxy\n(execute-tool-proxy)"]:::platform
        ET["Execute Tool\n(execute-tool)"]:::platform
        CC["Multi-cloud Entry\n(mcp.ts)"]:::platform
        subgraph "SDK Modules"
            direction TB
            FS["Files Module\n(files/)"]:::platform
            HC["HTTP Client\n(http.ts)"]:::platform
            ST["Storage Module\n(storage.ts)"]:::platform
            UT["Utils Module\n(utils.ts)"]:::platform
        end
    end

    %% Custom Workflow
    subgraph "Custom Workflow"
        direction TB
        IDX["Main Orchestration\n(index.ts)"]:::custom
        NDS["Payload Mapping Nodes\n(nodes.ts)"]:::custom
    end

    %% User Scripts
    subgraph "User-configurable Scripts"
        direction TB
        SCR["Formatting Scripts\n(scripts/*.cjs)"]:::scripts
    end

    %% Local Development
    subgraph "Local Development"
        direction TB
        TR["Test Runner\n(test-runner.ts)"]:::local
    end

    %% Data Flows
    RC -->|POST event| HE
    HE --> EP
    HE --> ET
    HE --> CC
    EP --> IDX
    ET --> IDX
    CC --> IDX
    TR --> IDX
    IDX --> NDS
    NDS --> SCR
    IDX --> FS
    IDX --> ST
    IDX --> UT
    IDX --> HC
    HC -->|POST message| TG

    %% Click Events
    click EP "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/buildship/execute-tool-proxy.ts"
    click ET "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/buildship/execute-tool.ts"
    click FS "https://github.com/turancannb02/revenuecat-telegram-notifier/tree/main/src/buildship/files/"
    click HC "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/buildship/http.ts"
    click ST "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/buildship/storage.ts"
    click UT "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/buildship/utils.ts"
    click CC "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/mcp.ts"
    click IDX "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/revenueCatTelegramNotifier/index.ts"
    click NDS "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/revenueCatTelegramNotifier/nodes.ts"
    click TR "https://github.com/turancannb02/revenuecat-telegram-notifier/blob/main/src/revenueCatTelegramNotifier/test-runner.ts"
    click SCR "https://github.com/turancannb02/revenuecat-telegram-notifier/tree/main/scripts/"

    %% Styles
    classDef external fill:#ffe4b5,stroke:#d2691e,color:#000
    classDef platform fill:#b0e0e6,stroke:#4682b4,color:#000
    classDef custom fill:#98fb98,stroke:#2e8b57,color:#000
    classDef scripts fill:#ffebcd,stroke:#cd853f,color:#000
    classDef local fill:#e6e6fa,stroke:#9370db,color:#000
```
