Project Plan: Item Identifiers

Overview

Implements standard identifiers, additional QR codes, and labels on Item, plus the fuzzy /lookup and exact /by-code endpoints. See the Design for architecture and the Decision Log for decisions; Round 2 DQs must be resolved (or explicitly deferred) before Phase 1 starts. Backend phases are sequential; the frontend phase can run in parallel with Phase 2 once the API contract in the design is frozen.

Repositories

Repository	Role	Branch
operations	upstream (API provider)	jmpicnic/item-identifiers/operations
arda-frontend-app	downstream (BFF consumer)	jmpicnic/item-identifiers/frontend
documentation	project docs + byproducts	jmpicnic/item-identifiers/docs

There is no build-time dependency between operations and arda-frontend-app (HTTP contract only) and no common-module change (per DQ-013 recommendation), so no composite builds or version catalog updates are expected.

Task Execution Protocol (applies to every code task)

1. Red — write the task’s tests first; they compile and fail.
2. Green — implement until the task’s tests pass.
3. Verify — escalate per the verification cadence: compile → targeted test roots → full gate only at phase exit.
4. Commit — one self-contained, reviewable commit per task on the repo’s project branch.

Phases

Phase 1: Backend Domain and Persistence (operations)

Entry criteria: All Round 2 DQs Decided or Deferred — satisfied 2026-07-22 (all 16 decided).

#	Task	Repository	Depends On	Acceptance Criteria
T-01	Identifier value classes (Upc, Ean, Gtin, Isbn, Asin — no naked String) + ItemIdentifiers value object	operations	—	Unit tests: valid/invalid shapes per identifier kind (ISBN-10 and ISBN-13 both accepted); blank→null normalization in the raw-string factory; validating serializers reject malformed wire values; Result error channel (DQ-014)
T-02	CodeCandidates expansion utility	operations	—	Unit tests: 8/12/13/14-digit families, ASIN/QR verbatim, ISBN 10↔13 conversion incl. 979… one-directionality (DQ-006/DQ-010)
T-03	Item, Entity, ItemSerializer, ItemInput field additions	operations	T-01	Serialization round-trip tests incl. empty/populated lists; validate() enforces config-driven bounds: labels ≤128, QRs ≤64, ≤256 chars/entry, dedupe, order preserved (DQ-015)
T-04	Persistence: ItemIdentifiersComponent, jsonb columns, fillPayload	operations	T-03	Record round-trip integration test; legacy rows read with empty lists
T-05	Migrations V024 (columns + generated search_text incl. left(notes, 256) per DQ-009) and V025 (+.sql.conf, concurrent indexes)	operations	T-04	ContainerizedPostgres migration test: columns, generated values, all indexes present
T-06	Phase gate: item module test roots green	operations	T-01..T-05	Full item-module test run passes

Exit criteria: operations builds; item module tests green; migration verified on a clean container.

Phase 2: Backend Search Endpoints (operations)

Entry criteria: Phase 1 exit.

#	Task	Repository	Depends On	Acceptance Criteria
T-07	ItemUniverse.lookupPage (fuzzy predicate, ranking per DQ-011, Query composition, cursors) + ItemService.lookupItems (transaction boundary)	operations	T-06	Integration tests: match on name/identifier/label, ranking, filter composition, tenant isolation, effective-as-of; service test: universe called inside inTransaction(db)
T-08	ItemUniverse.byCode (candidate-set predicate) + jsonb containment operator + ItemService.findByCode (CodeCandidates expansion, DQ-012 result cap, transaction boundary)	operations	T-06	Integration tests: normalized-family hits, QR exact containment, tenant isolation; service tests: expansion in service (not endpoint), cap applied
T-09	ItemEndpoint routes: POST /lookup, GET /lookup/{page}, /by-code (per DQ-012) — request validation + response formatting only, delegating to ItemService	operations	T-07, T-08	Route tests: 200 happy paths, 400 blank param, auth failures; no business logic in the endpoint
T-10	Bruno API tests for the three routes	operations (api-tests/)	T-09	Suite green against local cluster per run-operations-api-test
T-11	Performance verification per DQ-016	operations	T-09	EXPLAIN-based test asserts index usage (no seq scan); checked-in seeding script makes the 50k-item benchmark repeatable; results recorded in byproducts

Exit criteria: full operations gate green (build, all tests); API tests pass locally.

Phase 3: Frontend BFF and Types (arda-frontend-app)

Entry criteria: Design § API Contract frozen (Round 2 DQs resolved). May run in parallel with Phase 2.

