Parameters Catalog

Overview

The parameters-catalog module is a configuration registry that defines reusable parameter definitions (metadata) for the entire FlowPOS system. Each parameter defines a configuration slot — its code, data type, entity scope, allowed values, and defaults — that can later be assigned concrete values via the companion entity-parameters module.

Parameters can be global (businessId = null) or business-scoped (tied to a specific business). They are consumed by modules such as cash register sessions, restaurant kitchen stations, and print job settings to drive dynamic behavior.

---

Domain Concepts

Concept	Description
ParameterCatalog	A parameter definition record: code, name, description, data type, entity type, allowed values, and default value.
Code	Unique uppercase identifier (e.g. SERVICE_BOOKING_ENABLED, CASH_REGISTER_PIN_REQUIRED). Pattern: ^[A-Z][A-Z0-9_]+$.
Data type	One of: string, number, boolean, enum, json, date. Determines how the parameter value is validated and rendered in the UI.
Entity type	The kind of entity this parameter applies to: business, location, product, service, customer, supplier, user, sale, purchase, materialConsumption, generic.
Global parameter	businessId = null. Available to all businesses. Typically seeded via migrations.
Business-scoped parameter	businessId set. Only visible to that business.
Entity parameter	A separate module (entity-parameters) stores the actual values assigned to specific entities. The catalog defines what can be configured; entity parameters store what is configured.

---

Architecture

The module follows strict Hexagonal Architecture:

interfaces/            ← HTTP adapter (controller, DTOs, query)
application/           ← Use cases (service)
domain/                ← Port interface + injection token (framework-agnostic)
infrastructure/        ← Kysely repository (DB adapter)

Dependency flow

ParametersCatalogController
        ↓
ParametersCatalogService
        ↓  (injected via PARAMETERS_CATALOG_REPOSITORY token)
IParametersCatalogRepository  ←  ParametersCatalogRepository (Kysely)

The service depends on the IParametersCatalogRepository interface (domain port), not the concrete Kysely implementation. The binding is configured in ParametersCatalogModule using a NestJS custom provider with the PARAMETERS_CATALOG_REPOSITORY symbol token.

Key design decisions

• Interface-based injection — The service is decoupled from Kysely via @Inject(PARAMETERS_CATALOG_REPOSITORY).
• Sortable keys in domain — sortableParameterCatalogKeys is defined in the domain layer, not the interface layer, to keep the dependency direction clean.
• Audit fields from auth token — updatedBy is resolved from the bearer token via the @UserId() decorator on PATCH, not accepted in the request body.
• Enum validation — dataType and entityType are validated against known values using @IsIn().
• Code pattern enforcement — The code field requires uppercase letters, digits, and underscores only.

---

Main Use Cases

List parameters (paginated)

GET /parameters-catalog?size=10&page=1&search=BOOKING&orderBy=name&order=asc

Returns a paginated list with text search across code, name, description, dataType, and entityType.

Create a parameter

POST /parameters-catalog

{
  "code": "SERVICE_BOOKING_ENABLED",
  "name": "Service Booking Enabled",
  "description": "Enables the ability to create service bookings for this business.",
  "dataType": "boolean",
  "entityType": "business",
  "isActive": true,
  "isRequired": false,
  "defaultValue": { "value": false }
}

Get parameter by ID

GET /parameters-catalog/:id

Returns 404 if not found.

Update a parameter

PATCH /parameters-catalog/:id

{
  "description": "Updated description.",
  "isActive": false
}

The updatedBy field is set automatically from the authenticated user.

Delete a parameter

DELETE /parameters-catalog/:id

Returns 204 No Content on success.

---

API Endpoints

Method	Path	Description	Status Codes
POST	/parameters-catalog	Create a parameter catalog entry	201, 400, 401
GET	/parameters-catalog	List parameters (paginated)	200, 401
GET	/parameters-catalog/:id	Get parameter by ID	200, 401, 404
PATCH	/parameters-catalog/:id	Update parameter	200, 400, 401
DELETE	/parameters-catalog/:id	Delete parameter	204, 401

All endpoints require Bearer token authentication.

---

Seeded Parameters

Parameters are seeded via database migrations. Key examples:

Code	Data Type	Entity Type	Purpose
SERVICE_BOOKING_ENABLED	boolean	business	Enable/disable service booking
SERVICE_BOOKING_REQUIRED	boolean	business	Require booking before service
ASSIGN_CUSTOMER_FROM_BOOKING_PLATFORM	boolean	business	Auto-assign customer from booking platform
CASH_REGISTER_*	various	business	Cash register behavior settings
RESTAURANT_SEND_MODE	enum	business	Restaurant order send mode
LOYALTY_* / STORE_CREDIT_*	various	business	Loyalty and store credit configuration
BARCODE_SCAN_INPUT	boolean	business	Barcode scanner input mode

See packages/backend/database/src/migrations/ for the full list of seeded parameters.

---

Related Modules

Module	Relationship
entity-parameters	Stores the actual parameter values assigned to specific entities
cash-register	Reads cash register parameters via cash-register-settings.service.ts
restaurant	Reads kitchen station and print job parameters

---

File Structure

apps/backend/src/parameters-catalog/
├── parameters-catalog.module.ts
├── application/
│   └── parameters-catalog.service.ts
├── domain/
│   └── parameters-catalog-repository.domain.ts
├── infrastructure/
│   └── parameters-catalog.repository.ts
└── interfaces/
    ├── parameters-catalog.controller.ts
    ├── dtos/
    │   ├── create-parameter-catalog.dto.ts
    │   ├── update-parameter-catalog.dto.ts
    │   └── parameter-catalog-response.dto.ts
    └── query/
        └── paginate-parameters-catalog.query.ts