PSA/ee/docs/plans/2026-01-01-products/PRD.md

Products (MSP Offer Catalog) — PRD

Plan date: 2026-01-01
Owner: TBD
Status: Draft (discovery in progress)

1) Problem Statement

Alga PSA needs a first-class way for MSPs to define Products they sell to customers and then use those products consistently across:

• Contracts (recurring + one-time billing)
• Automated invoices (from billing engine)
• Manual invoices
• Tax calculation and tax reporting/export
• Accounting exports (QBO/Xero/etc.)

Today, Alga already has a Service Catalog that is used as a de-facto “sellable item” source in billing, but “Products” as a user-facing concept is not implemented end-to-end, and the billing engine’s product / license charge paths are stubbed.

2) Goals

V1 goals (no inventory)

1. Provide a Products list (CRUD) with typical product properties and multi-currency sales pricing.
2. Allow adding products to:
   • Contract templates + contracts + assigned client contracts
   • Manual invoices
3. Ensure products flow through existing pipelines:
   • Tax (internal calculation, with future external passthrough compatibility)
   • Invoice rendering (PDF/template display)
   • Accounting exports and mapping
4. Keep the model extensible to support future inventory augmentation without rewriting billing.

3) Non-Goals (V1)

• Inventory counts, stock locations/warehouses, purchase orders, receiving, costing methods (FIFO/LIFO), serial numbers.
• Quotes/estimates (unless already present elsewhere).
• Full CPQ/bundling engine (simple “bundle as a product group” can be deferred).

4) Users / Personas

• MSP Admin / Billing Admin: maintains catalog, pricing, taxability, accounting mapping.
• Sales / Ops: selects products when building contracts or invoicing.
• Finance/Accounting: relies on correct tax and export mappings.

5) Proposed Domain Model

5.1 Key design decision: “Products” vs “Service Catalog”

Observation: The current service_catalog is already the authoritative “sellable item” table for billing, taxation hooks, and accounting mapping resolution.

Decision (V1): Treat Product as a subset/view of catalog items and keep a single source of truth for sellable items.

• Implement via service_catalog.item_kind (at least: service | product) plus product fields on service_catalog (or tightly-coupled extension tables if we want to keep the base table slimmer).
• Downstream systems (contracts, invoices, accounting mapping, taxes) continue to anchor on the catalog item id (service_catalog.service_id).

5.2 Product properties (minimum)

Required:

• name
• active / availability
• sales_price (multi-currency supported; aligned with existing service pricing)

Strongly recommended:

• sku (unique per tenant; configurable requirement)
• description
• unit_of_measure (defaults to “each”)
• tax_rate_id (nullable: “non-taxable”)
• category and/or type (for filtering and mapping)
• vendor / manufacturer
• cost (non-inventory, for margin reporting)

Deferred but designed-for:

• mfr_part_number
• external_ids (for PSA/RMM/accounting integrations)

6) Integrations & System Touchpoints

6.1 Contracts

Products must be addable to:

• Contract templates (as default included products and quantities)
• Contracts (as a line’s included items)
• Client contract assignments (snapshot and per-client override)

Key behaviors:

• Quantity can be overridden at client level
• Price source hierarchy matches existing pricing rules (template → contract → schedule → client override)
• V1 starts with recurring product billing on contracts (no bill-once behavior yet)

6.2 Billing Engine

Billing engine must produce product charges as type: 'product' based on the items attached to a client contract line. Current calculateProductCharges / calculateLicenseCharges are placeholders and must be implemented or removed in favor of a unified path.

6.3 Invoices (manual + automated)

• Manual invoice item picker should allow selecting products and entering quantity/price overrides.
• Automated invoices must render products in the same pipeline as other charges, with consistent tax calculation and rounding.
• Invoice rendering/templates must display product lines clearly (and optionally distinguish product vs service for UX).

6.4 Taxes

• Product lines must be taxable/non-taxable via tax_rate_id.
• Must align with the tax “source of truth” approach (internal calc now; external passthrough possible later).

6.5 Accounting Export

Accounting export mapping should work seamlessly:

• If products remain in service_catalog, existing mapping resolution can apply.
• If a separate products entity is introduced, mapping + resolver must be extended accordingly.

6.6 Tickets, Projects, Time Entries

V1 must support attaching products to:

• Tickets (materials/parts used on a ticket) that flow into invoicing
• Projects (materials/parts used on a project) that flow into invoicing
• Time entries (see Open Question: attach products directly to time entries vs a separate “materials” record associated to the time entry)

Core requirement: these product usages must be attributable (which ticket/project/time entry) and must map to invoice items consistently (tax, currency, accounting mapping).

Decision (V1 billing path): Ticket/project materials should flow into invoicing via the billing engine, like usage/time:

• Materials become billable “charges” in billing runs (not direct invoice items at the time of entry).
• Invoice generation persists those charges into invoice items using the same tax/rounding/persistence pipeline as other charges.

7) UX / UI Notes (V1)

7.1 Navigation

• Add a Products entry under Billing (or Sales) that lands on a Product Manager.
• The UI can be implemented as a filtered view of catalog items (if using Option A) to avoid duplicating “Service Catalog” tooling.

7.2 Product Manager

• Table view: name, SKU, active, type/category, primary price, tax rate, last updated.
• Create/edit: name, description, SKU, pricing (multi-currency), tax rate.
• Fast filtering: active, category/type, search by name/SKU.

7.3 Contract & Invoice selection

• Product picker with search and keyboard-friendly UX.
• Display price in correct currency context (contract/client currency).
• Show “not priced in this currency” validation consistent with contract wizard behavior.

8) Rollout / Migration Strategy

• Add DB fields/tables behind a feature flag if needed.
• Backfill existing service_catalog entries:
  • Default item_kind to service (or map using service types/categories where possible).
  • Allow manually reclassifying into product after rollout.
• Ensure invoice rendering and accounting exports remain backwards compatible.

9) Risks & Mitigations

• Model duplication risk: creating a parallel products table can fragment pricing/tax/mapping logic. Mitigate with single catalog id.
• Billing correctness risk: product charges affect taxes, totals, and exports. Mitigate with strong integration tests.
• UX confusion risk: “Service Catalog” vs “Products” overlaps. Mitigate with clear taxonomy and filtered views.

10) Open Questions (need your answers)

Resolved:

1. Products are a subset/view of Service Catalog (single catalog id).
2. Licenses need term/period semantics; V1 can implement this as product properties (optionally still emitting type: 'license' charges where appropriate).
3. Contracts: recurring only for V1.
4. V1 product fields: SKU, cost, vendor/manufacturer, category/type, tax rate. GL/account mapping should piggyback on existing service mapping.
5. Price overrides are allowed; no audit trail requirement yet.
6. No line-level discounts for V1.
7. Products must be usable on contracts + invoices + tickets + projects + time entries.

Still open: 8. Time-entry support: V1 starts with products/materials on tickets and projects only; model uses a separate “materials” record (not attached directly to time entries). 9. Ticket/project product usages: auto-bill for V1 (no approval workflow). 10. License semantics: V1 starts with term metadata only (no start/end dates, no proration rules).

11) Definition of Done (V1)

• Admin can CRUD products with multi-currency pricing and tax configuration.
• Products can be added to contracts and manual invoices.
• Automated billing produces product line items correctly (quantity, pricing, taxes).
• Invoice PDFs/templates render products correctly.
• Accounting exports include product lines with correct mapping and tax behavior.
• Automated tests cover core flows and edge cases (taxable vs non-taxable, missing currency price, overrides).