# ayarse/ibay_apartment_hunter architecture

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

- Interactive diagram: https://gitdiagram.com/ayarse/ibay_apartment_hunter
- Repository: https://github.com/ayarse/ibay_apartment_hunter

## Overview

##### Project type and purpose
- This is a backend “bot as a service” application written in TypeScript.
- Its sole purpose is to periodically scrape apartment listings from iBay.com.mv, persist them to a PostgreSQL database, and push notifications via Telegram to subscribed users.
- It’s deployed via Docker Compose and uses Drizzle ORM, Puppeteer, and grammY (Telegram bot framework).

##### File structure
- Entry point: src/app.ts
- “clients/”: third-party integrations
- db.ts (Drizzle-based PostgreSQL client)
- telegram.ts (grammY client wrapper)
- “scrapers/”: modules that fetch raw data from iBay (uses Puppeteer)
- “listeners/”: event handlers that respond to “new-ibay-item” events
- “services/”: business logic layer
- config-service.ts (read runtime config)
- user-service.ts (manage subscriber data)
- notif-service.ts (prepare/send Telegram notifications)
- “util/”: shared utilities (event-bus, logger, helpers)
- scripts/migrate.ts + drizzle.config.ts + db/migrations: database schema and migration tooling
- Deployment/config: Dockerfile, docker-compose.yml, ecosystem.config.cjs (PM2), .env examples

##### README for additional insights
- The timer interval is configurable (TIMER_INTERVAL).
- DEBUG mode reroutes all notifications to DEBUG_USER.
- External dependencies: PostgreSQL, Telegram API, Sentry for error logging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Scheduler Entry
    Scheduler["Scheduler / Timer\n(src/app.ts)"]:::client
    click Scheduler "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/app.ts"

    %% External Service iBay
    subgraph External_Services
        direction LR
        iBay["iBay.com.mv"]:::external
        TelegramAPI["Telegram API"]:::external
        Sentry["Sentry"]:::external
    end

    %% Scraper Layer
    subgraph "Scrapers Module" 
        direction TB
        ScrapersIndex["Scrapers Index\n(src/scrapers/index.ts)"]:::client
        click ScrapersIndex "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/scrapers/index.ts"
        ScraperIbay["iBay Scraper\n(src/scrapers/ibay.ts)"]:::client
        click ScraperIbay "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/scrapers/ibay.ts"
    end

    %% Event Bus
    EventBus["Event Bus\n(src/util/event-bus.ts)"]:::logic
    click EventBus "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/util/event-bus.ts"

    %% Listeners Layer
    subgraph "Listeners Module"
        direction TB
        ListenersIndex["Listeners Index\n(src/listeners/index.ts)"]:::logic
        click ListenersIndex "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/listeners/index.ts"
        NewItemListener["new-ibay-item Listener\n(src/listeners/new-ibay-item.ts)"]:::logic
        click NewItemListener "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/listeners/new-ibay-item.ts"
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        ConfigService["Config Service\n(src/services/config-service.ts)"]:::logic
        click ConfigService "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/services/config-service.ts"
        UserService["User Service\n(src/services/user-service.ts)"]:::logic
        click UserService "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/services/user-service.ts"
        NotifService["Notification Service\n(src/services/notif-service.ts)"]:::logic
        click NotifService "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/services/notif-service.ts"
    end

    %% Clients Layer
    subgraph "Clients"
        direction TB
        ClientsIndex["Clients Index\n(src/clients/index.ts)"]:::client
        click ClientsIndex "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/clients/index.ts"
        DBClient["Database Client\n(src/clients/db.ts)"]:::data
        click DBClient "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/clients/db.ts"
        TelegramClient["Telegram Client\n(src/clients/telegram.ts)"]:::client
        click TelegramClient "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/clients/telegram.ts"
    end

    %% Database Schema & Migrations
    subgraph "Database Setup"
        direction TB
        Schema["Schema Definition\n(src/db/schema.ts)"]:::data
        click Schema "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/db/schema.ts"
        Migrations["Migrations\n(src/db/migrations/*)"]:::data
        click Migrations "https://github.com/ayarse/ibay_apartment_hunter/tree/master/src/db/migrations/*"
        DrizzleConfig["Drizzle Config\n(drizzle.config.ts)"]:::data
        click DrizzleConfig "https://github.com/ayarse/ibay_apartment_hunter/blob/master/drizzle.config.ts"
        MigrateScript["Migration Script\n(scripts/migrate.ts)"]:::data
        click MigrateScript "https://github.com/ayarse/ibay_apartment_hunter/blob/master/scripts/migrate.ts"
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        direction TB
        UtilsIndex["Utilities Index\n(src/util/index.ts)"]:::logic
        click UtilsIndex "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/util/index.ts"
        Helpers["Helpers\n(src/util/helpers.ts)"]:::logic
        click Helpers "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/util/helpers.ts"
        Logger["Logger\n(src/util/logger.ts)"]:::logic
        click Logger "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/util/logger.ts"
        GlobalConfig["Global Config\n(src/config.ts)"]:::logic
        click GlobalConfig "https://github.com/ayarse/ibay_apartment_hunter/blob/master/src/config.ts"
    end

    %% Flow Connections
    Scheduler -->|triggers| ScrapersIndex
    ScrapersIndex -->|invokes| ScraperIbay
    ScraperIbay -->|fetches data from| iBay
    ScraperIbay -->|"emit new-ibay-item"| EventBus
    EventBus -->|subscribes| ListenersIndex
    ListenersIndex -->|handles| NewItemListener
    NewItemListener -->|reads| UserService
    NewItemListener -->|writes| DBClient
    NewItemListener -->|formats| NotifService
    NotifService -->|calls| TelegramClient
    TelegramClient -->|sends to| TelegramAPI
    ConfigService -->|provides config| Scheduler
    ConfigService -->|provides config| ScrapersIndex
    ConfigService -->|provides config| NewItemListener
    UserService -->|queries| DBClient
    DBClient -->|connects to| Schema
    Schema -->|managed by| DrizzleConfig
    Migrations -->|run by| MigrateScript
    UtilsIndex -->|aggregates| EventBus
    UtilsIndex -->|aggregates| Logger
    Logger -->|logs to| Sentry

    %% Styling
    classDef data fill:#cfe2f3,stroke:#6c8ebf,color:#0b3852;
    classDef logic fill:#d9ead3,stroke:#6aa84f,color:#274e13;
    classDef client fill:#fce5cd,stroke:#e69138,color:#974f0c;
    classDef external fill:#f4cccc,stroke:#cc0000,color:#660000;
```
