YapHub

Appearance

Category Management Services ​

Last Updated: 2026-03-09 Version: 2.0 (Consolidated)

The category services manage the organizational hierarchy of the Knowledge Hub. They handle both the direct persistence to SQLite and the high-level business rules for "Thematic Lists".

🏛️ Service Layering ​

🛠️ CategoryService ​

Our low-level data accessor.

  • Responsibility: Fetching active categories, finding items by Notion ID, and managing direct repository interactions.
  • Key Pattern: Returns Category entities or throws CategoryNotFoundException.

👔 CategoryManagementService ​

The high-level business logic orchestrator.

  • Responsibility: Validating category names, managing sort orders, and enforcing deletion rules.
  • Business Rule: A category cannot be deleted if it contains active knowledge items.

⚖️ Core Business Logic ​

Audience Inheritance ​

When a new Knowledge item is created without explicit role names, the CategoryManagementService provides the "Target Roles" from the parent category as the default.

Activation Logic ​

Deactivating a category (isActive = false) does not delete data but hides the category from the Slack UI and excludes it from automatic sync routines. This preserves historical associations for existing knowledge items.

Sort Management ​

Categories are displayed in Slack based on a sortOrder. The management service provides a reorderCategories method that takes an array of IDs and updates the sequence in a single transaction.

🔄 Integration Points ​

  • Notion: Synced via NotionSyncService. Local changes aren't pushed automatically; they wait for the next sync cycle unless explicitly triggered.
  • Knowledge: Category items are the "One" side of a OneToMany relationship with Knowledge items.

Technical Details ​

  • Namespace: App\Service\Category
  • Location: src/Service/Category/

TIP

Use CategoryService::findActive() to populate dropdown menus or Slack Home views, as it handles the sorting logic automatically.