# koff75/node-toogoodtogo-watcher architecture

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

- Interactive diagram: https://gitdiagram.com/koff75/node-toogoodtogo-watcher
- Repository: https://github.com/koff75/node-toogoodtogo-watcher

## Overview

##### Project Type and Purpose
- This is an open-source Node.js command-line application (“toogoodtogo-watcher”) for monitoring TooGoodToGo business stock changes.
- Purpose: periodically poll the TooGoodToGo API for favorite businesses, then notify the user via desktop notifications, console output, or Telegram.

##### File Structure Analysis
- Root files:
- index.js – CLI entry point, command dispatcher
- config.defaults.json – default config template
- Dockerfile / .dockerignore – containerization
- package.json / package-lock.json – dependencies & scripts
- lib/ directory (core modules):
- lib/config.js – reads/writes user config
- lib/api.js – wraps TooGoodToGo HTTP API calls
- lib/poller.js – schedules/fires periodic polling jobs
- lib/notifier.js – routes notification events to console or desktop
- lib/telegram-bot.js – Telegram integration and conversational handlers
- lib/emaillogin.js – handles email-based login flow
- .vscode, .eslintrc.js, .prettierrc – developer/editor configs

##### README Insights
- Describes CLI commands (login, config, watch, etc.)
- Highlights features: desktop notifications, console output, Telegram bot commands
- Details Docker usage with a host directory mounted for persistent config

##### Components
a. Main Components
1. CLI Layer
- index.js: parses commands via yargs or similar
2. Configuration Service
- lib/config.js: reads config from ~/.config/toogoodtogo-watcher-nodejs/config.json
3. Authentication Service
- lib/emaillogin.js / lib/api.js: login & token management
4. Polling Engine
- lib/poller.js: timers, scheduling logic
5. API Client
- lib/api.js: REST calls to TooGoodToGo endpoints
6. Notification Dispatcher
- lib/notifier.js: desktop & console notifications
- lib/telegram-bot.js: Telegram Bot API integration
7. External Systems
- TooGoodToGo backend (HTTPS API)
- Telegram Bot API
- OS desktop notification center
- File system (config volume in Docker)

b. Relationships & Data Flow
- User invokes CLI → index.js
- index.js loads Configuration Service → fetch credentials & user preferences
- For “watch” command:
- Authentication Service obtains/refreshes token
- Polling Engine periodically calls API Client
- API Client fetches business stock info → returns JSON
- Poller compares new vs. old state → emits change events
- Notification Dispatcher receives events → fans out to:
– Desktop notifier (OS API)
– Console logger
– Telegram-bot client (webhook/long-polling to Telegram API)
- Config changes (via “config” command) update config file on disk (mounted host volume in Docker)

c. Architectural Patterns & Principles
- Modular separation: each concern in its own module (SRP)
- Event-driven polling model: poller emits events to notifier
- Adapter pattern for different notification channels (console, desktop, Telegram)
- CLI command pattern for subcommands (login, watch, config)

d. Key Technologies & Libraries
- Node.js (runtime)
- yargs or similar CLI parser (implied in index.js)
- node-telegram-bot-api or direct HTTPS calls (lib/telegram-bot.js)
- Node FS module for config persistence
- Docker for container deployment

##### Essential Detail
- Lib modules as distinct components
- Persistent config in file system or Docker volume
- How the poll-and-notify loop interacts with both OS and network endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application"
        CLI["CLI Entry Point (index.js)"]:::internal
        Config["Config Service (lib/config.js)"]:::internal
        Auth["Authentication Service (lib/emaillogin.js)"]:::internal
        Poller["Polling Engine (lib/poller.js)"]:::internal
        API["API Client (lib/api.js)"]:::internal
        NotifierDC["Notifier: Desktop & Console (lib/notifier.js)"]:::internal
        NotifierTG["Notifier: Telegram Bot (lib/telegram-bot.js)"]:::internal
    end

    %% External Systems
    TGTAPI["TooGoodToGo API"]:::external
    TeleAPI["Telegram Bot API"]:::external
    OSNotif["OS Notification Center"]:::external

    %% Docker Host / Volume
    subgraph "Docker Host / Volume" style dashed
        FileSystem["Config File System (Volume)"]:::external
    end

    %% Project Files
    subgraph "Project Files"
        DefConfig["Default Config Template (config.defaults.json)"]:::file
        Dockerfile["Dockerfile"]:::file
        Dockerignore[".dockerignore"]:::file
        PackageJSON["package.json"]:::file
        PackageLock["package-lock.json"]:::file
    end

    %% Data Flow
    CLI -->|"load config"| Config
    Config -->|"read/write config"| FileSystem
    CLI -->|"invoke command"| Auth
    Auth -->|"provide token"| Poller
    Poller -->|"schedule polls"| API
    API -->|"fetch stock info"| TGTAPI
    TGTAPI -->|"return data"| API
    API -->|"return JSON"| Poller
    Poller -->|"emit change events"| NotifierDC
    Poller -->|"emit change events"| NotifierTG
    NotifierDC -->|"desktop alert"| OSNotif
    NotifierDC -->|"console output"| CLI
    NotifierTG -->|"send message"| TeleAPI

    %% Click Events
    click CLI "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/index.js"
    click Config "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/config.js"
    click Auth "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/emaillogin.js"
    click API "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/api.js"
    click Poller "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/poller.js"
    click NotifierDC "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/notifier.js"
    click NotifierTG "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/lib/telegram-bot.js"
    click DefConfig "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/config.defaults.json"
    click Dockerfile "https://github.com/koff75/node-toogoodtogo-watcher/tree/master/Dockerfile"
    click Dockerignore "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/.dockerignore"
    click PackageJSON "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/package.json"
    click PackageLock "https://github.com/koff75/node-toogoodtogo-watcher/blob/master/package-lock.json"

    %% Styles
    classDef internal fill:#b3e6b3,stroke:#2d7a2d,color:#000;
    classDef external fill:#b3d9ff,stroke:#004080,color:#000;
    classDef file fill:#ffe0b3,stroke:#b37700,color:#000;
```
