# agntdev/neet-resource-hub architecture

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

- Interactive diagram: https://gitdiagram.com/agntdev/neet-resource-hub
- Repository: https://github.com/agntdev/neet-resource-hub

## Overview

NEET Resource Hub is a Telegram study-resource bot for repeaters. Its user workflow begins with an update delivered by Telegram, enters the bot runtime, and is dispatched to feature handlers for browsing subjects, finding resources, bookmarks, mock tests, or study plans; replies and menu interactions return through Telegram. The repository also includes reusable session, UI, reminder, and telemetry layers. The sampled sources document the Worker entry and toolkit internals; handler implementations and the Node bot builder were not sampled, so feature-specific wiring is intentionally limited.

Main entry points: [`src/bot.ts`](https://github.com/agntdev/neet-resource-hub/blob/main/src/bot.ts) (Bot builder), [`src/worker.ts`](https://github.com/agntdev/neet-resource-hub/blob/main/src/worker.ts) (Worker entry), [`src/toolkit/bot.ts`](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/bot.ts) (Bot toolkit), [`src/toolkit/session/durable.ts`](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/durable.ts) (Durable sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtimes"]
  node_node_entry["Node entry<br/>[index.ts]"]
  node_worker_entry["Worker entry<br/>[worker.ts]"]
  node_bot_builder["Bot builder<br/>[bot.ts]"]
end

subgraph group_features["Study features"]
  node_start["Start and menu<br/>[start.ts]"]
  node_help["Help<br/>[help.ts]"]
  node_subjects["Browse subjects<br/>[browse-subjects.ts]"]
  node_search["Resource search<br/>[search-start.ts]"]
  node_bookmarks["Bookmarks<br/>[bookmarks-list.ts]"]
  node_mocktest["Mock tests<br/>[mocktest-start.ts]"]
  node_study_plan["Study plans<br/>[plan-start.ts]"]
end

subgraph group_toolkit["Bot toolkit"]
  node_bot_toolkit["Bot toolkit<br/>[bot.ts]"]
  node_keyboard["Keyboard UI<br/>[keyboard.ts]"]
end

subgraph group_integrations["State and integrations"]
  node_memory_session["Memory sessions<br/>[memory.ts]"]
  node_redis_session["Redis sessions<br/>[redis.ts]"]
  node_durable_session["Durable sessions<br/>[durable.ts]"]
  node_chat_do[("Chat state and reminders<br/>[durable.ts]")]
  node_telemetry["Activity reporter<br/>[reporter.ts]"]
end

node_student(("Student"))
node_telegram{{"Telegram"}}
node_telemetry_service{{"Telemetry service"}}

node_student -->|"sends update"| node_telegram
node_telegram -->|"webhook POST"| node_worker_entry
node_node_entry -->|"builds bot"| node_bot_builder
node_worker_entry -->|"builds bot"| node_bot_builder
node_worker_entry -->|"provides storage"| node_durable_session
node_bot_builder -->|"uses toolkit"| node_bot_toolkit
node_bot_builder -->|"registers handlers"| node_start
node_bot_builder -->|"registers handlers"| node_help
node_bot_builder -->|"registers handlers"| node_subjects
node_bot_builder -->|"registers handlers"| node_search
node_bot_builder -->|"registers handlers"| node_bookmarks
node_bot_builder -->|"registers handlers"| node_mocktest
node_bot_builder -->|"registers handlers"| node_study_plan
node_start -.->|"builds menus"| node_keyboard
node_bot_toolkit -->|"selects fallback"| node_memory_session
node_bot_toolkit -->|"selects by config"| node_redis_session
node_worker_entry -->|"selects storage"| node_durable_session
node_durable_session -->|"routes session and reminders"| node_chat_do
node_chat_do -->|"sends reminder"| node_telegram
node_bot_toolkit -->|"installs reporter"| node_telemetry
node_telemetry -.->|"posts activity"| node_telemetry_service
node_worker_entry -->|"passes webhook update"| node_telegram
node_node_entry -->|"starts polling"| node_telegram

click node_node_entry "https://github.com/agntdev/neet-resource-hub/blob/main/src/index.ts"
click node_worker_entry "https://github.com/agntdev/neet-resource-hub/blob/main/src/worker.ts"
click node_bot_builder "https://github.com/agntdev/neet-resource-hub/blob/main/src/bot.ts"
click node_start "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/start.ts"
click node_help "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/help.ts"
click node_subjects "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/browse-subjects.ts"
click node_search "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/search-start.ts"
click node_bookmarks "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/bookmarks-list.ts"
click node_mocktest "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/mocktest-start.ts"
click node_study_plan "https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/plan-start.ts"
click node_bot_toolkit "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/bot.ts"
click node_keyboard "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/ui/keyboard.ts"
click node_memory_session "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/memory.ts"
click node_redis_session "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/redis.ts"
click node_durable_session "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/durable.ts"
click node_chat_do "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/durable.ts"
click node_telemetry "https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/telemetry/reporter.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_node_entry,node_worker_entry,node_bot_builder toneBlue
class node_start,node_help,node_subjects,node_search,node_bookmarks,node_mocktest,node_study_plan toneAmber
class node_bot_toolkit,node_keyboard toneMint
class node_memory_session,node_redis_session,node_durable_session,node_chat_do,node_telemetry toneRose
class node_student,node_telegram,node_telemetry_service toneIndigo
```

## Components

### Bot runtimes

- [Node entry](https://github.com/agntdev/neet-resource-hub/blob/main/src/index.ts): `src/index.ts`
- [Worker entry](https://github.com/agntdev/neet-resource-hub/blob/main/src/worker.ts): `src/worker.ts`
- [Bot builder](https://github.com/agntdev/neet-resource-hub/blob/main/src/bot.ts): `src/bot.ts`

### Study features

- [Start and menu](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/start.ts): `src/handlers/start.ts`
- [Help](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/help.ts): `src/handlers/help.ts`
- [Browse subjects](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/browse-subjects.ts): `src/handlers/browse-subjects.ts`
- [Resource search](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/search-start.ts): `src/handlers/search-start.ts`
- [Bookmarks](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/bookmarks-list.ts): `src/handlers/bookmarks-list.ts`
- [Mock tests](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/mocktest-start.ts): `src/handlers/mocktest-start.ts`
- [Study plans](https://github.com/agntdev/neet-resource-hub/blob/main/src/handlers/plan-start.ts): `src/handlers/plan-start.ts`

### Bot toolkit

- [Bot toolkit](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/bot.ts): `src/toolkit/bot.ts`
- [Keyboard UI](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/ui/keyboard.ts): `src/toolkit/ui/keyboard.ts`

### State and integrations

- [Memory sessions](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/memory.ts): `src/toolkit/session/memory.ts`
- [Redis sessions](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/redis.ts): `src/toolkit/session/redis.ts`
- [Durable sessions](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/durable.ts): `src/toolkit/session/durable.ts`
- [Chat state and reminders](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/session/durable.ts): `src/toolkit/session/durable.ts`
- [Activity reporter](https://github.com/agntdev/neet-resource-hub/blob/main/src/toolkit/telemetry/reporter.ts): `src/toolkit/telemetry/reporter.ts`

### Other components

- **Student**
- **Telegram**
- **Telemetry service**

## Connections

- Student → Telegram: sends update
- Telegram → Worker entry: webhook POST
- Node entry → Bot builder: builds bot
- Worker entry → Bot builder: builds bot
- Worker entry → Durable sessions: provides storage
- Bot builder → Bot toolkit: uses toolkit
- Bot builder → Start and menu: registers handlers
- Bot builder → Help: registers handlers
- Bot builder → Browse subjects: registers handlers
- Bot builder → Resource search: registers handlers
- Bot builder → Bookmarks: registers handlers
- Bot builder → Mock tests: registers handlers
- Bot builder → Study plans: registers handlers
- Start and menu → Keyboard UI: builds menus
- Bot toolkit → Memory sessions: selects fallback
- Bot toolkit → Redis sessions: selects by config
- Worker entry → Durable sessions: selects storage
- Durable sessions → Chat state and reminders: routes session and reminders
- Chat state and reminders → Telegram: sends reminder
- Bot toolkit → Activity reporter: installs reporter
- Activity reporter → Telemetry service: posts activity
- Worker entry → Telegram: passes webhook update
- Node entry → Telegram: starts polling