# atul-k-m/opgrab_bot architecture

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

- Interactive diagram: https://gitdiagram.com/atul-k-m/opgrab_bot
- Repository: https://github.com/atul-k-m/opgrab_bot

## Overview

OpportunityIQ collects student and developer opportunities, stores them in Supabase, ranks them against user profiles, and presents them in a web dashboard or Telegram alerts. The main automated path is scheduled scraping followed by persistence and personalized delivery; users can also request an on-demand digest. The README additionally describes Telegram onboarding and profile setup. The bot entry point is absent from the supplied tree, so its wiring is not inferred; dashboard and backend links reflect the sampled source, while AI ranking is an optional integration.

Main entry points: [`src/delivery.js`](https://github.com/atul-k-m/opgrab_bot/blob/main/src/delivery.js) (Digest delivery), [`src/scraper.js`](https://github.com/atul-k-m/opgrab_bot/blob/main/src/scraper.js) (Source scrapers), [`src/supabase.js`](https://github.com/atul-k-m/opgrab_bot/blob/main/src/supabase.js) (Supabase client), [`src/automation.js`](https://github.com/atul-k-m/opgrab_bot/blob/main/src/automation.js) (Scheduled automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Opportunity ingestion"]
  node_scraper["Source scrapers<br/>[scraper.js]"]
  node_automation["Scheduled automation<br/>[automation.js]"]
end

subgraph group_personalization["Matching and delivery"]
  node_matcher["Relevance ranking<br/>[matcher.js]"]
  node_delivery["Digest delivery<br/>[delivery.js]"]
end

subgraph group_web["Web dashboard"]
  node_webapp["Dashboard and auth<br/>[main.js]"]
end

subgraph group_data["Persistence"]
  node_supabase_client["Supabase client<br/>[supabase.js]"]
  node_supabase["Supabase service"]
  node_database[("Opportunity and user data<br/>[schema.sql]")]
end

node_user(("Student or developer"))
node_sources(("Opportunity sources"))
node_telegram(("Telegram Bot API"))
node_groq(("Groq ranking API"))

node_user -->|"uses dashboard"| node_webapp
node_user -->|"uses bot"| node_telegram
node_automation -->|"runs scrape"| node_scraper
node_automation -->|"triggers alerts"| node_delivery
node_scraper -->|"fetches listings"| node_sources
node_scraper -->|"upserts opportunities"| node_supabase_client
node_matcher -.->|"requests AI scores"| node_groq
node_delivery -->|"ranks matches"| node_matcher
node_delivery -->|"reads and records"| node_supabase_client
node_delivery -->|"sends digests"| node_telegram
node_webapp -->|"auth and data queries"| node_supabase
node_supabase_client -->|"connects"| node_supabase
node_supabase -->|"reads and writes"| node_database

click node_scraper "https://github.com/atul-k-m/opgrab_bot/blob/main/src/scraper.js"
click node_automation "https://github.com/atul-k-m/opgrab_bot/blob/main/src/automation.js"
click node_matcher "https://github.com/atul-k-m/opgrab_bot/blob/main/src/matcher.js"
click node_delivery "https://github.com/atul-k-m/opgrab_bot/blob/main/src/delivery.js"
click node_webapp "https://github.com/atul-k-m/opgrab_bot/blob/main/web/src/main.js"
click node_supabase_client "https://github.com/atul-k-m/opgrab_bot/blob/main/src/supabase.js"
click node_database "https://github.com/atul-k-m/opgrab_bot/blob/main/schema.sql"

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_scraper,node_automation toneBlue
class node_matcher,node_delivery toneAmber
class node_webapp,node_telegram,node_groq toneMint
class node_supabase_client,node_supabase,node_database toneRose
class node_user,node_sources toneIndigo
```

## Components

### Opportunity ingestion

- [Source scrapers](https://github.com/atul-k-m/opgrab_bot/blob/main/src/scraper.js): `src/scraper.js`
- [Scheduled automation](https://github.com/atul-k-m/opgrab_bot/blob/main/src/automation.js): `src/automation.js`

### Matching and delivery

- [Relevance ranking](https://github.com/atul-k-m/opgrab_bot/blob/main/src/matcher.js): `src/matcher.js`
- [Digest delivery](https://github.com/atul-k-m/opgrab_bot/blob/main/src/delivery.js): `src/delivery.js`

### Web dashboard

- [Dashboard and auth](https://github.com/atul-k-m/opgrab_bot/blob/main/web/src/main.js): `web/src/main.js`

### Persistence

- [Supabase client](https://github.com/atul-k-m/opgrab_bot/blob/main/src/supabase.js): `src/supabase.js`
- **Supabase service**
- [Opportunity and user data](https://github.com/atul-k-m/opgrab_bot/blob/main/schema.sql): `schema.sql`

### Other components

- **Student or developer**
- **Opportunity sources**
- **Telegram Bot API**
- **Groq ranking API**

## Connections

- Student or developer → Dashboard and auth: uses dashboard
- Student or developer → Telegram Bot API: uses bot
- Scheduled automation → Source scrapers: runs scrape
- Scheduled automation → Digest delivery: triggers alerts
- Source scrapers → Opportunity sources: fetches listings
- Source scrapers → Supabase client: upserts opportunities
- Relevance ranking → Groq ranking API: requests AI scores
- Digest delivery → Relevance ranking: ranks matches
- Digest delivery → Supabase client: reads and records
- Digest delivery → Telegram Bot API: sends digests
- Dashboard and auth → Supabase service: auth and data queries
- Supabase client → Supabase service: connects
- Supabase service → Opportunity and user data: reads and writes