Taxonomy Library - Requirements Specification

Library: @libs-core/taxonomy Location: libs/core/taxonomy/ Type: Core infrastructure library (not a business module) Permission Namespace: taxonomy:*

1. Overview

Generic, reusable classification system that provides hierarchical categories and flexible tags to any module in the platform. Not tied to any specific domain — products, documents, tickets, knowledge articles, or any future entity can use taxonomy for organization.

1.1 Design Principles

• Domain-agnostic: No knowledge of what entities use it. Works via entityType discriminator.
• Multi-tenant: Full isolation per tenant.
• Embeddable: Provides UI components that any module can embed (category tree, tag selector).
• Event-driven: Publishes domain events for category/tag changes so consumers can react.
• Buildable: ng-packagr library for module boundary compliance (same as workflow-engine, media).

2. Functional Requirements

2.1 Category Entity

Category Rules:

• Unlimited nesting depth
• Materialized path pattern for efficient ancestor/descendant querying
• Moving a category updates all descendant paths atomically
• scope isolates category trees — product categories are completely separate from document categories
• Slug uniqueness enforced per scope + tenantId + parentId
• Cannot delete a category that has children (must move/delete children first)

2.2 Tag Entity

Tag Rules:

• Flat structure (no hierarchy)
• scope: 'global' tags are available to all entity types
• Tags can be created on-the-fly when assigning to entities (auto-create)
• Tag name uniqueness enforced per scope + tenantId

3. Services

3.1 TaxonomyCategoryService

Injectable service for programmatic access to categories:

• getTree(scope, tenantId, rootId?): Observable<CategoryTreeNode[]> — Full tree or subtree
• getById(id): Observable<Category> — Single category
• getBySlug(scope, slug, tenantId): Observable<Category> — Lookup by slug
• getChildren(parentId): Observable<Category[]> — Direct children
• getAncestors(categoryId): Observable<Category[]> — Path from root to category
• create(category): Observable<Category> — Create category
• update(id, changes): Observable<Category> — Update category
• move(id, newParentId): Observable<Category> — Move to new parent (updates path)
• delete(id): Observable<void> — Delete (fails if has children)
• search(scope, query, tenantId): Observable<Category[]> — Search by name

3.2 TaxonomyTagService

Injectable service for programmatic access to tags:

• getAll(scope, tenantId): Observable<Tag[]> — All tags for scope
• getById(id): Observable<Tag> — Single tag
• getOrCreate(scope, name, tenantId): Observable<Tag> — Find by name or create
• create(tag): Observable<Tag> — Create tag
• update(id, changes): Observable<Tag> — Update tag
• delete(id): Observable<void> — Delete tag
• search(scope, query, tenantId): Observable<Tag[]> — Search by name
• incrementUsage(tagId): Observable<void> — Increment usage counter
• decrementUsage(tagId): Observable<void> — Decrement usage counter

4. Integration Points

4.1 Domain Events

4.2 Embeddable Components

4.3 Public Actions

5. Permissions

6. User Stories

• US-01: As an admin, I can create a hierarchical category tree scoped to a specific entity type.
• US-02: As an admin, I can move a category to a different parent, with all descendants updating automatically.
• US-03: As an admin, I can create and manage tags scoped to a specific entity type.
• US-04: As a module developer, I can embed a category tree picker in my module's forms.
• US-05: As a module developer, I can embed a tag input with autocomplete in my module's forms.
• US-06: As a module developer, I can get/create categories and tags programmatically via services or public actions.
• US-07: As a module developer, I can listen to taxonomy events to react when categories or tags change.

7. Non-Functional Requirements

• NF-01: Buildable library (ng-packagr) for module boundary compliance.
• NF-02: All components standalone with OnPush change detection.
• NF-03: Multi-tenant isolation on all entities.
• NF-04: Full mock API for development.
• NF-05: Minimum 90% test coverage.
• NF-06: Category tree operations must handle deep hierarchies efficiently (materialized path).

8. Dependencies

@libs-core/taxonomy
├── @libs-core/event-system        (domain events)
├── @libs-core/security            (permissions, tenant context)
├── @libs-core/log-system          (logging)
├── @libs-core/utilities           (string utils, slug generation)
├── @libs-core/shared-models       (BaseEntity, pagination, API types)
├── @libs-core/ui-framework        (UI components for embeddables)
├── @libs-core/action-registry     (public actions)
└── @libs-core/mock-api            (development mock data)