{"id":50732406,"url":"https://github.com/shivam-kumar-59/quelm","last_synced_at":"2026-06-10T10:01:16.208Z","repository":{"id":359911632,"uuid":"1246312105","full_name":"SHIVAM-KUMAR-59/quelm","owner":"SHIVAM-KUMAR-59","description":"A distributed multi-agent workflow platform where AI agents collaborate asynchronously to execute complex workflows at scale. Built with event-driven architecture, message queues, real-time orchestration, and a visual workflow builder.","archived":false,"fork":false,"pushed_at":"2026-06-09T11:45:17.000Z","size":1218,"stargazers_count":6,"open_issues_count":5,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T13:23:41.505Z","etag":null,"topics":["ai-agents","docker","expressjs","nextjs","nodejs","postgresql","prisma","typescript"],"latest_commit_sha":null,"homepage":"https://quelm-client.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SHIVAM-KUMAR-59.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T04:32:26.000Z","updated_at":"2026-06-09T11:55:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SHIVAM-KUMAR-59/quelm","commit_stats":null,"previous_names":["shivam-kumar-59/quelm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SHIVAM-KUMAR-59/quelm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SHIVAM-KUMAR-59%2Fquelm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SHIVAM-KUMAR-59%2Fquelm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SHIVAM-KUMAR-59%2Fquelm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SHIVAM-KUMAR-59%2Fquelm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SHIVAM-KUMAR-59","download_url":"https://codeload.github.com/SHIVAM-KUMAR-59/quelm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SHIVAM-KUMAR-59%2Fquelm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34146870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","docker","expressjs","nextjs","nodejs","postgresql","prisma","typescript"],"created_at":"2026-06-10T10:01:14.977Z","updated_at":"2026-06-10T10:01:16.171Z","avatar_url":"https://github.com/SHIVAM-KUMAR-59.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Dashboard](./preview.png)\n\n# Quelm\n\nA distributed multi-agent workflow platform where AI agents collaborate asynchronously to execute complex workflows at scale. Built with event-driven architecture, message queues, real-time orchestration, and a visual workflow builder.\n\n\u003e **Status:** Active Development \u0026nbsp;|\u0026nbsp; **Stack:** TypeScript · Next.js · Express · BullMQ · PostgreSQL · Redis · Groq · Vitest\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Tech Stack](#tech-stack)\n- [Project Structure](#project-structure)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Environment Variables](#environment-variables)\n  - [Running Locally](#running-locally)\n- [API Reference](#api-reference)\n  - [Workflows](#workflows)\n  - [Runs](#runs)\n  - [Agents](#agents)\n- [Agent Types](#agent-types)\n- [Workflow Definition Schema](#workflow-definition-schema)\n- [How It Works](#how-it-works)\n  - [Creating a Workflow](#creating-a-workflow)\n  - [Triggering a Run](#triggering-a-run)\n  - [Live Run Monitor](#live-run-monitor)\n  - [Retry and Failure Handling](#retry-and-failure-handling)\n- [Deployment](#deployment)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n\n---\n\n## Overview\n\nQuelm is a general-purpose distributed workflow platform where users visually compose workflows by connecting AI agents on a canvas, trigger runs with a JSON input payload, and watch them execute live in real time.\n\nUnder the hood, tasks flow through BullMQ queues on Redis, workers process them independently with automatic retries and exponential backoff, and an event-driven orchestrator dispatches downstream tasks as dependencies complete. Every execution is fully persisted in PostgreSQL with a complete audit trail.\n\n---\n\n## Features\n\n- **Visual Workflow Builder** — drag and drop agent nodes onto a canvas, connect them with edges, configure each node with prompts, URLs, or transformation logic\n- **Live Run Monitor** — watch a workflow execute in real time with per-node status updates via Server-Sent Events\n- **Distributed Workers** — each agent type runs as an independent worker process, scales horizontally without code changes\n- **Dependency Resolution** — parallel execution, fan-out, and sequential chains all handled automatically based on the graph structure\n- **Retry Logic** — exponential backoff with configurable max attempts per task, dead-letter handling for permanently failed jobs\n- **Critical Task Control** — mark any node as critical to fail the entire workflow on failure, or non-critical to skip and continue\n- **Agent Heartbeat** — every worker reports its liveness every 30 seconds, the dashboard shows real-time agent health\n- **Modular Agent System** — extend `BaseAgent` to add any new agent type without touching the orchestrator\n- **Structured Observability** — structured JSON logs in production, per-request logging, full task input/output history in the database\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph Client[\"Client (Next.js + Vercel)\"]\n        WB[\"Workflow Builder\\nReact Flow canvas\"]\n        RM[\"Run Monitor\\nLive SSE updates\"]\n        DB[\"Dashboard\\nMetrics \u0026 agents\"]\n    end\n\n    subgraph API[\"REST API (Express)\"]\n        WR[\"/api/workflows\"]\n        RR[\"/api/runs\"]\n        AR[\"/api/agents\"]\n        SSE[\"/api/runs/:id/stream\\nSSE endpoint\"]\n    end\n\n    subgraph Orchestrator[\"Orchestrator\"]\n        OC[\"Workflow engine\\nDependency resolver\"]\n        QE[\"QueueEvents\\nCompletion listener\"]\n        RE[\"RunEmitter\\nEvent broadcast\"]\n    end\n\n    subgraph Queues[\"BullMQ Queues (Redis)\"]\n        LQ[\"LLM_AGENT\"]\n        HQ[\"HTTP_AGENT\"]\n        TQ[\"TRANSFORM_AGENT\"]\n        EQ[\"EXTRACTION_AGENT\"]\n        NQ[\"NOTIFICATION_AGENT\"]\n        SQ[\"STORAGE_AGENT\"]\n    end\n\n    subgraph Workers[\"Agent Workers\"]\n        LA[\"LLM Agent\\nGroq API\"]\n        HA[\"HTTP Agent\"]\n        TA[\"Transform Agent\"]\n    end\n\n    subgraph Storage[\"Storage\"]\n        PG[(\"PostgreSQL\\nWorkflows · Runs · Tasks · Agents\")]\n        RD[(\"Redis\\nJob queues · State\")]\n    end\n\n    WB --\u003e|\"POST /api/workflows\"| WR\n    WB --\u003e|\"POST /api/workflows/:id/run\"| WR\n    RM --\u003e|\"GET /api/runs/:id/stream\"| SSE\n    DB --\u003e|\"GET /api/agents\"| AR\n    DB --\u003e|\"GET /api/runs\"| RR\n\n    WR --\u003e OC\n    OC --\u003e|\"Dispatch first tasks\"| LQ\n    OC --\u003e|\"Dispatch first tasks\"| HQ\n    QE --\u003e|\"completed / failed\"| OC\n    OC --\u003e|\"Dispatch next tasks\"| LQ\n    OC --\u003e RE\n    RE --\u003e|\"Push status event\"| SSE\n\n    LQ --\u003e|\"Pull job\"| LA\n    HQ --\u003e|\"Pull job\"| HA\n    TQ --\u003e|\"Pull job\"| TA\n\n    LA --\u003e|\"Update task\"| PG\n    HA --\u003e|\"Update task\"| PG\n    TA --\u003e|\"Update task\"| PG\n\n    OC --\u003e|\"Update run state\"| PG\n    API --\u003e PG\n    Queues --- RD\n```\n\n---\n\n## Tech Stack\n\n| Layer            | Technology                     | Purpose                                 |\n| ---------------- | ------------------------------ | --------------------------------------- |\n| Language         | TypeScript                     | End-to-end type safety                  |\n| Package Manager  | pnpm                           | Fast installs, strict workspace support |\n| Frontend         | Next.js + Tailwind + shadcn/ui | Full-stack React, deploys to Vercel     |\n| Workflow Canvas  | React Flow                     | Node-based visual editor                |\n| Backend          | Node.js + Express              | REST API server                         |\n| Queue System     | BullMQ + Redis                 | Task distribution, retries, job state   |\n| Database         | PostgreSQL + Prisma            | Persistent workflow and run state       |\n| AI Provider      | Groq (LLaMA 3.3 70B)           | Fast LLM inference, generous free tier  |\n| Real-time        | Server-Sent Events             | Live run monitor updates                |\n| Containerization | Docker Compose                 | Local Postgres and Redis                |\n| Testing          | Vitest + Supertest             | Unit, integration, and API tests        |\n| Deployment       | Vercel + Render                | Frontend and backend hosting            |\n\n---\n\n## Project Structure\n\n```\nquelm/\n├── client/                         # Next.js frontend\n│   ├── __tests__/                  # Test Suite\n│   ├── app/                        # App router pages\n│   ├── components/                 # React components\n│   ├── hooks/                      # Custom hooks for API calling\n│   ├── lib/                        # Utility methods and types\n│   ├── providers/                  # Context providers\n│   └── package.json\n├── server/                         # Express backend\n│   ├── agents/                     # Agent worker implementations\n│   │   ├── base.agent.ts           # Abstract base class\n│   │   ├── llm.agent.ts            # Groq LLM agent\n│   │   └── registry.ts             # Agent startup registry\n│   ├── __tests__/                  # Test suite\n│   │   ├── api/                    # API integration tests (supertest)\n│   │   ├── helpers/                # Mock factories and app builder\n│   │   ├── orchestrator/           # Orchestrator workflow tests\n│   │   ├── services/               # Service layer unit tests\n│   │   ├── utils/                  # Utility function tests\n│   │   └── setup.ts                # Global mocks and env config\n│   ├── agents/                     # Agent worker implementations\n│   │   ├── base.agent.ts           # Abstract base class\n│   │   ├── llm.agent.ts            # Groq LLM agent\n│   │   └── registry.ts             # Agent startup registry\n│   ├── api/                        # Modular REST API\n│   │   ├── workflow/               # Workflow module\n│   │   ├── run/                    # Run module\n│   │   └── agent/                  # Agent module\n│   ├── config/                     # App configuration\n│   │   ├── index.ts                # Typed env variables\n│   │   ├── logger.config.ts        # Winston logger\n│   │   ├── prisma.config.ts        # Prisma singleton\n│   │   ├── redis.config.ts         # Redis singleton\n│   │   └── groq.config.ts          # Groq client singleton\n│   ├── events/\n│   │   └── run.emitter.ts          # In-process event emitter for SSE\n│   ├── orchestrator/\n│   │   └── index.ts                # Workflow orchestration engine\n│   ├── queue/\n│   │   └── index.ts                # BullMQ queue abstraction\n│   ├── middleware/\n│   │   └── error.middleware.ts     # Global error handler\n│   ├── prisma/\n│   │   └── schema.prisma           # Database schema\n│   ├── utils/\n│   │   ├── errors.ts               # Typed API error classes\n│   │   ├── types.ts                # Shared TypeScript types\n│   │   └── template.utils.ts       # Prompt interpolation\n│   └── index.ts                    # Server entry point\n├── docker-compose.yml              # Postgres + Redis\n├── .eslintrc.js                    # Shared ESLint config\n├── .prettierrc                     # Shared Prettier config\n├── tsconfig.base.json              # Base TypeScript config\n└── pnpm-workspace.yaml             # pnpm workspace config\n```\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 20+\n- pnpm 8+\n- Docker Desktop\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/quelm.git\ncd quelm\n\n# Install all dependencies\npnpm install\n```\n\n### Environment Variables\n\nCreate the following `.env` files:\n\n**Root `.env`** — Docker Compose infrastructure:\n\n```env\nPOSTGRES_USER=postgres\nPOSTGRES_PASSWORD=postgres\nPOSTGRES_DB=agent_platform\n```\n\n**`server/.env`** — Application config:\n\n```env\n# App\nPORT=8000\n\n# Database\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/agent_platform\n\n# Redis\nREDIS_URL=redis://localhost:6379\n\n# Client URL (deployed frontend, for CORS)\nCLIENT_URL=http://localhost:3000\n\n# Groq\nGROQ_API_KEY=your_groq_api_key_here\n\n# JWT\nJWT_SECRET=your_jwt_secret\nJWT_REFRESH_SECRET=your_jwt_refresh_secret\n```\n\n**`client/.env.local`** — Frontend config:\n\n```env\nNEXT_PUBLIC_API_URL=http://localhost:8000\n```\n\nCopy the example files as a starting point:\n\n```bash\ncp .env.example .env\ncp server/.env.example server/.env\ncp client/.env.local.example client/.env.local\n```\n\nGet a free Groq API key at [console.groq.com](https://console.groq.com).\n\n### Running Locally\n\n**1. Start infrastructure:**\n\n```bash\ndocker compose up -d\n```\n\n**2. Run database migrations:**\n\n```bash\ncd server\npnpm prisma migrate dev\n```\n\n**3. Start the server:**\n\n```bash\n# From root\npnpm dev:server\n```\n\n**4. Start the client:**\n\n```bash\n# From root\npnpm dev:client\n```\n\n**5. Run tests (no infrastructure required):**\n\n```bash\n# Run all backend tests\npnpm test:server\n\n# Watch mode\npnpm test:server:watch\n\n# Run all frontend tests\npnpm test:client\n\n# Watch mode\npnpm test:client:watch\n```\n\nTests use mocked dependencies — no database, Redis, or API keys needed.\n\nThe API will be available at `http://localhost:8000` and the frontend at `http://localhost:3000`.\n\n---\n\n## API Reference\n\nAll endpoints return responses in the following shape:\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Human readable message\",\n  \"data\": {}\n}\n```\n\nErrors follow this shape:\n\n```json\n{\n  \"success\": false,\n  \"message\": \"Error description\",\n  \"errorCode\": \"NOT_FOUND\"\n}\n```\n\n### Workflows\n\n| Method | Endpoint                | Description                      |\n| ------ | ----------------------- | -------------------------------- |\n| `GET`  | `/api/workflow`         | List all workflow definitions    |\n| `GET`  | `/api/workflow/:id`     | Get a single workflow definition |\n| `POST` | `/api/workflow`         | Create a new workflow definition |\n| `POST` | `/api/workflow/:id/run` | Trigger a workflow run           |\n\n**Create a workflow:**\n\n```bash\nPOST /api/workflow\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"name\": \"Company Research Pipeline\",\n    \"description\": \"Researches a company and analyses sentiment\",\n    \"definition\": {\n      \"nodes\": [...],\n      \"edges\": [...]\n    }\n  }\n}\n```\n\n**Trigger a run:**\n\n```bash\nPOST /api/workflow/:id/run\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"input\": {\n      \"company_name\": \"Anthropic\"\n    }\n  }\n}\n```\n\n### Runs\n\n| Method | Endpoint                         | Description                     |\n| ------ | -------------------------------- | ------------------------------- |\n| `GET`  | `/api/runs`                      | List all workflow runs          |\n| `GET`  | `/api/runs/:id`                  | Get a run with all its tasks    |\n| `GET`  | `/api/runs/workflow/:workflowId` | Get all runs for a workflow     |\n| `GET`  | `/api/runs/:id/stream`           | SSE stream for live run updates |\n\n### Agents\n\n| Method | Endpoint          | Description                |\n| ------ | ----------------- | -------------------------- |\n| `GET`  | `/api/agents`     | List all registered agents |\n| `GET`  | `/api/agents/:id` | Get a single agent         |\n\n---\n\n## Agent Types\n\n| Type                 | Description                                        | Use Case                                                  |\n| -------------------- | -------------------------------------------------- | --------------------------------------------------------- |\n| `LLM_AGENT`          | Calls Groq with a configurable prompt template     | Summarisation, classification, extraction, generation     |\n| `HTTP_AGENT`         | Makes an HTTP request to any external API          | Fetching data, sending webhooks, third-party integrations |\n| `TRANSFORM_AGENT`    | Transforms and reshapes JSON data                  | Filtering fields, mapping values, formatting              |\n| `EXTRACTION_AGENT`   | Extracts structured data from unstructured sources | Web scraping, PDF parsing, raw text parsing               |\n| `NOTIFICATION_AGENT` | Sends notifications                                | Emails, Slack messages, webhooks                          |\n| `STORAGE_AGENT`      | Reads from or writes to external storage           | Saving results, reading files, S3 operations              |\n\n---\n\n## Workflow Definition Schema\n\nA workflow definition is a JSON object with `nodes` and `edges`:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"id\": \"node_1\",\n      \"type\": \"LLM_AGENT\",\n      \"name\": \"Research Company\",\n      \"critical\": true,\n      \"config\": {\n        \"promptTemplate\": \"Research {{company_name}} and summarise their recent news in 3 bullet points.\",\n        \"model\": \"llama-3.3-70b-versatile\",\n        \"maxTokens\": 500\n      }\n    },\n    {\n      \"id\": \"node_2\",\n      \"type\": \"LLM_AGENT\",\n      \"name\": \"Sentiment Analysis\",\n      \"critical\": true,\n      \"config\": {\n        \"promptTemplate\": \"Analyse the sentiment of this text — return positive, negative, or neutral with a one sentence reason: {{text}}\",\n        \"model\": \"llama-3.3-70b-versatile\",\n        \"maxTokens\": 100\n      }\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"edge_1\",\n      \"source\": \"node_1\",\n      \"target\": \"node_2\"\n    }\n  ]\n}\n```\n\nPrompt templates support `{{variable}}` placeholders. The first node receives the run input as its variables. Subsequent nodes receive the output of their dependency tasks.\n\n---\n\n## How It Works\n\n### Creating a Workflow\n\nOpen the Workflow Builder, drag agent nodes onto the canvas, connect them with edges, and configure each node's prompt or settings in the side panel. Save the workflow — it gets stored as a JSON definition in PostgreSQL.\n\n### Triggering a Run\n\nClick Run on any saved workflow, fill in the input payload, and hit Execute. The API creates a `WorkflowRun` row, instantiates `Task` rows for every node, builds a dependency map from the edges, and dispatches the first tasks (those with no incoming edges) to the appropriate BullMQ queues. The run starts asynchronously and the API returns immediately with a `runId`.\n\n### Live Run Monitor\n\nThe frontend opens an SSE connection to `/api/runs/:id/stream`. As each task completes, the worker updates the database and the orchestrator emits an event on the `RunEmitter`. The SSE endpoint pushes that event to the browser — the canvas node changes colour (blue for running, green for completed, red for failed) without a single page refresh.\n\n### Retry and Failure Handling\n\nEvery task has a configurable `maxAttempts` (default 3). BullMQ retries failed jobs with exponential backoff. If a task marked `critical: true` exhausts all attempts, the entire workflow run is marked `FAILED` and all pending tasks are cancelled. Non-critical task failures are logged and skipped — the run continues with remaining tasks.\n\n### Stale Run Timeout\n\nRuns that have been in `RUNNING` status for more than 10 minutes with no task activity (no task has reached `RUNNING` or `COMPLETED`) are automatically marked as `FAILED` and all pending tasks are cancelled. A background job runs every 5 minutes to detect and clean up stale runs. This covers edge cases where invalid configuration, type mismatches, or worker unavailability prevent any task from progressing.\n\n---\n\n## Testing\n\nThe project includes both backend and frontend test suites powered by **Vitest**. Tests are designed to run locally and in CI without requiring external infrastructure such as databases, Redis instances, or third-party API keys.\n\n### Backend Test Structure\n\n```text\nserver/__tests__/\n├── setup.ts                # Global mocks (Prisma, Redis, BullMQ, Groq, Winston)\n├── helpers/\n│   ├── prisma.ts           # Mock PrismaClient factory\n│   └── app.ts              # Express app builder for integration tests\n├── utils/                  # Error classes, template interpolation\n├── services/               # Workflow, auth, run, agent, dashboard\n├── orchestrator/           # Workflow engine, dependency resolution, event handling\n└── api/                    # Integration tests via supertest\n```\n\n### Frontend Test Structure\n\n```text\nclient/__tests__/\n├── helpers.tsx             # Shared render utilities and mock factories\n├── LoginPage.test.tsx\n├── RegisterPage.test.tsx\n├── RunPage.test.tsx\n├── AgentsPage.test.tsx\n└── StatCard.test.tsx\n```\n\n### Coverage Areas\n\n#### Backend\n\n| Layer        | Tests | What's tested                                                 |\n| ------------ | ----- | ------------------------------------------------------------- |\n| Utils        | 11    | Error classes, `{{placeholder}}` interpolation                |\n| Services     | 38    | CRUD validation, ownership checks, auth flow, stats           |\n| Orchestrator | 13    | triggerRun, dependency graph, task dispatch, failure handling |\n| API          | 20    | Auth, workflows, agents, dashboard — via supertest            |\n\n#### Frontend\n\n| Area        | What's tested                                                    |\n| ----------- | ---------------------------------------------------------------- |\n| Auth Pages  | Login and registration flows, validation, redirects, and toasts  |\n| Runs Page   | Loading, error, empty, and populated states, duration formatting |\n| Agents Page | Agent listing, loading states, and empty-state rendering         |\n| Components  | Dashboard components such as StatCard                            |\n\n### Running Tests\n\n```bash\n# Run all tests\npnpm test\n\n# Run backend tests\npnpm test:server\n\n# Run frontend tests\npnpm test:client\n\n# Backend watch mode\npnpm test:server:watch\n\n# Frontend watch mode\npnpm test:client:watch\n\n# Run a specific backend test file\npnpm --filter server vitest run __tests__/services/workflow.service.test.ts\n\n# Run a specific frontend test file\npnpm --filter client vitest run __tests__/LoginPage.test.tsx\n```\n\n### CI Integration\n\nThe test suite is automatically executed in GitHub Actions on every push and pull request to ensure that frontend and backend changes do not introduce regressions.\n\n### Mock Strategy\n\n#### Backend\n\n- **`@prisma/client`** — globally mocked; `PrismaClient` returns configured mock methods\n- **`bullmq`** — `Queue`, `Worker`, and `QueueEvents` are mocked; no Redis connection required\n- **`ioredis`** — `Redis` constructor returns a no-op mock\n- **`groq-sdk`** — `Groq` returns a mock `chat.completions.create`\n- **`winston`** — `createLogger` returns a no-op logger\n- **`bcryptjs`** — `hash` and `compare` are stubbed to avoid real crypto operations\n\n#### Frontend\n\n- **`next/navigation`** — mocked router and navigation hooks\n- **`next/link`** — rendered as a standard anchor element for assertions\n- **`sonner`** — toast notifications mocked to prevent portal rendering\n- **`@xyflow/react`** — React Flow components mocked for lightweight testing\n- **`@monaco-editor/react`** — Monaco editor replaced with a simple textarea\n- **React Query** — wrapped with a dedicated test `QueryClientProvider`\n- Shared mock factories provide reusable workflow, run, agent, and dashboard data\n\nServices use dependency injection and isolated mocks, allowing tests to run quickly and deterministically without external services.\n\n---\n\n## Deployment\n\n### Frontend — Vercel\n\n1. Push your code to GitHub\n2. Go to [vercel.com](https://vercel.com) and import the repository\n3. Set the root directory to `client`\n4. Add the environment variable `NEXT_PUBLIC_API_URL` pointing to your Render backend URL\n5. Deploy — Vercel auto-deploys on every push to `main`\n\n### Backend — Render\n\n1. Go to [render.com](https://render.com) and create a new **Web Service**\n2. Connect your GitHub repository and set the root directory to `server`\n3. Set the build command to `pnpm install \u0026\u0026 pnpm prisma generate \u0026\u0026 pnpm build`\n4. Set the start command to `pnpm start`\n5. Add a **PostgreSQL** database from the Render dashboard — it injects `DATABASE_URL` automatically\n6. Add a **Redis** instance from the Render dashboard — copy the external URL into `REDIS_URL`\n7. Add remaining environment variables — `GROQ_API_KEY`, `PORT`, `NODE_ENV=production`\n8. Deploy\n\n\u003e Both Vercel and Render have free tiers that cover this project with no credit card required.\n\n---\n\n## Roadmap\n\n- [x] User authentication (JWT + refresh tokens)\n- [x] HTTP Agent implementation\n- [x] Transform Agent implementation\n- [x] Backend testing infrastructure (Vitest, 83 tests)\n- [ ] Node name editing in the workflow builder\n- [ ] Workflow versioning\n- [ ] Scheduled workflow triggers (cron)\n- [ ] Webhook triggers\n- [ ] Multi-tenancy support\n\n---\n\n## Contributing\n\nContributions, issues, and feature requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, coding standards, branching strategy, and a step-by-step guide to adding new agent types.\n\n1. Fork the repository\n2. Create a feature branch — `git checkout -b feature/my-feature`\n3. Commit your changes — `git commit -m 'feat: add my feature'`\n4. Push to the branch — `git push origin feature/my-feature`\n5. Open a Pull Request against `main`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshivam-kumar-59%2Fquelm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshivam-kumar-59%2Fquelm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshivam-kumar-59%2Fquelm/lists"}