Purchase Order V1 Decisions
Design decisions for the Purchase Order V1 project (MVP2 task 13). Tracks scoping, Kanban card lifecycle, architectural patterns, and open questions from the initial design round.
Decision Table
Section titled “Decision Table”| # | Question | Status | Decision | Round |
|---|---|---|---|---|
| DQ-001 | Design scope strategy | Decided | Full scope design; simplified spec as descope floor | R1 |
| DQ-002 | Kanban card state transitions for PO lifecycle | Decided | Three-step: REQUESTING → REQUESTED → IN_PROCESS → FULFILLED | R1 |
| DQ-003 | READY / FULFILLING state activation | Decided | Continue bypass; reserved for Loops | R1 |
| DQ-004 | ”Order and Release” shortcut | Decided | Support REQUESTED → FULFILLED skip-receiving path | R1 |
| DQ-005 | PO-to-card transition mechanism | Decided | Implicit batch via PO actions, not per-card explicit | R1 |
| DQ-006 | Update propagation vs update on read | Decided | Adopt update propagation pattern | R1 |
| DQ-007 | Document service behavior | Decided | Documint default; same as card/label printing | R1 |
| DQ-008 | Clipboard timing | Decided | Copy on click; confirm on successful generation | R1 |
| DQ-009 | Email template ownership | Decided | Fixed template until tenant settings exist | R1 |
| DQ-010 | PO Number generation | Open | R1 | |
| DQ-011 | Snapshot vs live sync | Open | R1 | |
| DQ-012 | Card exclusion from PO draft | Open | R1 | |
| DQ-013 | Order quantities, units, and editability | Open | R1 | |
| DQ-014 | Vendor typeahead source | Open | R1 | |
| DQ-015 | PO persistence strategy | Open | R1 |
Round 1 Decisions
Section titled “Round 1 Decisions”DQ-001: Design Scope Strategy
Section titled “DQ-001: Design Scope Strategy”Context: The PM’s Simplified PO Spec V1 targets a narrow “generate PDF from Order Queue” workflow. The existing backend and technical spec design a full PO lifecycle. These scopes need to be reconciled.
| Option | Description |
|---|---|
| A | Design for full scope; use simplified spec as descope floor |
| B | Design only to the simplified spec |
Decision: Option A. Complete the design for full PO scope (create, approve/submit, receive) to estimate remaining work. Use the Simplified PO Spec V1 as the floor for descoping to bring the release date earlier.
DQ-002: Kanban Card State Transitions for PO Lifecycle
Section titled “DQ-002: Kanban Card State Transitions for PO Lifecycle”Context: The PO lifecycle must drive Kanban Card state transitions. The Demo202509 workflow defines per-card explicit transitions; PO V1 needs to map these to PO-level actions.
| Option | Description |
|---|---|
| A | Three-step: create PO (accept), submit PO (start-processing), receive (receive) |
| B | Two-step: create+submit combined, receive |
Decision: Option A. The three confirmed transitions are:
- Create PO / add cards →
accept→REQUESTING→REQUESTED - Submit PO →
start-processing→REQUESTED→IN_PROCESS - Receive →
receive→IN_PROCESS→FULFILLED
DQ-003: READY / FULFILLING State Activation
Section titled “DQ-003: READY / FULFILLING State Activation”Context: The full Kanban model has IN_PROCESS → READY → FULFILLING → FULFILLED. MVP0/MVP1 bypass READY and FULFILLING. Should PO V1 activate them?
Decision: Option A (continue bypass). PO V1 changes the procurement process, not the card lifecycle. READY and FULFILLING are reserved for the future Loops feature.
DQ-004: “Order and Release” Shortcut
Section titled “DQ-004: “Order and Release” Shortcut”Context: Demo202509 supports a 3-ALT flow where “Order and Release” skips the receiving step (REQUESTED → FULFILLED). Should PO V1 have an equivalent?
Decision: Option A. PO V1 must support a “Submit and Release” action that transitions cards directly from REQUESTED to FULFILLED. Maintains parity with the existing Demo202509 workflow.
DQ-005: PO-to-Card Transition Mechanism
Section titled “DQ-005: PO-to-Card Transition Mechanism”Context: Demo202509 uses explicit per-card actions. PO V1 introduces the Purchase Order as a grouping mechanism. How should card transitions fire?
Decision: Option A (implicit batch). PO actions batch card state transitions across all cards associated with PO lines. The PO is the unit of work for the Procurement Manager.
DQ-006: Update Propagation vs Update on Read
Section titled “DQ-006: Update Propagation vs Update on Read”Context: The current PO backend uses “update on read” patterns, which has made lookup logic overly complicated. The Item/ItemSupply/Supplier chain already implements a cleaner “update propagation” pattern via observer notifications.
Decision: Option A. PO V1 must adopt the update propagation pattern. Aligns with the established codebase pattern and produces cleaner reads.
DQ-007: Document Service Behavior
Section titled “DQ-007: Document Service Behavior”Context: How should the generated PO PDF be delivered to the user?
Decision: Option A. Use Documint default behavior — open PDF the same way card and label printing works. Reuses existing infrastructure with no new dependencies.
DQ-008: Clipboard Timing
Section titled “DQ-008: Clipboard Timing”Context: When should the email body be copied to the clipboard relative to PDF generation?
Decision: Option A. Copy email body on click; show confirmation prompt on successful PDF generation. Better UX — the user can start composing the email while the PDF is generating.
DQ-009: Email Template Ownership
Section titled “DQ-009: Email Template Ownership”Context: Should the email body template be configurable per organization?
Decision: Option A (fixed template). Defer configurability until tenant settings infrastructure exists. Sufficient for V1.
Open Questions (Round 1)
Section titled “Open Questions (Round 1)”DQ-010: PO Number Generation
Section titled “DQ-010: PO Number Generation”Preliminary direction: User-entered initially; auto-generated once POs are persisted.
Options: User-entered, auto-generated by backend, or auto-generated with user override.
DQ-011: Snapshot vs Live Sync
Section titled “DQ-011: Snapshot vs Live Sync”Preliminary direction: Option A — snapshot on open; validate at submit time; refresh cards on error; preserve user header edits.
Context: What happens if the Order Queue changes while the PO side panel is open.
DQ-012: Card Exclusion from PO Draft
Section titled “DQ-012: Card Exclusion from PO Draft”Preliminary direction: Option A — select in Order Queue before opening panel; allow removal of lines in panel before submitting.
DQ-013: Order Quantities, Units, and Editability
Section titled “DQ-013: Order Quantities, Units, and Editability”Open: Needs clarification on whether PO line quantity comes from ItemSupply order quantity or aggregated card reorder quantities, and whether the user can override.
DQ-014: Vendor Typeahead Source
Section titled “DQ-014: Vendor Typeahead Source”Preliminary direction: Vendor is determined by Order Queue group (read-only on PO for V1). “Compatible vendor” query is deferred.
DQ-015: PO Persistence Strategy
Section titled “DQ-015: PO Persistence Strategy”Preliminary direction: Export-only as descope floor; full persistence as the design target.
Options: Full persistence (use existing backend), export-only (PDF generation, no backend persistence), or minimal persistence (save PO record on generate without full CRUD UI).
Copyright: © Arda Systems 2025-2026, All rights reserved