Skip to content

Architecture

Jump to bottom
Mundo edited this page Apr 8, 2026 · 2 revisions

Architecture

Overview

Oh My Workers uses a multi-agent architecture powered by LangChain and Claude. Each task is handled by a chain of specialized agents, each with a single responsibility.

Tech Stack

Layer Technology
Runtime Node.js + TypeScript
AI Framework LangChain + LangGraph
LLM Claude Sonnet (via @langchain/anthropic)
Database PostgreSQL (Neon) via pg
Trending Data GitHub Trending (HTML scraping)
Messaging Telegram Bot API
Scheduling node-cron / GitHub Actions
Validation Zod

Project Structure

src/
├── agent/
│   ├── index.ts                # WorkCoordinator — orchestrates all agents
│   ├── prompt.ts               # System prompts for all agents
│   ├── cleanup.agent.ts        # Stale record deletion
│   ├── github.agent.ts         # GitHub activity fetching
│   ├── manual-kpi.agent.ts     # Interactive KPI input
│   ├── diary.agent.ts          # KPI report generation
│   ├── news-curator.agent.ts   # LLM-powered trending repo curation
│   └── news-telegram.agent.ts  # Telegram trending delivery
├── tools/                      # DynamicStructuredTool implementations
│   ├── trending-scrape.tool.ts # GitHub trending HTML scraper
│   ├── news-curator.tool.ts    # Repo curation + tagging
│   ├── news-telegram.tool.ts   # Telegram message formatting
│   └── ...                     # GitHub, cleanup, diary tools
├── storage/
│   ├── own-db.ts               # Main DB: kpi, diary, cleanup_log, github_trending
│   └── company-db.ts           # Company DB: stale record cleanup
├── schemas/index.ts            # Zod type definitions
├── jobs/scheduler.ts           # node-cron configuration
├── constants/index.ts          # Config values
├── utils/logger.ts             # Logging helpers
└── index.ts                    # Entry point + CLI flags

.github/workflows/
├── cleanup.yml                 # Daily 5pm cleanup
├── daily-kpi.yml               # Manual KPI trigger (workflow_dispatch)
├── seed-mock-users.yml         # Daily 4:30pm mock data seeding
└── morning-news.yml            # Daily 8am GitHub trending digest

Agent Pattern

Each agent follows the same pattern:

  1. Agent — LangChain agent with a specific system prompt and one tool
  2. Tool — DynamicStructuredTool with a Zod schema defining inputs/outputs
  3. Prompt — focused system prompt that tells the LLM exactly what to do
// Example: trending curator agent
const llm = new ChatAnthropic({ model: DEFAULT_LLM, temperature: 0 })

export const trendingCuratorAgent = createAgent({
  model: llm,
  tools: [trendingCuratorTool],
  systemPrompt: TRENDING_CURATOR_PROMPT,
  middleware: [toolCallLimitMiddleware({ runLimit: 1, exitBehavior: 'end' })],
})

The toolCallLimitMiddleware ensures each agent makes exactly one tool call and exits — keeping costs predictable.

Orchestration

The WorkCoordinator class in src/agent/index.ts orchestrates multi-step pipelines:

  • Runs agents sequentially when outputs feed into the next step
  • Runs agents in parallel (via Promise.allSettled) when independent
  • Handles errors gracefully — one agent failing doesn't crash the pipeline
  • Sends Telegram alerts on failures

Error Handling

  • Promise.allSettled() for parallel operations (independent failures don't cancel each other)
  • Telegram error notifications for critical failures
  • Parse error retry logic with configurable limits
  • DB connection cleanup on exit

Clone this wiki locally