Knowledge Base System - Integration Documentation

​

Version History

​

File Naming

​

Document Structure

1. Overview
2. Integration Patterns
3. Event Contracts
4. API Contracts
5. Platform Integration Layer
6. Error Handling
7. Security Considerations
8. Performance Considerations
9. Testing Requirements
10. Future Enhancements
11. References

​

Cross-References

• Spec: specs/pf/specs/PF-61-knowledge-base-system.md (v1.0.0)
• PF-60 Spec: specs/pf/specs/PF-60-rag-infrastructure.md (v1.0.0)
• PF-11 Spec: specs/pf/specs/PF-11-document-management.md (v1.0.0)
• Event Contracts: docs/architecture/integrations/EVENT_CONTRACTS.md (v1.0.0)
• API Contracts: docs/architecture/integrations/API_CONTRACTS.md (v1.0.0)
• Integration Matrix: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md (v1.0.0)

​

Quick Reference

​

Decision Trees

​

Should I use PF-61 Knowledge Base?

​

Pattern Library

​

Event Publishing Pattern

// Event payload contains organization_id and user_id for tenant isolation
interface KnowledgeArticlePublishedPayload {
  event_type: 'knowledge_article_published';
  organization_id: uuid; // Required for tenant isolation
  article_id: uuid;
  timestamp: timestamptz;
  user_id: uuid; // Required for user-initiated events
}

// Consumers fetch details under RLS with organization_id filter
const article = await supabase
  .from('pf_knowledge_base')
  .select('*')
  .eq('id', payload.article_id)
  .eq('organization_id', payload.organization_id) // Enforce tenant isolation
  .single();

​

Common Mistakes

​

Pre-Flight Checklist

• Verify PF-60 (RAG Infrastructure) is available
• Verify PF-11 (Document Management) is available
• Review event contracts for correct payload structure
• Ensure RLS policies are in place
• Test event publishing and consumption

​

Overview

​

Integration Patterns

​

Pattern 1: Platform Integration Layer

• Location: /src/platform/documents/
• Usage: Document import feature
• Public API: Document selection and text extraction
• Status: 📝 Planned

​

Pattern 2: Event-Based Integration

• Events Published: knowledge_article_published, knowledge_article_unpublished
• Channel: domain_events
• Status: 📝 Planned

​

Direct Dependency

• Usage: Stores embeddings in pf_document_embeddings table
• Edge Function: generate-embeddings for embedding generation
• Status: 📝 Planned

• Usage: Permission keys pf.knowledge.view and pf.knowledge.manage
• Status: 📝 Planned

​

Event Contracts

​

Event: knowledge_article_published

​

Purpose

​

Trigger Conditions

• Article status changes from draft or in_review to published via UPDATE
• Note: Event only fires on UPDATE operations when status changes to published. The trigger is defined as AFTER UPDATE only. Consumers must fetch article details (title, tags, category) under RLS using article_id.

​

Payload Schema

interface KnowledgeArticlePublishedPayload {
  event_type: 'knowledge_article_published';
  organization_id: uuid; // Required for tenant isolation
  article_id: uuid;
  timestamp: timestamptz;
  user_id: uuid; // Required for user-initiated events
}

​

Implementation

CREATE OR REPLACE FUNCTION pf_publish_knowledge_article_published()
RETURNS TRIGGER AS $$
BEGIN
  IF NEW.status = 'published' AND (OLD.status IS NULL OR OLD.status != 'published') THEN
    PERFORM pg_notify('domain_events', json_build_object(
      'event_type', 'knowledge_article_published',
      'article_id', NEW.id,
      'timestamp', now()
    )::text);
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = public;

CREATE TRIGGER trigger_knowledge_article_published
AFTER UPDATE ON pf_knowledge_base
FOR EACH ROW
WHEN (OLD.status IS DISTINCT FROM NEW.status AND NEW.status = 'published')
EXECUTE FUNCTION pf_publish_knowledge_article_published();

​

Consumer Actions

​

Testing Requirements

• Event payload structure validation
• Event fires on publish
• Correct organization_id included
• PF-60 handles event correctly

​

Event: knowledge_article_unpublished

​

Purpose

​

Trigger Conditions

• Article status changes from published to draft, in_review, or archived via UPDATE
• Note: Event only fires on UPDATE operations when status changes from published. The trigger is defined as AFTER UPDATE only. Consumers must fetch article details under RLS using article_id.

​

Payload Schema

interface KnowledgeArticleUnpublishedPayload {
  event_type: 'knowledge_article_unpublished';
  organization_id: uuid; // Required for tenant isolation
  article_id: uuid;
  timestamp: timestamptz;
  user_id: uuid; // Required for user-initiated events
}

