Integrations

Overview

The integrations module provides a generic configuration framework for platform-specific integrations (e.g., OBS, Discord bots). Each integration is scoped to an account with a platform identifier, a human-readable label, an enable/disable toggle, and a flexible JSONB config field for platform-specific settings.

Integrations are pre-created (typically during account setup or when a platform connection is established) and managed through update and toggle operations. There is no create or delete via the API -- lifecycle management is handled server-side.

Architecture

Dashboard UI
    |
    v
Next.js API Proxy (/api/integrations)
    |
    v
GraphQL (IntegrationQuery / IntegrationMutation)
    |
    v
db::integrations (PostgreSQL)

The config JSONB field stores platform-specific configuration. For example, an OBS integration might store WebSocket connection details, scene mappings, or source configurations. The API layer is agnostic to the config structure -- validation is handled by the consuming service.

API

GraphQL Queries

Query	Args	Returns	Permission
integrations	--	[Integration]	settings:read
integration	id: UUID	Integration?	settings:read

• integrations returns all configs for the active account, ordered by platform.
• integration returns a single config by ID, filtered by account ownership.

GraphQL Mutations

Mutation	Args	Returns	Permission
updateIntegration	input: UpdateIntegrationInput	Integration	settings:edit
toggleIntegration	id: UUID	Integration	settings:edit

• updateIntegration supports partial updates via COALESCE -- only provided fields are changed.
• toggleIntegration flips the enabled boolean without requiring the caller to know the current state.

Both mutations verify account ownership before proceeding.

GraphQL Types

type Integration {
  id: UUID!
  accountId: UUID!
  platform: String!
  label: String!
  enabled: Boolean!
  config: JSON!
  createdAt: String!
  updatedAt: String!
}

input UpdateIntegrationInput {
  id: UUID!
  label: String
  enabled: Boolean
  config: JSON
}

Permissions

Permission	Description
settings:read	View integration configurations
settings:edit	Update integration configurations

Integrations share the settings:* permission namespace. Included in: Owner, Administrator roles.

Database

Table: integration_configs

Column	Type	Description
id	UUID (PK)	Integration config ID
account_id	UUID (FK)	Owning account
platform	TEXT	Platform identifier (e.g., obs, discord)
label	TEXT	Human-readable label
enabled	BOOLEAN	Whether the integration is active
config	JSONB	Platform-specific configuration
created_at	TIMESTAMPTZ	Creation timestamp
updated_at	TIMESTAMPTZ	Last update timestamp

DB Functions

Function	Description
list_integrations	List all configs for an account, ordered by platform ASC
get_integration	Get a single config by ID
update_integration	Partial update using COALESCE for label, enabled, config
toggle_integration	Flip enabled to NOT enabled

Key Files

File	Purpose
apps/api/src/graphql/integrations.rs	GraphQL queries, mutations, input/output types
apps/api/src/db/integrations.rs	Database CRUD operations
crates/lo-auth/src/rbac.rs	Permission constants (settings:read, settings:edit)