DevAlert - Developer Alert Platform

A Kestra-orchestrated developer alert platform that aggregates opportunities from multiple sources, filters them using LLM, and sends notifications via Telegram and Email.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    DevAlert Architecture                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    │
│  │   Frontend   │    │    Kestra    │    │   Telegram   │    │
│  │   (React)    │◄──►│  (Port 8080) │◄──►│   Bot API     │    │
│  │  (Port 5173) │    │              │    │              │    │
│  └──────────────┘    └──────┬───────┘    └──────────────┘    │
│                              │                                 │
│         ┌────────────────────┼────────────────────┐          │
│         │                    │                    │          │
│         ▼                    ▼                    ▼          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     │
│  │  Source 1   │     │  Source 2   │     │  Source N   │     │
│  │  (GitHub)   │     │  (MLH)      │     │  (GSOC)     │     │
│  └─────────────┘     └─────────────┘     └─────────────┘     │
│         │                    │                    │          │
│         └────────────────────┼────────────────────┘          │
│                              ▼                                 │
│                   ┌─────────────────┐                          │
│                   │    Aggregator   │                          │
│                   └────────┬────────┘                          │
│                            ▼                                    │
│                   ┌─────────────────┐                          │
│                   │  LLM Filter     │                          │
│                   │  (Scoring)      │                          │
│                   └────────┬────────┘                          │
│                            ▼                                    │
│                   ┌─────────────────┐                          │
│                   │  Notifier       │                          │
│                   │  (Telegram/     │                          │
│                   │   Gmail)        │                          │
│                   └─────────────────┘                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 18+ and npm
• Telegram Bot Token (get from @BotFather)
• (Optional) Gmail credentials for email notifications

Setup

1. Start Kestra:

   docker compose up -d

2. Configure Secrets in Kestra UI (http://localhost:8080):

   • Go to Settings > Secrets
   • Add the following secrets:
     • TELEGRAM_BOT_TOKEN: Your Telegram bot token
     • TELEGRAM_CHAT_ID: Your Telegram chat ID
     • GMAIL_PASSWORD: Your Gmail app password (if using email)

3. Configure Environment Variables (optional):

   • GMAIL_USERNAME: Your Gmail address
   • GMAIL_TO: Recipient email address

4. Start Frontend:

   cd frontend
   npm install
   npm run dev

5. Access:

   • Frontend: http://localhost:5173
   • Kestra UI: http://localhost:8080

Flow Structure

Master Orchestrator (devalert.master_orchestrator)

The main flow that coordinates all data fetching, filtering, and notifications.

Schedule: Every 6 hours (cron: 0 */6 * * *)

Tasks:

1. run_all_sources - Fetches data from all 6 sources in parallel
2. aggregate_all_items - Combines all items into a single list
3. filter_items - Filters items based on scoring threshold (default: 40)
4. route_notifications - Sends notifications if items pass filtering
5. set_last_run - Records last execution timestamp

Error Handling: Logs failure details on any error

Source Flows (devalert.sources.*)

Individual source flows for modular data fetching:

Flow	Description	Source URL
source_github	GitHub good-first-issue labels	api.github.com
source_hackathons	MLH hackathons	api.mlh.io
source_gsoc	Google Summer of Code RSS	opensource.googleblog.com
source_coral	Coral Project bounties	api.coralproject.net
source_hn	Hacker News jobs	hn.algolia.com
source_wemakedevs	WeMakeDevs opportunities	wemakedevs.org

Each source flow:

• Has built-in fallback data when APIs are unavailable
• Returns standardized item format
• Includes error handling with logging

Notification Flows

Flow	Namespace	Description
notify_telegram	devalert.notify	Sends Telegram notifications
notify_gmail	devalert.notify	Sends email notifications

API Endpoints

The frontend communicates with Kestra via these API endpoints:

• GET /api/v1/flows - List all flows
• GET /api/v1/flows/{namespace}/{flowId} - Get flow details
• POST /api/v1/executions/{namespace}/{flowId} - Trigger flow execution
• GET /api/v1/executions - List executions
• GET /api/v1/executions/{executionId} - Get execution details
• GET /api/v1/executions/{executionId}/logs - Get execution logs

Configuration

Docker Compose

services:
  kestra:
    image: kestra/kestra:v0.22.43
    ports:
      - "8080:8080"
    volumes:
      - kestra-data:/app/storage
      - ./kestra/flows:/app/flows
    environment:
      KESTRA_QUEUE_TYPE: memory
      KESTRA_REPOSITORY_TYPE: memory
      KESTRA_STORAGE_TYPE: local

Flow Variables

• score_threshold: Minimum score for items to pass filter (default: 40)

Secrets

Store sensitive data in Kestra secrets:

• TELEGRAM_BOT_TOKEN: Bot token from @BotFather
• TELEGRAM_CHAT_ID: Target chat ID
• GMAIL_PASSWORD: App-specific password for Gmail

Development

Project Structure

devalert/
├── docker-compose.yml          # Kestra container setup
├── kestra-config.yml           # Kestra configuration
├── kestra/
│   ├── flows/                  # Flow YAML files
│   │   ├── 00_master_orchestrator.yml
│   │   ├── source_github.yml
│   │   ├── source_hackathons.yml
│   │   ├── source_gsoc.yml
│   │   ├── source_coral.yml
│   │   ├── source_hn.yml
│   │   ├── source_wemakedevs.yml
│   │   └── notify_telegram.yml
│   └── templates/              # Notification templates
├── frontend/                   # React application
│   ├── src/
│   │   ├── components/         # UI components
│   │   ├── hooks/              # Custom React hooks
│   │   ├── utils/              # Utility functions
│   │   └── styles/             # CSS files
│   └── package.json
└── README.md

Adding New Sources

1. Create a new flow file in kestra/flows/source_<name>.yml
2. Follow the pattern of existing source flows
3. Return items with these fields:
   • id: Unique identifier
   • title: Item title
   • link: URL to item
   • date: Date string
   • description: Short description
   • source_type: Type category
   • source_name: Source display name
4. Import the flow to Kestra

Customizing LLM Filter

The filter_items task in master_orchestrator uses a simple scoring algorithm. To integrate with an actual LLM:

1. Add LLM API credentials as secrets
2. Modify the filter_items task to call your LLM provider
3. Use the LLM response to score/filter items

Troubleshooting

Common Issues

1. 401 Unauthorized on API calls

   • Ensure Kestra is running properly
   • Check that basic-auth is disabled in configuration

2. Telegram 401 error

   • Verify bot token is correct
   • Ensure bot has been started in the target chat

3. Network errors in source flows

   • Source flows include fallback data for resilience
   • Check container network connectivity

4. JSON parse errors

   • Flows use proper try/except handling
   • Fallback data ensures execution continues

Logs

View execution logs in Kestra UI:

1. Go to the execution detail page
2. Click on the task to see its logs
3. Use the log viewer for debugging

License

MIT License