#	Task	Repository	Depends On	Acceptance Criteria
T-12	Unified identifier validators src/lib/shared/identifiers.ts (port prototype UPC/EAN/ISBN-10; add GTIN-14, ISBN-13, ASIN)	arda-frontend-app	—	Jest parity tests mirroring backend accept/reject sets
T-13	Types + mappers: arda-api.ts, items.ts, ardaMappers.ts	arda-frontend-app	—	Type-check green; mapper round-trip tests
T-14	BFF routes POST /api/arda/items/lookup, GET /api/arda/items/by-code	arda-frontend-app	T-13	Route tests with MSW upstream: envelope, auth, error mapping
T-15	SSRM accessors for identifiers, QRs, labels in filteringProperties.ts	arda-frontend-app	T-13	filterEngine tests: free-text token matches the new fields (DQ-008)
T-16	Phase gate: lint, typecheck, full Jest suite	arda-frontend-app	T-12..T-15	Repo pre-push gate green

Exit criteria: frontend gate green; no UI component changes in the diff (phase-2 boundary).

Phase 4: Documentation Byproducts (documentation)

Entry criteria: Phases 2 and 3 exit (content reflects final implementation).

#	Task	Repository	Depends On	Acceptance Criteria
T-17	Update item module reference (current-system/functional/reference-data/item/) with new fields + endpoints	documentation	T-09	Page reflects shipped contract; make pr-checks green
T-18	Update domain model (domain/information-model/assets/items.md) with the three new attributes	documentation	T-03	Entity table updated; links resolve

Exit criteria: make pr-checks green in the documentation worktree.

Phase 5: Release

Entry criteria: Phases 2–4 exit.

Per-repository lifecycle (CHANGELOG → gate → PR → steward → merge), in dependency order. operations merges and deploys first; the frontend PR notes the dependency and merges after the backend endpoints are live in dev; documentation last.

#	Task	Repository	Depends On	Acceptance Criteria
T-19	CHANGELOG entry under [Unreleased] — Added (minor; internal refactors under Fixed)	operations	T-11	CLQ validation passes
T-20	Pre-push guard + gate: staged-diff scan (no local overrides, no absolute paths), full build/test, push, feat: PR with attribution block; changelog listed largest-impact first	operations	T-19	PR open, CI green
T-21	Steward operations PR (pr-steward): checks, review threads; merge only on user direction	operations	T-20	PR merged; release tagged
T-22	CHANGELOG per repo’s current model (direct-edit vs PR-body — verify at PR time, repo is migrating), gate, push, feat: PR with dependency note on the operations release	arda-frontend-app	T-16, T-21	PR open, CI green, dependency note present
T-23	Steward frontend PR; merge after operations endpoints deployed to dev	arda-frontend-app	T-22	PR merged
T-24	Documentation PR: PR-body ## CHANGELOG, make pr-checks, project docs status frontmatter set to completed (documents stay in place), then worktree/branch cleanup for all three repos	documentation	T-17, T-18, T-23	PR merged; worktrees removed with no uncommitted work

Exit criteria: all three PRs merged; worktrees and local branches removed; project docs marked completed.

Dependency Graph

The graph shows the coarse phase ordering: backend phases are sequential, the frontend phase starts from the frozen API contract and can overlap Phase 2, and documentation and release close the project in dependency order.

Personas

Persona	Working Directory	Agent Name Pattern
Back-end engineer	projects/item-identifiers-worktrees/operations	be-item-identifiers
Front-end engineer	projects/item-identifiers-worktrees/arda-frontend-app	fe-item-identifiers
Technical writer	projects/item-identifiers-worktrees/documentation	tw-item-identifiers

Single-agent-per-repo, sequential within each repo; no integration branch (one project branch per repo, as in the manufacturer-field project).

Worktree Strategy

Worktree	Branch	Cleanup
projects/item-identifiers-worktrees/operations	jmpicnic/item-identifiers/operations	after T-21
projects/item-identifiers-worktrees/arda-frontend-app	jmpicnic/item-identifiers/frontend	after T-23
projects/item-identifiers-worktrees/documentation	jmpicnic/item-identifiers/docs	after T-24
projects/item-identifiers-worktrees/prototype-scan-to-item	symlink (read-only reference)	remove symlink at close

Push guards (every push): stage narrowly (never git add -A); scan the staged diff for includeBuild, absolute /Users/ paths, and -worktrees references; run the repo’s full local gate first. Before removing any worktree: verify no uncommitted changes and all branches pushed.

References

• Design — architecture and API contract
• Decision Log — DQ-001..DQ-016
• Goal — scope statement

---

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved