# mohammedabusamra04/career-platform architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedabusamra04/career-platform
- Repository: https://github.com/mohammedabusamra04/career-platform

## Overview

AI Career Platform is a Telegram job-alert service. Users set preferences and subscribe; scheduled or on-demand runs collect postings per subscriber, deduplicate them, analyze unique jobs once, score them against preferences, and notify users about qualifying jobs not previously sent. The graph includes the bot, HTTP and scheduler entry points, pipeline stages, source integrations, matching, notifications, and Redis-backed state. Relationships are limited to shown imports/calls or explicit README claims; several source implementations were not sampled.

Main entry points: [`src/modules/jobs/job.pipeline.service.ts`](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.pipeline.service.ts) (Job pipeline), [`src/config/services.ts`](https://github.com/mohammedabusamra04/career-platform/blob/main/src/config/services.ts) (Service wiring), [`src/modules/matching/matching.service.ts`](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/matching/matching.service.ts) (AI and rule matching), [`src/modules/subscriptions/subscription.service.ts`](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/subscriptions/subscription.service.ts) (Subscription service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_bot["Telegram bot<br/>[bot.ts]"]
  node_preference_handler["Preference flow"]
  node_subscription_handler["Subscription commands"]
  node_http_app["HTTP app<br/>[app.ts]"]
  node_pipeline_route["Pipeline endpoint"]
  node_scheduler["Notification scheduler"]
  node_cli_trigger["CLI trigger<br/>[run-pipeline.ts]"]
end

subgraph group_jobs["Job collection"]
  node_pipeline["Job pipeline"]
  node_collection["Job collection"]
  node_source_manager["Source manager"]
  node_source_adapters["Job-board sources"]
end

subgraph group_matching["Deduplication and matching"]
  node_deduplication["Job deduplication"]
  node_fingerprinting["Fingerprinting"]
  node_matching_service["AI and rule matching"]
  node_gemini["Gemini provider<br/>[gemini.provider.ts]"]
end

subgraph group_delivery["Preferences and delivery"]
  node_preferences["Preference service"]
  node_subscriptions["Subscription service"]
  node_notifier["Telegram notifications"]
end

subgraph group_infra["State and integrations"]
  node_cache_adapter["Redis cache adapter<br/>[redis.adapter.ts]"]
  node_redis[("Redis<br/>[redis.ts]")]
  node_service_wiring["Service wiring<br/>[services.ts]"]
end

node_telegram_user(("Telegram user"))
node_pipeline_caller(("Pipeline caller"))

node_telegram_user -->|"sends updates"| node_bot
node_bot -->|"registers handler"| node_preference_handler
node_bot -->|"registers handler"| node_subscription_handler
node_preference_handler -->|"saves preferences"| node_preferences
node_preference_handler -->|"subscribes user"| node_subscriptions
node_subscription_handler -->|"manages subscription"| node_subscriptions
node_pipeline_caller -->|"requests run"| node_pipeline_route
node_http_app -->|"mounts route"| node_pipeline_route
node_pipeline_route -->|"triggers run"| node_pipeline
node_scheduler -->|"runs pipeline"| node_pipeline
node_cli_trigger -->|"runs pipeline"| node_pipeline
node_pipeline -->|"loads subscribers"| node_subscriptions
node_pipeline -->|"loads criteria"| node_preferences
node_pipeline -->|"collects per user"| node_collection
node_collection -->|"fetches jobs"| node_source_manager
node_source_manager -->|"dispatches sources"| node_source_adapters
node_pipeline -->|"deduplicates listings"| node_deduplication
node_deduplication -->|"creates fingerprints"| node_fingerprinting
node_pipeline -->|"analyzes unique jobs"| node_matching_service
node_pipeline -->|"scores per user"| node_matching_service
node_matching_service -->|"analyzes jobs"| node_gemini
node_matching_service -->|"caches analyses"| node_cache_adapter
node_pipeline -->|"sends qualifying jobs"| node_notifier
node_pipeline -->|"checks sent log"| node_cache_adapter
node_preferences -->|"stores preferences"| node_cache_adapter
node_subscriptions -->|"stores subscriptions"| node_redis
node_cache_adapter -->|"reads and writes"| node_redis
node_service_wiring -->|"constructs service"| node_collection
node_service_wiring -->|"registers sources"| node_source_manager
node_service_wiring -->|"constructs service"| node_matching_service
node_service_wiring -->|"constructs service"| node_pipeline
node_service_wiring -->|"constructs service"| node_notifier

click node_bot "https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/bot.ts"
click node_preference_handler "https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/handlers/preferences.handler.ts"
click node_subscription_handler "https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/handlers/subscription.handler.ts"
click node_http_app "https://github.com/mohammedabusamra04/career-platform/blob/main/src/app.ts"
click node_pipeline_route "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.pipeline.route.ts"
click node_scheduler "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/notifications/job-notification.scheduler.ts"
click node_cli_trigger "https://github.com/mohammedabusamra04/career-platform/blob/main/src/scripts/run-pipeline.ts"
click node_pipeline "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.pipeline.service.ts"
click node_collection "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.collection.service.ts"
click node_source_manager "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/sources/job-source.manager.ts"
click node_source_adapters "https://github.com/mohammedabusamra04/career-platform/tree/main/src/modules/jobs/sources"
click node_deduplication "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/deduplication/deduplication.service.ts"
click node_fingerprinting "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/deduplication/fingerprint.service.ts"
click node_matching_service "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/matching/matching.service.ts"
click node_gemini "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/matching/ai/gemini.provider.ts"
click node_preferences "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/preferences/preference.service.ts"
click node_subscriptions "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/subscriptions/subscription.service.ts"
click node_notifier "https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/notifications/telegram/telegram-notification.service.ts"
click node_cache_adapter "https://github.com/mohammedabusamra04/career-platform/blob/main/src/cache/redis.adapter.ts"
click node_redis "https://github.com/mohammedabusamra04/career-platform/blob/main/src/config/redis.ts"
click node_service_wiring "https://github.com/mohammedabusamra04/career-platform/blob/main/src/config/services.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_bot,node_preference_handler,node_subscription_handler,node_http_app,node_pipeline_route,node_scheduler,node_cli_trigger,node_telegram_user toneBlue
class node_pipeline,node_collection,node_source_manager,node_source_adapters toneAmber
class node_deduplication,node_fingerprinting,node_matching_service,node_gemini toneMint
class node_preferences,node_subscriptions,node_notifier toneRose
class node_cache_adapter,node_redis,node_service_wiring,node_pipeline_caller toneIndigo
```

## Components

### Entry points

- [Telegram bot](https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/bot.ts): `src/bot/bot.ts`
- [Preference flow](https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/handlers/preferences.handler.ts): `src/bot/handlers/preferences.handler.ts`
- [Subscription commands](https://github.com/mohammedabusamra04/career-platform/blob/main/src/bot/handlers/subscription.handler.ts): `src/bot/handlers/subscription.handler.ts`
- [HTTP app](https://github.com/mohammedabusamra04/career-platform/blob/main/src/app.ts): `src/app.ts`
- [Pipeline endpoint](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.pipeline.route.ts): `src/modules/jobs/job.pipeline.route.ts`
- [Notification scheduler](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/notifications/job-notification.scheduler.ts): `src/modules/notifications/job-notification.scheduler.ts`
- [CLI trigger](https://github.com/mohammedabusamra04/career-platform/blob/main/src/scripts/run-pipeline.ts): `src/scripts/run-pipeline.ts`

### Job collection

- [Job pipeline](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.pipeline.service.ts): `src/modules/jobs/job.pipeline.service.ts`
- [Job collection](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/job.collection.service.ts): `src/modules/jobs/job.collection.service.ts`
- [Source manager](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/jobs/sources/job-source.manager.ts): `src/modules/jobs/sources/job-source.manager.ts`
- [Job-board sources](https://github.com/mohammedabusamra04/career-platform/tree/main/src/modules/jobs/sources): `src/modules/jobs/sources`

### Deduplication and matching

- [Job deduplication](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/deduplication/deduplication.service.ts): `src/modules/deduplication/deduplication.service.ts`
- [Fingerprinting](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/deduplication/fingerprint.service.ts): `src/modules/deduplication/fingerprint.service.ts`
- [AI and rule matching](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/matching/matching.service.ts): `src/modules/matching/matching.service.ts`
- [Gemini provider](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/matching/ai/gemini.provider.ts): `src/modules/matching/ai/gemini.provider.ts`

### Preferences and delivery

- [Preference service](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/preferences/preference.service.ts): `src/modules/preferences/preference.service.ts`
- [Subscription service](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/subscriptions/subscription.service.ts): `src/modules/subscriptions/subscription.service.ts`
- [Telegram notifications](https://github.com/mohammedabusamra04/career-platform/blob/main/src/modules/notifications/telegram/telegram-notification.service.ts): `src/modules/notifications/telegram/telegram-notification.service.ts`

### State and integrations

- [Redis cache adapter](https://github.com/mohammedabusamra04/career-platform/blob/main/src/cache/redis.adapter.ts): `src/cache/redis.adapter.ts`
- [Redis](https://github.com/mohammedabusamra04/career-platform/blob/main/src/config/redis.ts): `src/config/redis.ts`
- [Service wiring](https://github.com/mohammedabusamra04/career-platform/blob/main/src/config/services.ts): `src/config/services.ts`

### Other components

- **Telegram user**
- **Pipeline caller**

## Connections

- Telegram user → Telegram bot: sends updates
- Telegram bot → Preference flow: registers handler (evidence: `src/bot/bot.ts`)
- Telegram bot → Subscription commands: registers handler (evidence: `src/bot/bot.ts`)
- Preference flow → Preference service: saves preferences (evidence: `src/bot/handlers/preferences.handler.ts`)
- Preference flow → Subscription service: subscribes user (evidence: `src/bot/handlers/preferences.handler.ts`)
- Subscription commands → Subscription service: manages subscription (evidence: `src/bot/handlers/subscription.handler.ts`)
- Pipeline caller → Pipeline endpoint: requests run
- HTTP app → Pipeline endpoint: mounts route (evidence: `src/app.ts`)
- Pipeline endpoint → Job pipeline: triggers run (evidence: `src/modules/jobs/job.pipeline.route.ts`)
- Notification scheduler → Job pipeline: runs pipeline
- CLI trigger → Job pipeline: runs pipeline (evidence: `src/scripts/run-pipeline.ts`)
- Job pipeline → Subscription service: loads subscribers (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Job pipeline → Preference service: loads criteria
- Job pipeline → Job collection: collects per user (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Job collection → Source manager: fetches jobs
- Source manager → Job-board sources: dispatches sources (evidence: `src/modules/jobs/sources/job-source.manager.ts`)
- Job pipeline → Job deduplication: deduplicates listings (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Job deduplication → Fingerprinting: creates fingerprints (evidence: `src/modules/deduplication/deduplication.service.ts`)
- Job pipeline → AI and rule matching: analyzes unique jobs (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Job pipeline → AI and rule matching: scores per user (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- AI and rule matching → Gemini provider: analyzes jobs (evidence: `src/config/services.ts`)
- AI and rule matching → Redis cache adapter: caches analyses (evidence: `src/modules/matching/matching.service.ts`)
- Job pipeline → Telegram notifications: sends qualifying jobs (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Job pipeline → Redis cache adapter: checks sent log (evidence: `src/modules/jobs/job.pipeline.service.ts`)
- Preference service → Redis cache adapter: stores preferences (evidence: `src/modules/preferences/preference.service.ts`)
- Subscription service → Redis: stores subscriptions (evidence: `src/modules/subscriptions/subscription.service.ts`)
- Redis cache adapter → Redis: reads and writes (evidence: `src/config/services.ts`)
- Service wiring → Job collection: constructs service (evidence: `src/config/services.ts`)
- Service wiring → Source manager: registers sources (evidence: `src/config/services.ts`)
- Service wiring → AI and rule matching: constructs service (evidence: `src/config/services.ts`)
- Service wiring → Job pipeline: constructs service (evidence: `src/config/services.ts`)
- Service wiring → Telegram notifications: constructs service (evidence: `src/config/services.ts`)
