# atin-thappa/taskflow architecture

> Architecture diagram of the GitHub repository atin-thappa/taskflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atin-thappa/taskflow
- Repository: https://github.com/atin-thappa/taskflow

## Overview

1. **Overall shape**
   - TaskFlow is split into three independently run processes: **Frontend**, **Backend API**, and **Worker**.
   - The core architecture is event-driven: the API accepts workflow/webhook requests, places jobs onto **Redis/BullMQ**, and the worker performs the actual execution and persistence work.

2. **Frontend subsystem**
   - The `Frontend/` app is a **React + TypeScript + Vite** client.
   - It is responsible for workflow creation, login/signup, dashboarding, and viewing execution logs.
   - Key UI areas are the builder (`BuilderPage`, React Flow nodes, config panel), auth pages, and logs/dashboard pages.

3. **Frontend state and API boundary**
   - The builder uses **Zustand** in `store/workflowStore.ts` to manage canvas/workflow state.
   - Network access is centralized through `src/api/axios.ts`, so the UI talks only to the backend API rather than directly to the database or queue.
   - `ProtectedRoute` and `useAuth` indicate client-side auth gating around authenticated pages.

4. **Backend API subsystem**
   - The `Backend/` app is an **Express + TypeScript** service.
   - `app.ts` contains the reusable Express application setup; `server.ts` is the runtime entry point that connects to infra and starts listening.
   - This split is important for testing: the app can be imported without booting the server.

5. **Backend request pipeline**
   - Requests enter through routes in `src/routes/` and flow through middleware, controllers, and models.
   - `authMiddleware.ts` protects authenticated endpoints.
   - `errorMiddleware.ts` standardizes failure handling.
   - Controllers are organized by domain: auth, workflow, execution, and webhook.

6. **Backend data model**
   - MongoDB is the main persistent store, accessed through **Mongoose** models in `src/models/`.
   - The main entities are `User`, `Workflow`, and `Execution`.
   - `Workflow` likely stores the builder-generated automation definition and webhook identifier.
   - `Execution` stores run history, timestamps, status, and action output for the logs view.

7. **Webhook trigger path**
   - The most important inbound integration is `POST` to a workflow’s unique webhook route, handled in `webhookRoutes.ts`.
   - The README describes the flow: webhook hit → backend validates the workflow exists → backend creates an `Execution` record with `running` status → backend pushes a BullMQ job to Redis.
   - This is the handoff point between synchronous HTTP handling and asynchronous execution.

8. **Queue and decoupling layer**
   - `src/queue/workflowQueue.ts` is the backend’s bridge to **BullMQ + Redis**.
   - The API does not execute workflow actions itself; it only enqueues jobs.
   - This keeps the API stateless with respect to job processing and allows workers to scale independently.

9. **Worker subsystem**
   - `Worker/` is a separate Node.js process that consumes queued jobs.
   - It reads execution/job data, runs actions sequentially, and writes results back to MongoDB.
   - The worker is intentionally decoupled from the API, so it does not depend on incoming HTTP requests or frontend state.

10. **Worker action executors**
   - Worker actions are implemented as dedicated executors in `src/executors/`: `httpExecutor`, `discordExecutor`, and `delayExecutor`.
   - This suggests a pluggable action model where each workflow step is mapped to a specific executor type.
   - The worker’s main responsibility is orchestration of action order plus result/error reporting.

11. **Execution log feedback loop**
   - The logs page in the frontend reads execution history from the backend, which in turn comes from the `Execution` collection.
   - The user experience is therefore asynchronous: the UI does not wait for a workflow to finish inside the webhook request, it polls or refreshes logs after the worker completes.
   - This is a clean separation between trigger time and run-time visibility.

