# kaithwasaditya/job_alert_telegram architecture

> Architecture diagram of the GitHub repository kaithwasaditya/job_alert_telegram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaithwasaditya/job_alert_telegram
- Repository: https://github.com/kaithwasaditya/job_alert_telegram

## Overview

Alert Bot lets job seekers track company career pages, filter roles, and receive scheduled Telegram alerts. Users sign in, configure subscriptions and preferences in the dashboard, and connect Telegram; scheduled polling normalizes job postings, while dispatch applies filters and records deliveries. Custom company detection and manual polling extend the same workflow. The graph reflects the shown route and service calls; unsampled dashboard actions and webhook behavior are represented only where the index or README supports them.

Main entry points: [`src/lib/db.ts`](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/db.ts) (Application database), [`src/app/dashboard/actions.ts`](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/actions.ts) (Dashboard actions), [`src/app/api/cron/dispatch/route.ts`](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/cron/dispatch/route.ts) (Alert dispatcher), [`src/app/dashboard/page.tsx`](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user["User experience"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_sign_in["Sign in / sign up<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard controls"]
  node_actions["Dashboard actions<br/>[actions.ts]"]
end

subgraph group_ingest["Job discovery"]
  node_company_detection["Company detection<br/>[ats.ts]"]
  node_poll_route["Scheduled poll route<br/>[route.ts]"]
  node_poller["Posting poller<br/>[poller.ts]"]
  node_ats_sources["ATS adapters<br/>[ats.ts]"]
end

subgraph group_alerts["Alert delivery"]
  node_dispatch_route["Alert dispatcher<br/>[route.ts]"]
  node_matching["Filter and schedule<br/>[matching.ts]"]
  node_telegram_service["Telegram service<br/>[telegram.ts]"]
  node_webhook["Telegram webhook<br/>[route.ts]"]
end

subgraph group_data["Identity and data"]
  node_clerk_user["Synced user<br/>[clerk-user.ts]"]
  node_postgres[("Application database<br/>[db.ts]")]
end

node_jobseeker(("Job seeker"))
node_ats_platforms["ATS platforms<br/>external system"]
node_cron_actor(("Cron scheduler"))
node_telegram["Telegram"]
node_clerk["Clerk identity"]

node_jobseeker -->|"opens"| node_landing
node_jobseeker -.->|"signs in"| node_sign_in
node_jobseeker -.->|"manages alerts"| node_dashboard
node_dashboard -->|"renders"| node_dashboard_ui
node_dashboard_ui -->|"invokes"| node_actions
node_dashboard -->|"requires user"| node_clerk_user
node_dashboard -->|"loads dashboard data"| node_postgres
node_actions -->|"requires user"| node_clerk_user
node_actions -->|"updates preferences"| node_postgres
node_actions -->|"detects company"| node_company_detection
node_actions -->|"polls company"| node_poller
node_clerk_user -->|"reads identity"| node_clerk
node_clerk_user -->|"syncs user"| node_postgres
node_cron_actor -->|"triggers"| node_poll_route
node_poll_route -->|"selects companies"| node_postgres
node_poll_route -->|"polls company"| node_poller
node_poller -->|"fetches postings"| node_ats_sources
node_ats_sources -->|"normalized postings"| node_postgres
node_ats_sources -.->|"fetches job listings"| node_ats_platforms
node_cron_actor -->|"triggers"| node_dispatch_route
node_dispatch_route -->|"loads subscriptions and jobs"| node_postgres
node_dispatch_route -->|"checks schedule and filters"| node_matching
node_dispatch_route -->|"sends alerts"| node_telegram_service
node_dispatch_route -->|"records delivery"| node_postgres
node_telegram_service -->|"calls Bot API"| node_telegram
node_jobseeker -.->|"connects bot"| node_telegram
node_telegram -->|"posts updates"| node_webhook
node_webhook -->|"stores connection data"| node_postgres

click node_landing "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/page.tsx"
click node_sign_in "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/sign-in/%5B%5B...sign-in%5D%5D/page.tsx"
click node_dashboard "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/page.tsx"
click node_dashboard_ui "https://github.com/kaithwasaditya/job_alert_telegram/tree/main/src/app/dashboard"
click node_actions "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/actions.ts"
click node_company_detection "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/ats.ts"
click node_poll_route "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/cron/poll/route.ts"
click node_poller "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/poller.ts"
click node_ats_sources "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/ats.ts"
click node_dispatch_route "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/cron/dispatch/route.ts"
click node_matching "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/matching.ts"
click node_telegram_service "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/telegram.ts"
click node_webhook "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/telegram/webhook/route.ts"
click node_clerk_user "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/clerk-user.ts"
click node_postgres "https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/db.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_sign_in,node_dashboard,node_dashboard_ui,node_actions toneBlue
class node_company_detection,node_poll_route,node_poller,node_ats_sources toneAmber
class node_dispatch_route,node_matching,node_telegram_service,node_webhook toneMint
class node_clerk_user,node_postgres,node_cron_actor toneRose
class node_jobseeker,node_ats_platforms,node_telegram,node_clerk toneIndigo
```

## Components

### User experience

- [Landing page](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Sign in / sign up](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/sign-in/%5B%5B...sign-in%5D%5D/page.tsx): `src/app/sign-in/[[...sign-in]]/page.tsx`
- [Dashboard](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Dashboard controls](https://github.com/kaithwasaditya/job_alert_telegram/tree/main/src/app/dashboard): `src/app/dashboard`
- [Dashboard actions](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/dashboard/actions.ts): `src/app/dashboard/actions.ts`

### Job discovery

- [Company detection](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/ats.ts): `src/lib/ats.ts`
- [Scheduled poll route](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/cron/poll/route.ts): `src/app/api/cron/poll/route.ts`
- [Posting poller](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/poller.ts): `src/lib/poller.ts`
- [ATS adapters](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/ats.ts): `src/lib/ats.ts`

### Alert delivery

- [Alert dispatcher](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/cron/dispatch/route.ts): `src/app/api/cron/dispatch/route.ts`
- [Filter and schedule](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/matching.ts): `src/lib/matching.ts`
- [Telegram service](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/telegram.ts): `src/lib/telegram.ts`
- [Telegram webhook](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/app/api/telegram/webhook/route.ts): `src/app/api/telegram/webhook/route.ts`

### Identity and data

- [Synced user](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/clerk-user.ts): `src/lib/clerk-user.ts`
- [Application database](https://github.com/kaithwasaditya/job_alert_telegram/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Other components

- **Job seeker**
- **ATS platforms**: external system
- **Cron scheduler**
- **Telegram**
- **Clerk identity**

## Connections

- Job seeker → Landing page: opens (evidence: `src/app/page.tsx`)
- Job seeker → Sign in / sign up: signs in (evidence: `README.md`)
- Job seeker → Dashboard: manages alerts (evidence: `README.md`)
- Dashboard → Dashboard controls: renders (evidence: `src/app/dashboard/page.tsx`)
- Dashboard controls → Dashboard actions: invokes (evidence: `src/app/dashboard/add-company-form.tsx`)
- Dashboard → Synced user: requires user (evidence: `src/app/dashboard/page.tsx`)
- Dashboard → Application database: loads dashboard data (evidence: `src/app/dashboard/page.tsx`)
- Dashboard actions → Synced user: requires user (evidence: `src/app/dashboard/actions.ts`)
- Dashboard actions → Application database: updates preferences (evidence: `src/app/dashboard/actions.ts`)
- Dashboard actions → Company detection: detects company (evidence: `src/app/dashboard/actions.ts`)
- Dashboard actions → Posting poller: polls company (evidence: `src/app/dashboard/actions.ts`)
- Synced user → Clerk identity: reads identity (evidence: `src/lib/clerk-user.ts`)
- Synced user → Application database: syncs user (evidence: `src/lib/clerk-user.ts`)
- Cron scheduler → Scheduled poll route: triggers (evidence: `README.md`)
- Scheduled poll route → Application database: selects companies (evidence: `src/app/api/cron/poll/route.ts`)
- Scheduled poll route → Posting poller: polls company (evidence: `src/app/api/cron/poll/route.ts`)
- Posting poller → ATS adapters: fetches postings (evidence: `src/lib/poller.ts`)
- ATS adapters → Application database: normalized postings (evidence: `src/lib/poller.ts`)
- ATS adapters → ATS platforms: fetches job listings
- Cron scheduler → Alert dispatcher: triggers (evidence: `README.md`)
- Alert dispatcher → Application database: loads subscriptions and jobs (evidence: `src/app/api/cron/dispatch/route.ts`)
- Alert dispatcher → Filter and schedule: checks schedule and filters (evidence: `src/app/api/cron/dispatch/route.ts`)
- Alert dispatcher → Telegram service: sends alerts (evidence: `src/app/api/cron/dispatch/route.ts`)
- Alert dispatcher → Application database: records delivery (evidence: `src/app/api/cron/dispatch/route.ts`)
- Telegram service → Telegram: calls Bot API (evidence: `src/lib/telegram.ts`)
- Job seeker → Telegram: connects bot (evidence: `README.md`)
- Telegram → Telegram webhook: posts updates (evidence: `README.md`)
- Telegram webhook → Application database: stores connection data (evidence: `src/app/api/telegram/webhook/route.ts`)