Colors Module

Overview

The colors module manages product colors within FlowPOS. Colors are used to classify products by their color attribute, supporting filtering, variant definition, and catalog organization.

Colors are business-scoped: every color belongs to a specific business and is isolated from other businesses.

---

Architecture

The module follows Hexagonal Architecture with strict layer boundaries.

colors/
├── colors.module.ts                          # NestJS module wiring
├── domain/
│   └── colors-repository.domain.ts           # IColorsRepository port + injection token
├── application/
│   └── colors.service.ts                     # Use cases (CRUD)
├── infrastructure/
│   └── colors.repository.ts                  # Kysely DB adapter (implements port)
└── interfaces/
    ├── colors.controller.ts                  # HTTP adapter
    ├── dtos/
    │   ├── create-color.dto.ts
    │   └── update-color.dto.ts
    └── query/
        └── paginate-colors.query.ts

Layer responsibilities

Layer	Responsibility
domain/	Repository port (IColorsRepository) and COLORS_REPOSITORY injection token.
application/	ColorsService — orchestrates CRUD operations and pagination.
infrastructure/	ColorsRepository — Kysely queries against the color table. Implements IColorsRepository.
interfaces/	ColorsController — maps HTTP requests to service calls. Thin layer with no business logic.

Dependency rule

interfaces → application → domain ← infrastructure

---

Domain Concepts

Color

A named color with a hex value, used to classify products (especially for variant definitions like apparel).

Field	Type	Description
id	UUID	Primary key (auto-generated)
name	string	Display name (e.g. "Red", "Navy Blue")
hexValue	string	Hex color code (e.g. "#FF0000")
businessId	UUID	FK to business
isActive	boolean	Whether the color is available for use
createdBy	UUID	FK to user
updatedBy	UUID	FK to user (nullable)
createdAt	timestamptz	Auto-set on creation
updatedAt	timestamptz	Set on update

---

API Endpoints

All endpoints require Bearer token authentication and are scoped to PolicyResource.Color for RBAC.

POST /colors

Create a new color.

Body:

{
  "name": "Red",
  "hexValue": "#FF0000",
  "businessId": "<uuid>",
  "isActive": true,
  "createdBy": "<uuid>"
}

Responses: 201 Created | 400 Invalid body | 401 Unauthorized

GET /colors

List colors with pagination, search, and sorting.

Query parameters:

Param	Required	Description
businessId	No	UUID of the business (filter)
page	No	Page number (default: 1)
size	No	Page size (default: 10)
search	No	Case-insensitive search on name and hexValue
orderBy	No	Sort field (name)
order	No	asc or desc

Responses: 200 Paginated list | 401 Unauthorized

GET /colors/:id

Get a single color by UUID.

Responses: 200 Found | 404 Not found | 401 Unauthorized

PATCH /colors/:id

Partially update a color.

Body:

{
  "name": "Blue",
  "hexValue": "#0000FF",
  "updatedBy": "<uuid>"
}

Responses: 200 Updated | 400 Invalid body | 404 Not found | 401 Unauthorized

DELETE /colors/:id

Delete a color by UUID.

Responses: 200 Deleted | 404 Not found | 401 Unauthorized

---

Related Modules

• Products — products reference colorId for catalog classification
• Product Variants — colors are used as option values in variant matrices (e.g. size × color)