Developer Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• docker-compose.local.yml
• slack_app_manifest.yml
• link.sh
• src/lib/constants.ts
• src/slack/slack-events-handler.service.ts
• src/slack/app_home.service.ts

Quix is an AI-powered Slack agent built on Nest.js that interacts with various business tools like JIRA, GitHub, and HubSpot directly from Slack. This guide provides a comprehensive walkthrough for setting up a local development environment. The project uses a monorepo structure to manage different integration packages.

The setup process involves cloning the repository, configuring environment variables, setting up a Slack application, initializing the database, and running the application services. Both a manual setup using yarn and a containerized setup using Docker are supported.

Sources: README.md:3-6, 19-25

1. Prerequisites

Before you begin, ensure you have the following tools installed on your system:

• Git
• Yarn
• Node.js
• Docker and Docker Compose
• ngrok or a similar tunneling tool for local Slack development.

You can install ngrok via Homebrew or npm:

# via Homebrew (macOS)
brew install ngrok

# via npm
npm install -g ngrok

Sources: README.md:49-56, 102-104

2. Initial Setup

This diagram illustrates the high-level steps for setting up the Quix development environment.

Step 1: Clone Repository and Install Dependencies

First, clone the project from GitHub and install the required Node.js packages using yarn.

git clone <repository-url>
cd quix
yarn install

The yarn install command will download all dependencies listed in package.json, including the Nest.js framework, Slack SDKs, and various agent packages for integrations.

Sources: README.md:31-38, package.json:33-60

Step 2: Configure Environment

Copy the example environment file and populate it with your specific configuration details.

cp .env.example .env

The .env file contains sensitive keys and configuration for the application, database, and third-party services.

Variable	Description	Example
PORT	The port on which the Nest.js server will run.	3000
OPENAI_API_KEY	Your API key for OpenAI services.	sk-...
SLACK_BOT_TOKEN	The Bot User OAuth Token from your Slack app.	xoxb-...
SLACK_SIGNING_SECRET	The Signing Secret from your Slack app's "Basic Information" page.	a1b2c3...
SELFSERVER_URL	The public-facing URL of your development server (e.g., your ngrok URL).	https://your-ngrok-url.ngrok.io
DB_HOST	Hostname for the PostgreSQL database.	localhost
DB_PORT	Port for the PostgreSQL database.	5432
DB_USER	Username for the database.	postgres
DB_PASSWORD	Password for the database user.	password
DB_NAME	Name of the database.	quix
REDIS_HOST	Hostname for the Redis instance.	localhost
REDIS_PORT	Port for the Redis instance.	6379

Sources: README.md:40-46, 61-75

3. Slack Application Setup

To integrate Quix with Slack, you need to create a Slack app using the provided manifest file. This process involves exposing your local server to the internet using ngrok and configuring the app with the correct callback URLs.

Slack App Creation and Configuration Flow

This sequence diagram shows the interaction between the developer, ngrok, and the Slack API dashboard during app setup.

Detailed Steps

1. Start the Local Server: Run the application in development mode.

   yarn start:dev
   

   Sources: README.md:54-55

2. Expose Localhost with ngrok: In a new terminal, create a public URL for your local server.

   ngrok http 3000
   

   Take note of the https://...ngrok.io URL provided.
   Sources: README.md:57-58

3. Create the Slack App:

   • Navigate to the Slack API Dashboard and choose "Create New App" -> "From an app manifest".
   • Copy the entire content of slack_app_manifest.yml.
   • In the manifest content, replace the placeholder URLs with your ngrok URL:
     • <YOUR_EVENTS_URL> becomes https://your-ngrok-url.ngrok.io/slack/events
     • <YOUR_INTERACTIONS_URL> becomes https://your-ngrok-url.ngrok.io/slack/interactions
     • <YOUR_REDIRECT_URL> becomes https://your-ngrok-url.ngrok.io/slack/install
   • Click "Create" to finalize the app.
     Sources: README.md:63-83, slack_app_manifest.yml:32, 40, 60

4. Install App and Get Credentials:

   • In your app's settings, go to "OAuth & Permissions" and click "Install to Workspace".
   • Copy the Bot User OAuth Token and set it as SLACK_BOT_TOKEN in your .env file.
   • Go to "Basic Information", copy the Signing Secret, and set it as SLACK_SIGNING_SECRET in your .env file.
     Sources: README.md:87-93

4. Database and Application Launch

Database Migration

Once the environment is configured, run the database migrations to set up the required tables. The application uses sequelize-cli for this purpose.

yarn db:migrate

This command executes the migration files to create tables such as slack_workspaces, jira_configs, github_configs, etc.

Sources: README.md:95-97, package.json:25

Running the Application

You can run the application either directly on your host machine for development or using Docker Compose for a more isolated environment.

Local Development Mode

To run the application with hot-reloading enabled, use the start:dev script.

yarn start:dev

This command uses nest start --watch to monitor for file changes and automatically restart the server.

Sources: README.md:99-101, package.json:17

Docker Compose for Local Development

The docker-compose.local.yml file defines the services needed for local development, including the main application, a PostgreSQL database, and Redis.

This diagram shows the services defined in the local Docker Compose setup.

To start all services:

docker-compose -f docker-compose.local.yml up

This will build the quix image if it doesn't exist and start the quix-app, postgres, and redis containers. The application will be available on the port mapped in the compose file (default 3000:3000).

Sources: README.md:108-110, docker-compose.local.yml:7, 23, 31

5. Project Structure and Integrations

The project is structured as a monorepo with a main Nest.js application in src/ and individual integration packages located in agent-packages/packages/.

Key Directories

• src/: The core Nest.js application, handling Slack events, LLM interactions, and database models.
• agent-packages/packages/: Contains individual packages for each supported integration (e.g., GitHub, Jira).

Sources: README.md:19-25

Supported Integrations

Quix supports a variety of integrations, each managed as a separate package.

Integration	Package Name
GitHub	@clearfeed-ai/quix-github-agent
Jira	@clearfeed-ai/quix-jira-agent
HubSpot	@clearfeed-ai/quix-hubspot-agent
PostgreSQL	@clearfeed-ai/quix-postgres-agent
Notion	@clearfeed-ai/quix-notion-agent
Okta	@clearfeed-ai/quix-okta-agent
Salesforce	@clearfeed-ai/quix-salesforce-agent
Slack	@clearfeed-ai/quix-slack-agent
Zendesk	@clearfeed-ai/quix-zendesk-agent
JumpCloud	@clearfeed-ai/quix-jumpcloud-agent
AssetPanda	@clearfeed-ai/quix-assetpanda-agent
BambooHR	@clearfeed-ai/quix-bamboohr-agent

Sources: package.json:34-45, link.sh:12, 26-37, src/lib/constants.ts:5-17

Extending the Platform

To add a new integration, you create a new package under agent-packages/packages/. After creating the package, you must build and link it to the main application using the provided script.

./link.sh

This script uses yarn link to create symbolic links between the integration packages and the root node_modules directory, making them available for local development.

Sources: README.md:112-121, link.sh

6. Useful Scripts

The package.json file contains several scripts to aid in development.

Script	Description
build	Compiles the TypeScript source code into JavaScript in the dist directory.
start:dev	Starts the application in watch mode for development.
start:prod	Starts the application from the compiled dist folder for production.
lint	Lints the codebase and automatically fixes issues.
test	Runs the Jest test suite.
db:migrate	Applies pending database migrations.
db:migrate:undo	Reverts the last applied database migration.
build:packages	Builds all integration packages in the agent-packages directory.
link:packages	Links all local integration packages for development.

Sources: package.json:13-27