Traffic Departure Notification Bot

A small Node.js + TypeScript bot that monitors a predefined route and sends a Telegram notification when traffic becomes good enough to leave.

Features

• Configurable origin/destination and travel-time threshold
• Polling interval and monitoring window
• Traffic provider abstraction
• Telegram notification provider
• Duplicate notification prevention
• Graceful shutdown and basic health endpoint
• Unit tests for decision logic

Architecture / Flowchart

flowchart TD
    Start([Poll timer fires]) --> WindowCheck{Within monitoring window?}
    WindowCheck -- No --> SkipCheck[Skip check] --> ScheduleNext[Schedule next check]
    WindowCheck -- Yes --> Overlap{Previous check still running?}
    Overlap -- Yes --> SkipCheck
    Overlap -- No --> FetchTraffic[Fetch travel time from Traffic Provider]

    FetchTraffic -- API error --> LogError[Log error] --> ScheduleNext
    FetchTraffic -- Success --> Compare{travelTime <= maxTravelTime?}

    Compare -- No --> NotReady[State = NOT_READY]
    Compare -- Yes --> Ready[State = READY]

    NotReady --> LogState[Log condition] --> ScheduleNext
    Ready --> LogState2[Log condition] --> Transition{Previous state was NOT_READY?}

    Transition -- No --> ScheduleNext
    Transition -- Yes --> Notify[Send departure notification via Notification Provider]
    Notify -- failure --> LogNotifyError[Log notification error] --> ScheduleNext
    Notify -- success --> ScheduleNext

    ScheduleNext --> Start

Loading

Setup

1. Install dependencies:

   npm install

2. Copy the example environment file and adjust it:

   cp .env.example .env

3. Build the project:

   npm run build

4. Start the bot:

   npm start

Docker

docker compose up -d

Testing

npm test