YapHub

Appearance

Controllers Documentation ​

This document provides comprehensive documentation for all controllers in the Yappa Knowledge Hub backend.

Overview ​

The backend has 8 controllers that handle different aspects of the application:

  1. KnowledgeController - Main knowledge CRUD with Notion sync
  2. LocalKnowledgeController - SQLite-only read operations
  3. CategoryController - Category management with auto-sync
  4. SummaryController - AI summary management
  5. NotionSyncController - Manual sync operations
  6. NotionWebhookController - Notion webhook handling
  7. DigestController - Digest generation
  8. NotionDigestController - Notion digest operations

KnowledgeController ​

Route Prefix: /api/knowledge

Description: Main controller for knowledge item CRUD operations. All operations sync with Notion API.

Dependencies:

  • NotionKnowledgeService - Notion API operations
  • NotionCategoryService - Category lookups
  • NotionSyncService - Dual-storage sync
  • OpenAiService - AI summaries (optional)

KnowledgeController Endpoints ​

Create a new knowledge item in both SQLite and Notion.

Request Body:

json
{
  "title": "How to Deploy Symfony Apps",
  "content": "Detailed deployment guide...",
  "tags": ["symfony", "deployment", "devops"],
  "category": "notion-page-id-here",
  "categoryId": "notion-page-id-here",
  "targetGroups": ["developers", "devops"],
  "status": "Not started",
  "url": "https://example.com/article",
  "userId": "U12345",
  "sourceMessage": {
    "ts": "1234567890.123456",
    "channel": "C12345"
  }
}

Response (201 Created):

json
{
  "id": "notion-page-id",
  "notionId": "notion-page-id",
  "notionUrl": "https://notion.so/...",
  "title": "How to Deploy Symfony Apps",
  "content": "Detailed deployment guide...",
  "tags": ["symfony", "deployment", "devops"],
  "targetGroups": ["developers", "devops"],
  "status": "Not started",
  "sourceUrl": "https://example.com/article",
  "aiSummary": "",
  "created": "2026-02-19T10:30:00.000Z",
  "lastEdited": "2026-02-19T10:30:00.000Z",
  "categoryId": ["notion-page-id-here"]
}

Notes:

  • If targetGroups is not provided, it inherits from the category's default target groups
  • Accepts category, category_id, or categoryId (all map to the same field)
  • Creates in both SQLite and Notion for dual persistence

GET /api/knowledge ​

List all knowledge items or search/filter.

Query Parameters:

  • search (string, optional) - Full-text search query
  • category (string, optional) - Filter by category ID

Examples:

bash
# List all
GET /api/knowledge

# Search
GET /api/knowledge?search=symfony

# Filter by category
GET /api/knowledge?category=notion-category-id

Response (200 OK):

json