Integration Patterns and Architecture

Promptless integrations follow consistent patterns and architectural principles that make them powerful, secure, and easy to use together. This guide explains the common patterns across all integrations to help you understand how they work and how to get the most out of them.

Three-Tier Integration Architecture

All Promptless integrations are designed around a three-tier architecture that separates concerns and enables flexible workflows:

1. Triggers

Purpose: Generate events that notify Promptless to take action

How it works: Trigger integrations monitor for specific events and automatically or manually initiate documentation workflows.

Trigger integrations include:

GitHub: Pull request creation, updates, and merges
Bitbucket: Pull request events and repository changes
Slack: @Promptless mentions and "Update Docs" message actions
Zendesk: Resolved support tickets that indicate documentation gaps

2. Context Research

Purpose: Provide additional information to enrich documentation generation

How it works: Context integrations allow Promptless to search for relevant information during the documentation creation process.

Context integrations include:

GitHub: Code functionality, repository structure, and commit history
Linear: Project management data, issue details, and team context

3. Publishing

Purpose: Deliver completed documentation to your chosen platforms

How it works: Publishing integrations push approved documentation updates to your content management systems.

Publishing integrations include:

GitHub: Documentation repositories and wikis
Zendesk: Help Center articles and knowledge base
Webflow: CMS content and blog posts (Beta)
Intercom: Help center documentation (Beta)

Common Authentication Patterns

Promptless uses industry-standard authentication methods across all integrations to ensure security and reliability:

OAuth 2.0 Authentication

Used by: Zendesk, Linear, Slack

Benefits:

Secure token-based authentication
Granular permission scopes
Easy access revocation
Regular token rotation for enhanced security

GitHub App Authentication

Used by: GitHub

Benefits:

JWT-based secure authentication
Organization-level installation control
Granular repository access management
Built-in security and compliance features

App Password Authentication

Used by: Bitbucket

Benefits:

Username and app password combination
Specific permission scoping (Read, Read/Write)
Easy credential management

Universal Setup Workflow

All integrations follow a consistent setup pattern that makes them predictable and easy to configure:

Step 1: Connect Integration

Navigate to the integrations page
Click "Connect [Integration Name]"
Complete the authentication flow
Verify the connection status

Step 2: Configure Project

Go to the projects page
Create a new project or edit an existing one
Select your trigger sources
Configure context research integrations
Choose publishing destinations

Step 3: Fine-tune Settings

Most integrations offer additional configuration options:

Directory-specific triggers: Monitor only specific folders or file paths
Team-level permissions: Control which teams or repositories are accessible
Notification settings: Configure how and when you're notified of updates

Permission and Access Patterns

Promptless follows the principle of least privilege across all integrations:

Read-Only Access

Used for: Trigger repositories, context research

Purpose: Monitor for changes and gather information without modifying source data

Read-Write Access

Used for: Documentation repositories, publishing destinations

Purpose: Create and update documentation content

Granular Controls

All integrations provide granular permission controls:

Repository-level: Choose specific repositories for access
Team-level: Select which teams can be accessed for context
Directory-level: Monitor only specific folders or paths
Action-level: Control what actions Promptless can perform

Data Flow and Processing Patterns

Event Processing Flow

Trigger Detection: Integration detects relevant event
Context Gathering: Promptless researches additional information
Content Generation: AI creates documentation suggestions
Review Process: Human review and approval
Publishing: Approved content pushed to destinations

Multi-Integration Workflows

Integrations work together seamlessly:

GitHub PR → Linear Context → GitHub Docs: Code changes trigger documentation updates with project context
Slack Discussion → Zendesk Publishing: Team conversations become help center articles
Zendesk Tickets → Multiple Publishing: Support patterns inform documentation across platforms

Security and Compliance Features

All integrations include consistent security features:

Data Protection

Encryption in Transit: TLS 1.2+ for all data transmission
Encryption at Rest: AES-256 for stored data
Minimal Data Retention: Only necessary data is stored
Regular Security Audits: Ongoing security assessments

Access Controls

Audit Logging: Complete activity tracking
Access Revocation: Immediate access removal capabilities
Permission Scoping: Granular control over integration capabilities
Regular Token Rotation: Automatic security credential updates

Troubleshooting Common Patterns

Connection Issues

Symptoms: Integration shows as disconnected or authentication fails

Solutions:

Check organization/workspace permissions
Verify token hasn't expired
Reinstall integration if permissions have changed
Contact support if issues persist

Permission Problems

Symptoms: Cannot access repositories, teams, or resources

Solutions:

Review integration permissions in source platform
Update repository or team access settings
Refresh integration connection
Verify project configuration matches available resources

Trigger Not Working

Symptoms: Expected events don't trigger documentation updates

Solutions:

Check directory-specific trigger settings
Verify webhook configurations
Review project trigger settings
Test with manual triggers where available

Best Practices for Integration Management

Setup Best Practices

Start Small: Begin with one trigger and one publishing destination
Test Thoroughly: Use manual triggers to verify setup before automation
Document Configuration: Keep track of which integrations serve which purposes
Regular Reviews: Periodically audit integration permissions and usage

Security Best Practices

Principle of Least Privilege: Grant only necessary permissions
Regular Access Reviews: Audit integration access quarterly
Monitor Activity: Review audit logs for unusual activity
Prompt Updates: Address security notifications immediately

Workflow Optimization

Use Directory Triggers: Focus on relevant code changes
Combine Context Sources: Use multiple integrations for richer documentation
Standardize Publishing: Maintain consistent documentation formats
Monitor Performance: Track documentation update frequency and quality

Getting Help

If you need assistance with integrations:

Documentation: Check individual integration guides for specific details
Support: Contact help@gopromptless.ai for technical assistance
Feature Requests: Request new integrations or features via support
Beta Access: Contact support for access to beta integrations

For the most up-to-date list of available integrations and their current status, visit the integrations page in your Promptless dashboard.