Requirements

Documentation for Modules

Brand Registry Library - Requirements Specification

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

1. Overview

Shared brand/manufacturer registry that provides brand management to any module in the platform. Products, suppliers, warranties, or any entity that references a brand can consume this library.

1.1 Design Principles

Domain-agnostic: Brands are a shared concept, not owned by any single module.
Multi-tenant: Full isolation per tenant.
Embeddable: Provides a brand selector component that any module can embed.
Event-driven: Publishes domain events for brand changes.
Buildable: ng-packagr library for module boundary compliance.

2. Functional Requirements

2.1 Brand Entity

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier (UUID)
`tenantId`	`string`	Yes	Multi-tenant isolation
`name`	`string`	Yes	Brand display name
`slug`	`string`	Yes	URL-friendly identifier (unique per tenant)
`description`	`string`	No	Brand description
`logoId`	`string`	No	Brand logo (via `@libs-core/media`)
`website`	`string`	No	Brand website URL
`isActive`	`boolean`	Yes	Whether brand is visible (default: `true`)
`sortOrder`	`number`	No	Display order
`metadata`	`Record<string, unknown>`	No	Extensible key-value metadata
`createdAt`	`Date`	Yes	Creation timestamp
`updatedAt`	`Date`	Yes	Last update timestamp

Brand Rules:

Name uniqueness enforced per tenant
Slug auto-generated from name with uniqueness check
Deactivating a brand does not affect entities referencing it (soft reference)

3. Services

3.1 BrandService

Injectable service for programmatic access:

getAll(tenantId): Observable<Brand[]> — All active brands
getById(id): Observable<Brand> — Single brand
getBySlug(slug, tenantId): Observable<Brand> — Lookup by slug
create(brand): Observable<Brand> — Create brand
update(id, changes): Observable<Brand> — Update brand
delete(id): Observable<void> — Delete brand
search(query, tenantId): Observable<Brand[]> — Search by name

4. Integration Points

4.1 Domain Events

Event	Payload	Trigger
`brands.brand.created`	`{ brand, tenantId }`	Brand created
`brands.brand.updated`	`{ brand, changes, tenantId }`	Brand updated
`brands.brand.deleted`	`{ brandId, tenantId }`	Brand deleted

4.2 Embeddable Components

Component ID	Description	Inputs
`brands:brand-selector`	Dropdown brand picker with search	`multiSelect`, `placeholder`, `showLogo`, `allowCreate`
`brands:brand-card`	Brand display card with logo	`brandId`, `compact`

4.3 Public Actions

Action ID	Description	Parameters	Permission
`brands:get-brands`	List brands	`{ query?, pagination }`	`brands:read`
`brands:get-brand`	Get single brand	`{ brandId }`	`brands:read`
`brands:create-brand`	Create brand	`{ brand data }`	`brands:manage`

5. Permissions

Permission	Description
`brands:read`	View brands
`brands:manage`	Create/edit/delete brands

6. User Stories

US-01: As an admin, I can create and manage brands with name, logo, and description.
US-02: As a module developer, I can embed a brand selector in my module's forms.
US-03: As a module developer, I can get/create brands programmatically via services or public actions.
US-04: As a module developer, I can listen to brand events to react when brands 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.

8. Dependencies

@libs-core/brand-registry
├── @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/media               (brand logos)
├── @libs-core/action-registry     (public actions)
└── @libs-core/mock-api            (development mock data)