12. **Testing and CI**
   - Backend integration tests live in `Backend/src/__tests__/webhook.test.ts` and focus on the webhook trigger path.
   - CI is configured in `.github/workflows/backend-ci.yml` and uses real service containers for **MongoDB** and **Redis**, which matches the production architecture closely.
   - That CI setup is a strong clue that the queue and database are first-class parts of the system boundary.

13. **Deployment boundary**
   - The README states the intended deployment split: **Frontend on Vercel**, **Backend + Worker on Render**, **MongoDB Atlas** for data, and **Upstash Redis** for the queue.
   - Those deployment choices reinforce the repo’s architecture: stateless client, API, queue, and worker are all separately deployable pieces.

14. **What to show in an architecture diagram**
   - Draw the main data flow as: **React client → Express API → Redis queue → Worker → MongoDB**, with the client also reading execution/workflow data back through the API.
   - Show the webhook endpoint as a special inbound path to the API.
   - Keep the queue and worker as separate boxes from the API, because that decoupling is the defining architectural feature of the repo.

Main entry points: [`Frontend/src/App.tsx`](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/App.tsx) (React app), [`Backend/src/app.ts`](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/app.ts) (Express app), [`Backend/src/routes/authRoutes.ts`](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/routes/authRoutes.ts) (Routes), [`Frontend/src/api/axios.ts`](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/api/axios.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>react+vite client<br/>[App.tsx]"]
  node_frontend_builder["Builder<br/>workflow editor<br/>[BuilderPage.tsx]"]
  node_frontend_auth["Auth pages<br/>auth UI<br/>[LoginPage.tsx]"]
  node_frontend_dash["Dashboard<br/>overview UI<br/>[DashboardPage.tsx]"]
  node_frontend_logs["Logs<br/>execution UI<br/>[LogsPage.tsx]"]
  node_frontend_api["API client<br/>http boundary<br/>[axios.ts]"]
  node_frontend_store["Workflow store<br/>state store<br/>[workflowStore.ts]"]
  node_frontend_route["Protected route<br/>auth gate<br/>[ProtectedRoute.tsx]"]
end

subgraph group_backend["Backend API"]
  node_backend_server["Server entry<br/>runtime entry<br/>[server.ts]"]
  node_backend_app["Express app<br/>http app<br/>[app.ts]"]
  node_backend_routes["Routes<br/>[authRoutes.ts]"]
  node_backend_ctrls["Controllers<br/>request handlers"]
  node_backend_mw["Middleware<br/>request pipeline<br/>[authMiddleware.ts]"]
  node_backend_queue["Workflow queue<br/>bullmq bridge<br/>[workflowQueue.ts]"]
  node_backend_models[("Mongoose models<br/>mongodb schema<br/>[Workflow.ts]")]
end

subgraph group_worker["Worker"]
  node_worker_main["Job worker<br/>queue consumer<br/>[worker.ts]"]
  node_worker_exec["Executors<br/>[httpExecutor.ts]"]
end

subgraph group_data["Data & Queue"]
  node_data_mongo[("MongoDB<br/>persistent store<br/>[db.ts]")]
  node_data_redis[("Redis<br/>queue store<br/>[redis.ts]")]
end

node_frontend_app -->|"routes to"| node_frontend_builder
node_frontend_app -->|"routes to"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_dash
node_frontend_app -->|"routes to"| node_frontend_logs
node_frontend_builder -->|"uses"| node_frontend_store
node_frontend_builder -->|"calls"| node_frontend_api
node_frontend_auth -->|"calls"| node_frontend_api
node_frontend_dash -->|"calls"| node_frontend_api
node_frontend_logs -->|"calls"| node_frontend_api
node_frontend_app -->|"guards"| node_frontend_route
node_backend_server -->|"boots"| node_backend_app
node_backend_app -->|"applies"| node_backend_mw
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_ctrls
node_backend_ctrls -->|"reads/writes"| node_backend_models
node_backend_ctrls -->|"enqueues"| node_backend_queue
node_backend_queue -->|"uses"| node_data_redis
node_backend_models -->|"persists to"| node_data_mongo
node_worker_main -->|"consumes from"| node_data_redis
node_worker_main -->|"delegates to"| node_worker_exec
node_worker_main -->|"updates"| node_data_mongo
node_backend_routes -->|"webhook trigger"| node_backend_queue
node_frontend_logs -.->|"reads executions"| node_backend_routes
node_backend_app -.->|"connects"| node_data_mongo
node_backend_app -.->|"connects"| node_data_redis

click node_frontend_app "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/App.tsx"
click node_frontend_builder "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/BuilderPage.tsx"
click node_frontend_auth "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/LoginPage.tsx"
click node_frontend_dash "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/DashboardPage.tsx"
click node_frontend_logs "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/LogsPage.tsx"
click node_frontend_api "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/api/axios.ts"
click node_frontend_store "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/store/workflowStore.ts"
click node_frontend_route "https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/components/layout/ProtectedRoute.tsx"
click node_backend_server "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/server.ts"
click node_backend_app "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/app.ts"
click node_backend_routes "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/routes/authRoutes.ts"
click node_backend_ctrls "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/controllers/workflowController.ts"
click node_backend_mw "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/middleware/authMiddleware.ts"
click node_backend_queue "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/queue/workflowQueue.ts"
click node_backend_models "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/models/Workflow.ts"
click node_worker_main "https://github.com/atin-thappa/taskflow/blob/main/Worker/src/worker.ts"
click node_worker_exec "https://github.com/atin-thappa/taskflow/blob/main/Worker/src/executors/httpExecutor.ts"
click node_data_mongo "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/config/db.ts"
click node_data_redis "https://github.com/atin-thappa/taskflow/blob/main/Backend/src/config/redis.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_frontend_app,node_frontend_builder,node_frontend_auth,node_frontend_dash,node_frontend_logs,node_frontend_api,node_frontend_store,node_frontend_route toneBlue
class node_backend_server,node_backend_app,node_backend_routes,node_backend_ctrls,node_backend_mw,node_backend_queue,node_backend_models toneAmber
class node_worker_main,node_worker_exec toneMint
class node_data_mongo,node_data_redis toneRose
```

## Components

### Frontend

React client for building workflows, authentication, dashboarding, and logs.

- [React app](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/App.tsx): react+vite client · Main UI shell and route composition for the TaskFlow frontend. · `Frontend/src/App.tsx`
- [Builder](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/BuilderPage.tsx): workflow editor · Workflow creation page with canvas, nodes, and configuration panel. · `Frontend/src/pages/BuilderPage.tsx`
- [Auth pages](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/LoginPage.tsx): auth UI · Login and signup screens for user access. · `Frontend/src/pages/LoginPage.tsx`
- [Dashboard](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/DashboardPage.tsx): overview UI · Landing page for authenticated workflow and account overview. · `Frontend/src/pages/DashboardPage.tsx`
- [Logs](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/pages/LogsPage.tsx): execution UI · Execution history and run-log view for completed workflows. · `Frontend/src/pages/LogsPage.tsx`
- [API client](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/api/axios.ts): http boundary · Centralized Axios client used by the UI to call the backend API. · `Frontend/src/api/axios.ts`
- [Workflow store](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/store/workflowStore.ts): state store · Zustand store for workflow canvas and builder state. · `Frontend/src/store/workflowStore.ts`
- [Protected route](https://github.com/atin-thappa/taskflow/blob/main/Frontend/src/components/layout/ProtectedRoute.tsx): auth gate · Client-side route guard for authenticated pages. · `Frontend/src/components/layout/ProtectedRoute.tsx`

### Backend API

Express service that handles auth, workflows, executions, webhooks, and queue handoff.

- [Server entry](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/server.ts): runtime entry · Bootstraps infrastructure and starts the Express server. · `Backend/src/server.ts`
- [Express app](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/app.ts): http app · Reusable Express application setup imported by the server and tests. · `Backend/src/app.ts`
- [Routes](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/routes/authRoutes.ts): api routes · HTTP route layer for auth, workflows, executions, and webhooks. · `Backend/src/routes/authRoutes.ts`
- [Controllers](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/controllers/workflowController.ts): request handlers · Domain controllers for auth, workflow, execution, and webhook flows. · `Backend/src/controllers/workflowController.ts`
- [Middleware](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/middleware/authMiddleware.ts): request pipeline · Authentication and error-handling middleware for the API. · `Backend/src/middleware/authMiddleware.ts`
- [Workflow queue](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/queue/workflowQueue.ts): bullmq bridge · Enqueues workflow jobs into Redis for asynchronous processing. · `Backend/src/queue/workflowQueue.ts`
- [Mongoose models](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/models/Workflow.ts): mongodb schema · User, Workflow, and Execution persistence models. · `Backend/src/models/Workflow.ts`

### Worker

Separate process that consumes queued jobs and executes workflow actions.

- [Job worker](https://github.com/atin-thappa/taskflow/blob/main/Worker/src/worker.ts): queue consumer · Consumes queued jobs and orchestrates workflow execution. · `Worker/src/worker.ts`
- [Executors](https://github.com/atin-thappa/taskflow/blob/main/Worker/src/executors/httpExecutor.ts): action executors · Pluggable action implementations for HTTP, Discord, and delay steps. · `Worker/src/executors/httpExecutor.ts`

### Data & Queue

Shared persistence and queue infrastructure used by the API and worker.

- [MongoDB](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/config/db.ts): persistent store · Primary database for users, workflows, and execution history. · `Backend/src/config/db.ts`
- [Redis](https://github.com/atin-thappa/taskflow/blob/main/Backend/src/config/redis.ts): queue store · Queue backend used by BullMQ for asynchronous job dispatch. · `Backend/src/config/redis.ts`

## Connections

- React app → Builder: routes to · Application shell exposes the workflow builder.
- React app → Auth pages: routes to · Application shell exposes login and signup pages.
- React app → Dashboard: routes to · Application shell exposes the dashboard.
- React app → Logs: routes to · Application shell exposes execution logs.
- Builder → Workflow store: uses · Builder reads and writes canvas state through Zustand.
- Builder → API client: calls · Builder submits workflow data through the API client.
- Auth pages → API client: calls · Auth screens communicate with backend auth endpoints.
- Dashboard → API client: calls · Dashboard loads authenticated data from the API.
- Logs → API client: calls · Logs view fetches execution history from the API.
- React app → Protected route: guards · Authenticated sections are wrapped by the route guard.
- Server entry → Express app: boots · Server entry starts the reusable Express app.
- Express app → Middleware: applies · Express app installs auth and error middleware.
- Express app → Routes: mounts · Express app mounts the HTTP route modules.
- Routes → Controllers: dispatches · Routes forward requests into domain controllers.
- Controllers → Mongoose models: reads/writes · Controllers persist and fetch domain records through Mongoose models.
- Controllers → Workflow queue: enqueues · Webhook and workflow handling hand off jobs to the queue.
- Workflow queue → Redis: uses · BullMQ publishes jobs through Redis.
- Mongoose models → MongoDB: persists to · Mongoose models store data in MongoDB.
- Job worker → Redis: consumes from · Worker reads queued jobs from Redis.
- Job worker → Executors: delegates to · Worker dispatches each action step to an executor.
- Job worker → MongoDB: updates · Worker records execution progress and final results in MongoDB.
- Routes → Workflow queue: webhook trigger · Webhook routes start the asynchronous workflow pipeline.
- Logs → Routes: reads executions · Logs page retrieves execution history through the API.
- Express app → MongoDB: connects · API service connects to the primary database.
- Express app → Redis: connects · API service connects to the queue backend.