​

Implementation

CREATE OR REPLACE FUNCTION pf_publish_knowledge_article_unpublished()
RETURNS TRIGGER AS $$
BEGIN
  IF NEW.status != 'published' AND OLD.status = 'published' THEN
    PERFORM pg_notify('domain_events', json_build_object(
      'event_type', 'knowledge_article_unpublished',
      'article_id', NEW.id,
      'timestamp', now()
    )::text);
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = public;

CREATE TRIGGER trigger_knowledge_article_unpublished
AFTER UPDATE ON pf_knowledge_base
FOR EACH ROW
WHEN (OLD.status = 'published' AND NEW.status != 'published')
EXECUTE FUNCTION pf_publish_knowledge_article_unpublished();

​

Consumer Actions

​

Testing Requirements

• Event payload structure validation
• Event fires on unpublish
• Correct organization_id included
• PF-60 handles event correctly

​

API Contracts

​

Database Function: Embedding Generation

​

Function Signature

pf_knowledge_base_embedding_trigger()
RETURNS TRIGGER

​

Purpose

​

Request Schema

• Trigger fires automatically on INSERT/UPDATE when article status changes to published
• Trigger context provides: NEW.id, NEW.organization_id, NEW.title, NEW.content, NEW.published_at

{
  article_id: uuid;
  title: string;
  content: string;
  publish_timestamp: timestamptz;
  metadata: {
    organization_id: uuid;
    category?: string;
  };
}

​

Response Schema

{
  success: true;
  embedding_id: uuid;
  status: 'indexed';
  chunks_processed: number;
}

{
  success: false;
  error: string;
  status: 'failed';
}

​

Fallback Queue Message Schema

{
  source_type: 'knowledge_article';
  source_id: uuid;
  organization_id: uuid;
  content: string;
  metadata: {
    title: string;
    category?: string;
    publish_timestamp: timestamptz;
  };
}

​

Failure Contract

• Article remains published but is_indexed is set to false
• Error details stored in pf_knowledge_base.indexing_error (if column exists)
• Retry mechanism available (manual or automatic after 5 minutes)

​

Implementation Notes

• Uses net.http_post extension to call /functions/v1/generate-embeddings edge function
• Falls back to queue-based approach if extension not available
• Sets is_indexed: false if embedding generation fails
• All requests include organization_id for tenant isolation

​

Platform Integration Layer

​

PF-11 (Document Management) Integration

• useDocuments() - List documents
• useDocument(id) - Get document details
• extractDocumentText(documentId) - Extract text content

import { useDocuments } from '@/platform/documents';

function DocumentImportDialog() {
  const { data: documents } = useDocuments();
  // Select document and extract text
}

​

Error Handling

​

Embedding Generation Failures

• Article is marked as published but is_indexed: false
• Warning shown to admin
• Retry mechanism available (manual or automatic after 5 minutes)
• Error logged for debugging

​

Document Import Failures

• Show clear error message to user
• Allow manual text entry as fallback
• Log error for debugging

​

Security Considerations

​

Multi-Tenant Isolation

• All events include organization_id for tenant isolation
• RLS policies enforce organization boundaries
• Event payloads validated for organization context

​

PHI/PII Handling

• No PHI/PII in event payloads (only IDs)
• Knowledge content may contain sensitive info, but events only include metadata
• Access controls same as source documents

​

Performance Considerations

​

Event Processing

• Events are asynchronous (non-blocking)
• Embedding generation happens in background
• No impact on article publish performance

​

API Calls

• Document import uses existing PF-11 APIs
• No additional API overhead
• Caching used where appropriate

​

Testing Requirements

​

Integration Tests

• Event publishing on article publish
• Event publishing on article unpublish
• PF-60 receives and processes events
• Document import flow
• Embedding generation flow

​

RLS Tests

• Events include correct organization_id
• Cross-organization event isolation
• Permission checks for event triggers

​

Future Enhancements

​

Queue-Based Embedding Generation

• Create pf_embedding_queue table
• Background job processes queue
• Better reliability and retry handling

​

Event Versioning

• Support event schema versioning
• Backward compatibility for event consumers

​

References

• Spec: specs/pf/specs/PF-61-knowledge-base-system.md
• PF-60 Spec: specs/pf/specs/PF-60-rag-infrastructure.md
• PF-11 Spec: specs/pf/specs/PF-11-document-management.md
• Event Contracts: docs/architecture/integrations/EVENT_CONTRACTS.md
• Integration Matrix: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md

​

PF-61-EN-01 — Organization Profile Knowledge Article and Guided Seeding