# udit-agarwal20/taskmaster-ai architecture

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

- Interactive diagram: https://gitdiagram.com/udit-agarwal20/taskmaster-ai
- Repository: https://github.com/udit-agarwal20/taskmaster-ai

## Overview

Taskmaster is an event-driven project operator: it turns merged GitHub changes or user goals into analyzed, policy-governed follow-up work, with human approval for consequential actions and verified results recorded and communicated. The README documents the asynchronous event path and the policy/verification guarantees; sampled routes confirm webhook ingestion, approval resolution, and API boundaries. Workflow and agent internals are represented at their existing source paths, but their unsampled call details are not expanded beyond documented behavior.

Main entry points: [`db/repositories/index.ts`](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/repositories/index.ts) (Domain Repositories), [`lib/services/workflow.service.ts`](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/services/workflow.service.ts) (Workflow Service), [`app/api/integrations/github/webhook/route.ts`](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/integrations/github/webhook/route.ts) (GitHub Webhook), [`agent/taskmaster_agent.ts`](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/taskmaster_agent.ts) (Root Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Event Ingestion"]
  node_webhook["GitHub Webhook<br/>[route.ts]"]
  node_github_normalize["Webhook Validation<br/>[webhook.ts]"]
  node_events["Event Records"]
  node_pubsub["Cloud Pub/Sub<br/>[pubsub.ts]"]
end

subgraph group_orchestration["Workflow Orchestration"]
  node_cloud_worker["Push Worker<br/>[route.ts]"]
  node_worker_runtime["Worker Runtime<br/>[worker.ts]"]
  node_workflow["Workflow Service"]
  node_agent_api["Agent API<br/>[route.ts]"]
end

subgraph group_decision["Agent And Policy"]
  node_agent["Root Agent"]
  node_read_tools["Project Inspection<br/>[read_tools.ts]"]
  node_policy["Action Policy<br/>[policy.ts]"]
end

subgraph group_operations["Execution And Records"]
  node_executor["Action Executor<br/>[executor.ts]"]
  node_database[("PostgreSQL<br/>[client.ts]")]
  node_repositories["Domain Repositories<br/>[index.ts]"]
  node_slack["Slack Notifications<br/>[client.ts]"]
end

subgraph group_product["Project Operations"]
  node_analysis["Project Analysis"]
  node_approval_api["Approval Resolution<br/>[route.ts]"]
  node_project_api["Project APIs<br/>[route.ts]"]
  node_workflows_api["Workflow History API<br/>[route.ts]"]
  node_status_api["Integration Status API<br/>[route.ts]"]
end

node_github(("GitHub"))
node_user(("Project Operator"))

node_github -->|"delivers event"| node_webhook
node_webhook -->|"verifies and normalizes"| node_github_normalize
node_webhook -->|"deduplicates and persists"| node_events
node_webhook -->|"publishes event"| node_pubsub
node_pubsub -->|"pushes message"| node_cloud_worker
node_cloud_worker -->|"dispatches message"| node_worker_runtime
node_worker_runtime -->|"processes event"| node_workflow
node_user -->|"requests planning"| node_agent_api
node_agent_api -->|"creates and executes run"| node_workflow
node_workflow -->|"requests reasoning"| node_agent
node_agent -->|"inspects project"| node_read_tools
node_read_tools -->|"reads project state"| node_repositories
node_agent -->|"analyzes risks"| node_analysis
node_workflow -->|"classifies actions"| node_policy
node_workflow -->|"executes allowed actions"| node_executor
node_workflow -->|"records run and audit"| node_repositories
node_executor -->|"mutates project state"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_executor -->|"sends verified updates"| node_slack
node_user -->|"resolves approval"| node_approval_api
node_approval_api -->|"validates and records decision"| node_repositories
node_approval_api -->|"resumes approved run"| node_workflow
node_project_api -->|"reads and creates tasks"| node_repositories
node_project_api -->|"accesses state"| node_database
node_workflows_api -->|"reads runs and approvals"| node_repositories
node_status_api -->|"reads integration activity"| node_repositories

click node_webhook "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/integrations/github/webhook/route.ts"
click node_github_normalize "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/integrations/github/webhook.ts"
click node_events "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/repositories/event.repository.ts"
click node_pubsub "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/cloud/pubsub.ts"
click node_cloud_worker "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/workers/event-worker/route.ts"
click node_worker_runtime "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/cloud/worker.ts"
click node_workflow "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/services/workflow.service.ts"
click node_agent_api "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/agent/route.ts"
click node_agent "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/taskmaster_agent.ts"
click node_read_tools "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/tools/read_tools.ts"
click node_analysis "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/services/project-analysis.service.ts"
click node_policy "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/policy.ts"
click node_executor "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/executor.ts"
click node_approval_api "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/approvals/%5BapprovalId%5D/resolve/route.ts"
click node_database "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/client.ts"
click node_repositories "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/repositories/index.ts"
click node_slack "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/integrations/slack/client.ts"
click node_project_api "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/projects/%5BprojectId%5D/tasks/route.ts"
click node_workflows_api "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/workflows/route.ts"
click node_status_api "https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/integrations/status/route.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_webhook,node_github_normalize,node_events,node_pubsub toneBlue
class node_cloud_worker,node_worker_runtime,node_workflow,node_agent_api toneAmber
class node_agent,node_read_tools,node_policy toneMint
class node_executor,node_database,node_repositories,node_slack toneRose
class node_analysis,node_approval_api,node_project_api,node_workflows_api,node_status_api,node_github,node_user toneIndigo
```

## Components

### Event Ingestion

- [GitHub Webhook](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/integrations/github/webhook/route.ts): `app/api/integrations/github/webhook/route.ts`
- [Webhook Validation](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/integrations/github/webhook.ts): `lib/integrations/github/webhook.ts`
- [Event Records](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/repositories/event.repository.ts): `db/repositories/event.repository.ts`
- [Cloud Pub/Sub](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/cloud/pubsub.ts): `lib/cloud/pubsub.ts`

### Workflow Orchestration

- [Push Worker](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/workers/event-worker/route.ts): `app/api/workers/event-worker/route.ts`
- [Worker Runtime](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/cloud/worker.ts): `lib/cloud/worker.ts`
- [Workflow Service](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/services/workflow.service.ts): `lib/services/workflow.service.ts`
- [Agent API](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/agent/route.ts): `app/api/agent/route.ts`

### Agent And Policy

- [Root Agent](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/taskmaster_agent.ts): `agent/taskmaster_agent.ts`
- [Project Inspection](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/tools/read_tools.ts): `agent/tools/read_tools.ts`
- [Action Policy](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/policy.ts): `agent/policy.ts`

### Execution And Records

- [Action Executor](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/agent/executor.ts): `agent/executor.ts`
- [PostgreSQL](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/client.ts): `db/client.ts`
- [Domain Repositories](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/db/repositories/index.ts): `db/repositories/index.ts`
- [Slack Notifications](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/integrations/slack/client.ts): `lib/integrations/slack/client.ts`

### Project Operations

- [Project Analysis](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/lib/services/project-analysis.service.ts): `lib/services/project-analysis.service.ts`
- [Approval Resolution](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/approvals/%5BapprovalId%5D/resolve/route.ts): `app/api/approvals/[approvalId]/resolve/route.ts`
- [Project APIs](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/projects/%5BprojectId%5D/tasks/route.ts): `app/api/projects/[projectId]/tasks/route.ts`
- [Workflow History API](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/workflows/route.ts): `app/api/workflows/route.ts`
- [Integration Status API](https://github.com/udit-agarwal20/taskmaster-ai/blob/main/app/api/integrations/status/route.ts): `app/api/integrations/status/route.ts`

### Other components

- **GitHub**
- **Project Operator**

## Connections

- GitHub → GitHub Webhook: delivers event
- GitHub Webhook → Webhook Validation: verifies and normalizes
- GitHub Webhook → Event Records: deduplicates and persists
- GitHub Webhook → Cloud Pub/Sub: publishes event
- Cloud Pub/Sub → Push Worker: pushes message
- Push Worker → Worker Runtime: dispatches message
- Worker Runtime → Workflow Service: processes event
- Project Operator → Agent API: requests planning
- Agent API → Workflow Service: creates and executes run
- Workflow Service → Root Agent: requests reasoning
- Root Agent → Project Inspection: inspects project
- Project Inspection → Domain Repositories: reads project state
- Root Agent → Project Analysis: analyzes risks
- Workflow Service → Action Policy: classifies actions
- Workflow Service → Action Executor: executes allowed actions
- Workflow Service → Domain Repositories: records run and audit
- Action Executor → Domain Repositories: mutates project state
- Domain Repositories → PostgreSQL: reads and writes
- Action Executor → Slack Notifications: sends verified updates
- Project Operator → Approval Resolution: resolves approval
- Approval Resolution → Domain Repositories: validates and records decision
- Approval Resolution → Workflow Service: resumes approved run
- Project APIs → Domain Repositories: reads and creates tasks
- Project APIs → PostgreSQL: accesses state
- Workflow History API → Domain Repositories: reads runs and approvals
- Integration Status API → Domain Repositories: reads integration activity