Environment Configuration

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/clearfeed/quix/blob/HEAD/README.md) - [src/lib/constants.ts](https://github.com/clearfeed/quix/blob/HEAD/src/lib/constants.ts) - [src/database/models/slack-workspace.model.ts](https://github.com/clearfeed/quix/blob/HEAD/src/database/models/slack-workspace.model.ts) - [src/slack/views/app_home.ts](https://github.com/clearfeed/quix/blob/HEAD/src/slack/views/app_home.ts) - [src/slack/views/modals.ts](https://github.com/clearfeed/quix/blob/HEAD/src/slack/views/modals.ts) - [agent-packages/packages/github/src/schema.ts](https://github.com/clearfeed/quix/blob/HEAD/agent-packages/packages/github/src/schema.ts) - [agent-packages/packages/okta/src/tools.ts](https://github.com/clearfeed/quix/blob/HEAD/agent-packages/packages/okta/src/tools.ts) - [src/llm/agent-evals/jira-agent/test-data.ts](https://github.com/clearfeed/quix/blob/HEAD/src/llm/agent-evals/jira-agent/test-data.ts) - [package.json](https://github.com/clearfeed/quix/blob/HEAD/package.json) - [src/slack/slack-events-handler.service.ts](https://github.com/clearfeed/quix/blob/HEAD/src/slack/slack-events-handler.service.ts) - [CONTRIBUTING.md](https://github.com/clearfeed/quix/blob/HEAD/CONTRIBUTING.md)

Quix is an AI-powered Slack agent that can interact with various business tools such as JIRA, GitHub, HubSpot, and more. This functionality is enabled by a modular integration system that allows Quix to connect to external services, understand their capabilities, and perform actions on behalf of users. Users can interact with these services using natural language directly from Slack channels or in direct messages with the Quix bot.

The integration framework is designed to be extensible, allowing new services to be added with a consistent structure for configuration, authentication, and tool definition.

Sources: README.md, src/lib/constants.ts

System Architecture

Quix utilizes a monorepo structure where the core application logic resides in the src/ directory, and each integration is encapsulated within its own package in the agent-packages/packages/ directory. This modular design promotes separation of concerns and simplifies the process of adding or updating integrations.

Sources: README.md:21-38

The diagram below illustrates the high-level architecture of the integration system.

Database Model

Connection configurations for each integration are stored in the database. The slack_workspaces table holds general information about a Slack workspace, and it has HasOne relationships to specific configuration tables for each integration (e.g., JiraConfig, GithubConfig). This allows each workspace to have its own set of connected integrations. Sensitive information, such as API tokens and access tokens, is encrypted before being stored in the database.

The following Entity-Relationship diagram shows the relationship between the SlackWorkspace and its integration configurations.

Supported Integrations

Quix supports a variety of integrations out-of-the-box. The connection method varies, with some using OAuth 2.0 for authorization and others requiring manual entry of API keys or credentials.

Integration	Summary	Connection Type
JIRA	Create, search, and update issues in JIRA	OAuth
GitHub	Create, update, and search issues or PRs in GitHub	OAuth
Hubspot	Track contacts, companies, and deals in HubSpot	OAuth
Zendesk	Create, update, and view tickets in Zendesk	API Key
Postgres	Run natural-language queries on your Postgres database	Credentials
Salesforce	View and update opportunities, contacts, and accounts	OAuth
Notion	Search, browse, and retrieve content from your Notion workspace	API Key
Linear	Manage and search tasks or issues in Linear	API Key
Okta	Look up users, groups, and apps in Okta	API Key
JumpCloud	Look up users, and groups in JumpCloud	API Key

Sources: src/lib/constants.ts:40-205, README.md:10-17

Other integrations are available as packages, including AssetPanda and BambooHR.

Sources: agent-packages/packages/assetpanda/package.json:2, agent-packages/packages/bamboohr/package.json:2

Connection and Configuration

Integrations can be connected and configured from the App Home tab in Slack. There are two primary methods for establishing a connection.

Sources: src/slack/views/app_home.ts:200-221

OAuth 2.0 Flow

Integrations like GitHub, Jira, Hubspot, and Salesforce use an OAuth 2.0 flow for authentication. When a user clicks "Connect", they are redirected to the service's authorization page. After granting permission, they are redirected back to Quix, which receives and securely stores the access token.

The following diagram shows the sequence for an OAuth-based connection.

The scopes requested during the OAuth flow are predefined for each service. For example, the GitHub integration requests repo, user, and read:org scopes.

Sources: src/lib/constants.ts:36-38, src/slack/views/app_home.ts:400-405

API Key / Direct Configuration

Other integrations, such as Postgres, Notion, and Okta, require manual configuration via a modal window in Slack. Users provide credentials like API tokens, hostnames, and passwords, which are then securely stored.

For example, connecting to a PostgreSQL database requires the following details:

Field	Description	Example
Host	The database hostname or IP address.	db.example.com
Port	The port number for the database.	5432
Database	The name of the database to connect to.	mydb
Username	The username for authentication.	postgres
Password	The password for the user.	********
SSL	Whether to use an SSL connection.	true/false

Sources: src/slack/views/modals.ts:10-72

Similarly, connecting to Okta requires:

Field	Description	Example
Organization URL	The base URL for your Okta organization.	https://your-org.okta.com
API Token	An API token with necessary permissions.	00a...

Sources: src/slack/views/modals.ts:571-605

Integration Capabilities (Tooling)

Each integration package exports a set of "tools" which are functions the LLM can invoke to perform actions. These tools are defined with clear names, descriptions, and input schemas (using zod), which helps the AI agent decide which tool to use for a given user request.

Sources: src/slack/views/app_home.ts:71-160, agent-packages/packages/okta/src/tools.ts:1-24

GitHub Integration

The GitHub agent provides tools for managing repositories, issues, and pull requests.

Tool Name (from schema)	Description	Key Parameters
searchIssuesOrPullRequestsSchema	Search for issues or pull requests.	type, keyword, reporter, assignee, status, repo, owner
createGithubIssueSchema	Create a new issue.	title, description, assignee, repo, owner
addGithubAssigneeSchema	Add an assignee to an issue or PR.	issueNumber, assignee, repo, owner
addIssueCommentSchema	Add a comment to an issue or PR.	issue_number, body, repo, owner
createPullRequestSchema	Create a new pull request.	title, head, base, body, repo, owner

Sources: agent-packages/packages/github/src/schema.ts

Jira Integration

The Jira agent is used for project and issue tracking. Test data shows it uses tools to fetch, find, and create issues.

Tool Name (from tests)	Description	Key Parameters
get_jira_issue	Retrieve a JIRA issue by its key.	issueId
find_jira_ticket	Search for JIRA issues using a JQL query.	jql_query
create_jira_issue	Create a new JIRA issue.	projectKey, summary, issueTypeId, assigneeId
add_jira_comment	Add a comment to an existing JIRA issue.	issueId, comment
assign_jira_issue	Assign an issue to a user.	issueId, accountId

Sources: src/llm/agent-evals/jira-agent/test-data.ts

Okta Integration

The Okta agent provides extensive tools for identity and access management. It includes specific prompts to guide the LLM in tool selection and response formatting.

Tool Name	Description	Key Parameters
list_okta_users	List users in Okta, with filtering.	limit, search
create_okta_user	Create a new user in Okta.	profile (firstName, lastName, email)
assign_user_to_okta_group	Assign a user to a group.	groupId, userId
suspend_okta_user	Suspend a user in Okta.	userId
list_okta_applications	List applications in Okta.	limit, query

Sources: agent-packages/packages/okta/src/tools.ts

Extending the Platform

Adding a new integration follows a defined process, leveraging the modular architecture.

1. Create a Package: A new directory is created under agent-packages/packages/.
2. Implement Tools: The core logic is implemented in tools.ts, defining the functions the agent can call. This includes defining zod schemas for input validation.
3. Export Configuration: The package should export a create<IntegrationName>ToolsExport function that returns the tool configuration.
4. Build and Link: The new package is built and linked to the main application.
5. Register in Main App: The new package is imported and registered in the main application, typically by adding it to files like src/slack/views/app_home.ts and src/lib/constants.ts.

Sources: README.md:124-132, CONTRIBUTING.md