https://github.com/hookdeck/deepwork
DeepWork is a web application that demonstrates the power of combining OpenAI's Deep Research API with the Hookdeck Event Gateway to support highly reliable and scalable asynchronous workflows and background jobs.
https://github.com/hookdeck/deepwork
asyncronous-jobs background-jobs background-workers hookdeck nextjs openai openai-api typescript webhooks
Last synced: 5 months ago
JSON representation
DeepWork is a web application that demonstrates the power of combining OpenAI's Deep Research API with the Hookdeck Event Gateway to support highly reliable and scalable asynchronous workflows and background jobs.
- Host: GitHub
- URL: https://github.com/hookdeck/deepwork
- Owner: hookdeck
- Created: 2025-08-08T10:54:30.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-08-08T12:58:22.000Z (5 months ago)
- Last Synced: 2025-08-08T13:33:57.913Z (5 months ago)
- Topics: asyncronous-jobs, background-jobs, background-workers, hookdeck, nextjs, openai, openai-api, typescript, webhooks
- Language: TypeScript
- Homepage:
- Size: 186 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# DeepWork: OpenAI Deep Research + Hookdeck Event Gateway
DeepWork is a web application that demonstrates the power of combining [OpenAI's Deep Research](https://platform.openai.com/docs/guides/deep-research) API with the [Hookdeck Event Gateway](https://hookdeck.com/event-gateway) to support highly reliable and scalable asynchronous workflows and background jobs.
The application enables users to submit complex research questions to OpenAI's Deep Research service, which runs asynchronously in the background. Hookdeck manages both the outbound API requests (via queue) and inbound webhook responses, providing complete visibility into the entire research workflow.
## Features
- **Asynchronous Research**: Submit long-running research tasks to OpenAI without blocking the UI.
- **Request Queuing**: Outbound requests to OpenAI are queued through Hookdeck for resilience and visibility.
- **Reliable Webhooks**: Hookdeck ensures reliable delivery of OpenAI's webhook responses.
- **Event Timeline**: View a detailed timeline of both outbound requests and inbound webhooks for each research task.
- **Simple Authentication**: A straightforward demo authentication system using NextAuth.js.
- **Serverless-first**: Built with Next.js and designed for deployment on Vercel.
## Architecture
```mermaid
graph TB
subgraph "DeepWork Application"
UI[Next.js Web UI]
API[Next.js API Routes]
KV[Vercel KV Store]
end
subgraph "Hookdeck Infrastructure"
subgraph "Connection: openai-queue"
SourceA[Source A
Queue Endpoint]
DestA[Destination
OpenAI API]
end
subgraph "Connection: openai-webhook"
SourceB[Source B
Webhook Endpoint]
DestB[Destination
/api/webhooks/openai]
end
end
subgraph "OpenAI"
DeepResearch[Deep Research API
Background Mode]
end
UI --> API
API --> KV
API --> SourceA
SourceA --> DestA
DestA --> DeepResearch
DeepResearch --> SourceB
SourceB --> DestB
DestB --> API
API --> KV
```
## Tech Stack
| Component | Technology | Purpose |
| -------------- | ------------------------ | ----------------------------------------------------- |
| Language | TypeScript | Type-safe development throughout |
| Framework | Next.js 14+ (App Router) | Modern React framework with API routes |
| Authentication | NextAuth.js | Simple demo authentication |
| Data Store | Vercel KV | Serverless Redis for persistence |
| Event Gateway | Hookdeck Event Gateway | Event Gateway infrastructure for queuing and webhooks |
| AI Service | OpenAI Deep Research | Long-running research capabilities |
| Deployment | Vercel | Serverless deployment platform |
| Polling | SWR | Data fetching with automatic revalidation |
## Getting Started
### Prerequisites
- [Node.js](https://nodejs.org/en/) (v18 or newer)
- A [Hookdeck](https://hookdeck.com/) account and API Key.
- An [OpenAI](https://openai.com/) account and API Key.
### 1. Installation
Clone the repository and install the dependencies:
```bash
git clone https://github.com/hookdeck/deepwork.git
cd deepwork
npm install
```
### 2. Environment Setup
This project uses a setup script to configure your local environment.
```bash
npm run setup:dev
```
The script will prompt you for your Hookdeck and OpenAI API keys and create a `.env.local` file with the necessary environment variables.
### 3. Start the Development Server
Once the setup is complete, start the development server:
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser to see the application.
### 4. Set up Hookdeck for Local Development
To receive webhooks from OpenAI locally, you need to use the Hookdeck CLI.
First, log in to your Hookdeck account:
```bash
npm run hookdeck:login
```
Then, start listening for webhooks:
```bash
npm run hookdeck:listen
```
This command forwards webhooks for the `openai-webhook` source to your local development server. The `setup:dev` script will have already configured the necessary Hookdeck connections for you.
## Available Scripts
- `npm run dev`: Starts the Next.js development server.
- `npm run build`: Builds the application for production.
- `npm run start`: Starts a production server.
- `npm run lint`: Lints the codebase.
- `npm run setup:dev`: Guides you through setting up your `.env.local` file.
- `npm run hookdeck`: Access the Hookdeck CLI.
- `npm run hookdeck:login`: Log in to your Hookdeck account.
- `npm run hookdeck:listen`: Start forwarding webhooks to your local server.
## Production Deployment (TODO)
This application is designed for deployment on [Vercel](https://vercel.com/).
- [ ] Configure production environment variables in Vercel.
- [ ] Set up a production Vercel KV store.
- [ ] Update `NEXTAUTH_URL` to the production URL.
- [ ] Ensure the OpenAI webhook is configured with the production Hookdeck source URL.
## Learn More
To learn more about the technologies used in this project, see the following resources:
- [Hookdeck Documentation](https://hookdeck.com/docs) - learn about Hookdeck's features.
- [OpenAI API Documentation](https://platform.openai.com/docs/api-reference) - learn about the OpenAI API.
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.