Goal: Connect Item.Supply to Business Affiliate References

Connect the ItemSupply components that populate primarySupply and secondarySupply on the Item entity to real suppliers represented in the BusinessAffiliate module, so that supplies reference actual supplier records rather than free-standing data. The work is scoped to the API / backend services layer in operations; front-end design and implementation are tracked by separate tickets. The project is design-first: assess the current state, produce a design (use cases, Item↔BusinessAffiliate interaction, and the cross-module information model in the Reference domain), decide two refactorings, then implement.

Linear Tickets

• PDEV-731 — Connect Item.Supply to Business Affiliate References: At the API/backend layer, connect ItemSupply (primarySupply / secondarySupply) to BusinessAffiliate supplier references; assess, design, decide refactorings, implement, and cover with unit + API tests.
• Parent: PDEV-182 — Reference / Supplier Management.
• Related: PDEV-829 — Phase 4: Supply Unification (connecting Items, Vendors, and POs).
• Blocks: PDEV-764 — Unhide /vendors once upstream typeahead + AG Grid PRs merge.

Repositories

Repository	Role	Planned Changes
operations	Backend service (Kotlin/Ktor/Exposed)	Connect ItemSupply to BusinessAffiliate references; possible ItemSupply service extraction; canonical reference-data routes; unit tests.
documentation	Doc site (Astro Starlight)	Design documentation in current-system; this project’s roadmap docs and decision log.
api-test	API tests (Bruno)	API-level tests exercising the use cases.
workbooks	Obsidian vault	Assessment and design research notes (working material, not a formal deliverable).

Success Criteria

1. Current state of the Item and BusinessAffiliate modules is assessed across code, documentation, and api-tests.
2. A design is produced covering the enumerated use cases, the Item↔BusinessAffiliate sequence interactions, and the cross-module information model in the Reference domain.
3. The two refactoring decisions are made and recorded: (a) separate ItemSupply service within the Item module; (b) canonical reference-data URL routes for Item and BusinessAffiliate.
4. Design is implemented in operations with unit tests covering all use cases; ./gradlew build passes.
5. Design is documented in current-system in the documentation repo.
6. API tests in api-test demonstrate the use cases at the API level and pass.

Context

The Item entity carries primarySupply and secondarySupply of type ItemSupply. An initial Item↔BusinessAffiliate linkage already exists in operations (a supplierEId, the ItemVendorResolver, qualifier modes, and VENDOR name-change propagation), so this project is a redesign rather than a greenfield connection: it replaces that ad-hoc link with a canonical SupplierReference to the VENDOR BusinessRole and adds the missing reaction to supplier removal (UC 5). See design.md for the full assessment. It is Phase-4 adjacent work (PDEV-829, Supply Unification) and unblocks the /vendors front-end surface (PDEV-764).

Scope

In Scope

• Assessment of Item + BusinessAffiliate modules (code, docs, api-tests).
• Design artifacts: use cases, sequence diagrams, cross-module information model.
• Refactoring decisions: ItemSupply service extraction; reference-data canonical routes.
• Backend implementation in operations + unit tests.
• API tests in api-test.
• Design documentation in documentation/current-system.

Use Cases to Design / Implement

1. Add primary and secondary supplies to an item on creation — (a) with an existing supplier; (b) without an existing supplier (create on-the-fly).
2. Edit primary/secondary supplies for an existing item — (a) assign a pre-existing supply; (b) create a new supply with a pre-existing supplier; (c) create a new supply with no pre-existing supplier.
3. List all supplies associated with an item.
4. Remove a supply associated with an item — (a) when it is not a primary/secondary supply; (b) when it is a primary/secondary supply.
5. Remove a supplier from the system — notifications emitted and the Item module’s reaction.

Out of Scope

• Front-end design and implementation (tracked by separate tickets, e.g. PDEV-764).

Constraints

1. API / backend services layer only.
2. Cross-Universe rule: no foreign keys or shared transactions across services; BusinessAffiliate references follow the reference pattern.
3. Follow Arda Kotlin conventions (Result/AppError, Exposed, smart constructors) and the bitemporal table conventions.
4. CHANGELOG entry required on every PR per repo’s model.

Deliverables

#	Deliverable	Location
1	Design document	documentation/.../current-system/
2	Decision log (refactoring decisions)	this project’s roadmap directory
3	Backend implementation + unit tests	operations
4	API tests	api-test
5	Research/assessment notes	workbooks

Reference Documents

• PDEV-731 — source ticket.
• complex-project-definition-and-planning skill — design + decision-log workflow used for this project.
• information-model-design skill — entity/reference/persistence design conventions.

---

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