# dan3612812/btsnotify architecture

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

- Interactive diagram: https://gitdiagram.com/dan3612812/btsnotify
- Repository: https://github.com/dan3612812/btsnotify

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript backend tool (a “BOT”) that periodically crawls Apple’s “back-to-school” (BTS) web pages, detects when a BTS campaign is live for different regions, and pushes notifications via a Telegram bot.

##### File structure
- Top-level:
- example.env, tsconfig.json, package.json (configuration & dependencies)
- reference/… (static screenshots for testing/documentation)
- src/ – main codebase
- src/crawler: HTML-scraping logic
- src/service: orchestration & BTS-detection rules
- src/notify: Telegram‐bot client & message dispatch
- src/lib: shared utilities (HTTP, HTML parsing, retry, logging)
- src/env: configuration loader (API tokens, URLs)
- src/index.ts: entry point that wires everything together

##### README for additional insights
- The README describes four heuristics for detecting BTS availability (URL patterns, sitemap inspection, redirect behavior, page‐rel links).
- It references a Telegram BOT and channel to send updates.

a. Main components
1. Scheduler/Executor (src/index.ts)
2. Crawler Module (src/crawler/*)
3. Business‐Logic Service (src/service/*)
4. Notification Module (src/notify/*)
5. Configuration Loader (src/env/*)
6. Utility Library (src/lib/*)
7. External Systems:
- Apple Web (various URLs, sitemap)
- Telegram Bot API
b. Relationships & interactions
- The Scheduler triggers the Crawler at configured intervals.
- The Crawler issues HTTP requests (via lib/http) to Apple URLs, retrieves HTML.
- Retrieved HTML is handed to the Service, which applies detection rules.
- If a BTS campaign is found, Service invokes the Notify module.
- Notify constructs and sends messages to Telegram via Telegram API.
- Env module provides API keys, region lists, and schedule settings to all modules.
c. Architectural patterns & design principles
- Modular layering: crawler, business logic, notification are decoupled.
- Single responsibility per module.
- Configuration‐as‐code (env loader centralizes secrets and URLs).
- Reusable utilities in lib to avoid duplication (HTTP, parsing, logging).
d. Key technologies & libraries
- Node.js + TypeScript
- Axios or node-fetch (HTTP requests)
- Cheerio (HTML parsing)
- dotenv (env configuration)
- Telegram Bot API client

##### Essential elements
- Module names and boundaries
- Config flows (Env → all modules)
- Data flows and triggers (interval or cron)
- External endpoints (Apple URLs, Telegram API)
- Error/Retry path (optionally annotate lib’s retry logic)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scheduler
    Scheduler["Scheduler/Executor"]:::core
    click Scheduler "https://github.com/dan3612812/btsnotify/blob/main/src/index.ts"

    %% Crawler Module
    subgraph "Crawler Module"
        CrawlerIndex["index.ts"]:::core
        CrawlerCore["core.ts"]:::core
    end
    click CrawlerIndex "https://github.com/dan3612812/btsnotify/blob/main/src/crawler/index.ts"
    click CrawlerCore "https://github.com/dan3612812/btsnotify/blob/main/src/crawler/core.ts"

    %% Business-Logic Service
    ServiceIndex["Business-Logic Service (index.ts)"]:::core
    click ServiceIndex "https://github.com/dan3612812/btsnotify/blob/main/src/service/index.ts"

    %% Notification Module
    subgraph "Notification Module"
        NotifyIndex["index.ts"]:::core
        NotifyListen["listen.ts"]:::core
    end
    click NotifyIndex "https://github.com/dan3612812/btsnotify/blob/main/src/notify/index.ts"
    click NotifyListen "https://github.com/dan3612812/btsnotify/blob/main/src/notify/listen.ts"

    %% Shared Modules
    subgraph "Shared Modules"
        EnvIndex["Configuration Loader (index.ts)"]:::shared
        LibIndex["Utility Library (index.ts)"]:::shared
        LibCore["core.ts"]:::shared
    end
    click EnvIndex "https://github.com/dan3612812/btsnotify/blob/main/src/env/index.ts"
    click LibIndex "https://github.com/dan3612812/btsnotify/blob/main/src/lib/index.ts"
    click LibCore "https://github.com/dan3612812/btsnotify/blob/main/src/lib/core.ts"

    %% External Services
    Apple["Apple Web"]:::external
    Telegram["Telegram Bot API"]:::external

    %% Data Flows
    Scheduler -->|"cron interval"| CrawlerIndex
    CrawlerIndex -->|"invokes"| CrawlerCore
    CrawlerCore -->|"HTML response"| ServiceIndex
    ServiceIndex -->|"BTS event"| NotifyIndex
    NotifyIndex -->|"calls listen"| NotifyListen
    NotifyListen -->|"HTTPS JSON"| Telegram
    CrawlerCore -->|"HTTP GET"| Apple

    %% Config & Utils
    EnvIndex --> Scheduler
    EnvIndex --> CrawlerIndex
    EnvIndex --> ServiceIndex
    EnvIndex --> NotifyIndex

    LibIndex --> CrawlerCore
    LibIndex --> ServiceIndex
    LibIndex --> NotifyIndex

    %% Styles
    classDef core fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef shared fill:#D5F5E3,stroke:#1D8348,color:#145A32;
    classDef external fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
```
