PSA/ee/docs/plans/2026-03-13-quoting-system/PRD.md

PRD — Quoting System

• Slug: quoting-system
• Date: 2026-03-13
• Status: Draft

Summary

Add a quoting system to Alga PSA that allows MSPs to create, send, and manage pricing proposals for clients. Quotes integrate with the existing billing infrastructure (service catalog, tax, discounts, templates, PDF generation, email, client portal) and can be converted into contracts and/or invoices upon acceptance.

Problem

Alga PSA has no way to create pre-sale pricing proposals. MSPs currently must:

• Create quotes outside the system (spreadsheets, Word docs, other tools)
• Manually re-enter accepted quote data as contracts and invoices
• Lose visibility into quote status, history, and conversion metrics
• Cannot offer clients a self-service experience for reviewing and accepting proposals

This creates data entry duplication, disconnected workflows, and lost context between the sales and billing stages.

Goals

• Create quotes with line items from the service catalog (all billing methods: fixed, hourly, usage, per_unit)
• Support optional line items that clients can opt-in/out of, with MSP review of client's configuration choices before conversion
• Distinguish recurring vs one-time charges for proper conversion
• Apply discounts (percentage and fixed) at line and quote level
• Calculate tax using existing tax infrastructure
• Version/revise quotes without losing history
• Track quote status through its full lifecycle
• Generate professional PDF documents using quote document templates (shared AST engine, separate from business quote templates)
• Send quotes via email to multiple addresses (not just the primary contact)
• Allow clients to view, accept, and reject quotes via the client portal (accessible to all client users with billing permissions)
• Convert accepted quotes into contracts (recurring items) and/or invoices (one-time items)
• Reusable quote templates (business configuration templates) for frequent quote patterns, following the contract template pattern
• Internal approval workflow (optional, configurable per tenant)

Non-goals

• E-signatures (accept button with timestamp is sufficient)
• CRM opportunity tracking beyond a basic opportunity_id link
• Automated follow-up sequences or drip campaigns
• Quote analytics/reporting dashboards (can be built on top later)
• Multi-currency quotes in Phase 1 (use tenant default currency; multi-currency can follow invoice pattern later)

Users and Primary Flows

Persona: MSP Sales/Account Manager

1. Creates a new quote for a client, selecting services from the catalog (optionally from a quote template)
2. Adds custom line items, marks some as optional, groups by phase
3. Adjusts rates, applies discounts, reviews tax calculation
4. Previews PDF, adjusts if needed
5. Sends quote to multiple email addresses (defaults to primary contact, can add more)
6. Client accepts with optional item selections → MSP reviews configuration → converts to contract + invoice
7. If client requests changes → creates a revision (new version)

Persona: MSP Manager/Approver (Phase 6)

1. Reviews quotes submitted for internal approval
2. Approves or requests changes
3. Approved quotes become ready to send

Persona: Client (via Client Portal)

1. Any client user with billing permissions sees quotes in the billing section
2. Receives email notification with link to quote in portal
3. Views quote details, including optional items
4. Toggles optional items on/off, sees total recalculate
5. Accepts (submitting optional item selections for MSP review) or rejects with optional comment
6. Views quote history (sent quotes, accepted quotes)

UX / UI Notes

MSP Portal — Billing Dashboard

• New "Quotes" tab in billing dashboard (alongside Client Contracts, Invoicing, etc.)
• Tab added to billingTabsConfig.ts with FileText icon
• Quote list uses DataTable with columns: Quote #, Client, Title, Amount, Status, Date, Valid Until, Actions
• Filters: status, client, date range
• Sort by date, amount, status

Quote Builder (Create/Edit)

• Header section: Client picker, contact picker, title, description/scope of work, dates (quote date, valid until), PO number
• Line items section:
  • Service catalog picker (searchable dropdown)
  • Manual/custom line item entry
  • Per-item: description, quantity, unit price, optional toggle, recurring toggle + frequency
  • Phase/section grouping (text label per item)
  • Drag-to-reorder (display_order)
  • Discount lines (add discount → select type, amount, target item/service)
• Totals section: Subtotal, discounts, tax, total — recalculates on any change
• Notes section: Internal notes (not visible to client), client-facing notes
• T&C section: Terms and conditions text field
• Actions: Save Draft, Preview PDF, Send to Client, [Submit for Approval — Phase 6]

Quote Detail View

• Read-only view of quote with all sections
• Status badge with current state
• Action buttons based on status:
  • Draft: Edit, Send, Delete
  • Sent: Revise, Cancel
  • Accepted: Convert to Contract, Convert to Invoice, Convert to Both
  • Any: View PDF, View History
• Version history sidebar (if multiple versions exist)
• Activity log (audit trail)

Client Portal

• Quotes tab in billing overview (alongside Invoices)
• Quote list: Quote #, Title, Amount, Status, Date
• Quote detail: full line items, optional item toggles, totals, T&C
• Accept/Reject buttons with optional comment field
• Status shows client-friendly text ("Awaiting Your Response", "Accepted", etc.)

Requirements

Phase 1 — Data Model, Core CRUD, Line Items

P1-FR1: Database Tables

• Create quotes table with all fields (see Data Model section)
• Create quote_items table modeled on invoice_charges
• Create quote_activities table for audit trail
• All tables tenant-scoped with composite keys for Citus compatibility
• Indexes on: (tenant, client_id), (tenant, status), (tenant, quote_number), (tenant, parent_quote_id)

P1-FR2: Quote Numbering

• Add 'QUOTE' to SharedNumberingService entity types in shared/services/numberingService.ts (EntityType union)
• Seed next_number table with entity_type='QUOTE', prefix='Q-', padding_length=4
• Generate sequential numbers: Q-0001, Q-0002, etc.
• Uses existing generate_next_number DB function — no changes needed to the function itself

P1-FR3: TypeScript Types

• IQuote, IQuoteItem, IQuoteActivity interfaces in packages/types/
• QuoteStatus type union
• IQuoteWithClient, IQuoteListItem view model types

P1-FR4: Zod Schemas

• createQuoteSchema, updateQuoteSchema
• createQuoteItemSchema, updateQuoteItemSchema
• Validation for status transitions

P1-FR5: Quote Model (Data Access)

• CRUD operations with tenant-explicit Knex queries
• getById, getByNumber, listByTenant, listByClient
• create, update, delete
• Delete behavior: hard delete for drafts with no business history (no activities beyond 'created'). For quotes with business history (sent, accepted, etc.), deletion is blocked — use cancel/archive instead. Register quote entity in deleteEntityWithValidation() config with supportsArchive: true.
• Auto-expiration check: if valid_until < today and status is sent, set to expired

P1-FR6: Quote Item Model

• CRUD for line items within a quote
• listByQuoteId, create, update, delete, reorder
• Service catalog lookup on create (denormalize name, SKU, default rate)

P1-FR7: Quote Activity Model

• create activity entries on all quote state changes
• listByQuoteId for audit trail display

P1-FR8: Server Actions

• createQuote, updateQuote, getQuote, listQuotes, deleteQuote
• createQuoteFromTemplate — create a new draft quote by copying a quote template's items
• addQuoteItem, updateQuoteItem, removeQuoteItem, reorderQuoteItems
• All wrapped with withAuth(), using billing:create/billing:read/billing:update/billing:delete permissions

P1-FR9: Status Transitions

• Enforce valid transitions: draft→sent, sent→accepted/rejected/expired/cancelled, accepted→converted, any non-terminal→cancelled
• Phase 6 adds: draft→pending_approval→approved→sent

P1-FR10: Service Catalog Integration

• Pick service from catalog → populate line item with name, SKU, default rate, billing method, unit of measure
• Support rate overrides (custom pricing on the quote)
• Support all billing methods: fixed, hourly, usage, per_unit

P1-FR11: Optional Line Items

• is_optional flag on quote items
• Optional items included in totals by default but can be toggled by client (Phase 4)
• UI shows clear visual distinction for optional items

P1-FR12: Recurring/One-Time Distinction

• is_recurring + billing_frequency on quote items
• Visual grouping in UI
• Drives conversion logic in Phase 5

P1-FR13: Quote Business Templates (Reusable Configurations)

• is_template boolean field on quotes table (following contract template pattern)
• Template quotes have is_template = true, are not numbered, and don't go through the status lifecycle
• Two creation flows (matching contract template pattern):
  • Template Wizard: Multi-step guided creation (basics → services → review)
  • Quick Create: Simple form for fast template creation
• Template management UI: list, create, edit, delete templates
• "Create from Template" action: copies template's items into a new draft quote
• Templates store predefined line items, default terms, default description/scope
• Separate from PDF document templates (Phase 3) — these define what a quote contains, not how it renders

P1-FR14: Billing Dashboard Tab

• Add "Quotes" tab to billing dashboard in billingTabsConfig.ts
• Route: /msp/billing?tab=quotes

P1-FR15: Quote List UI

• DataTable component with sorting, filtering, pagination
• Columns: Quote #, Client, Title, Total Amount, Status, Quote Date, Valid Until
• Status filter dropdown: All, Drafts, Sent, Accepted, Rejected, Expired, Converted, Cancelled, Archived (archived quotes shown via filter, not a separate tab)
• Client filter
• Row click → quote detail
• Separate template list view (filtered by is_template=true)

P1-FR16: Quote Form UI

• Create/edit form with client picker, contact picker, metadata fields
• "Create from Template" option in create flow
• Line item editor with service catalog search
• Add/remove/reorder items
• Save as draft

P1-FR17: Quote Detail UI

• Read-only detail view
• Status badge
• Action buttons based on current status
• Line items display with phase grouping
• For accepted quotes with optional items: highlight client's optional item selections for MSP review

P1-FR18: Quote Status Badge

• Reusable component showing colored badge per status
• Consistent with existing status badge patterns

P1-FR19: Deletion Validation

• Register quote entity in deleteEntityWithValidation() config
• Dependencies: quote_activities (beyond 'created'), email_sending_logs, converted contracts/invoices
• supportsArchive: true — quotes with business history can be archived, not deleted
• Hard delete allowed only for drafts with no business history

Phase 2 — Tax, Discounts, Calculations, Versioning

P2-FR1: Tax Calculation

• Integrate with taxService.ts → calculateTax() per line item
• Support tax_source: internal, external, pending_external
• Per-item tax_region, tax_rate, is_taxable
• Tax exemption check via client settings
• Reverse charge support

P2-FR2: Discount Line Items

• is_discount flag creates a discount line
• discount_type: 'percentage' or 'fixed'
• discount_percentage for percentage discounts
• applies_to_item_id: scope discount to specific item
• applies_to_service_id: scope discount to specific service
• Quote-level discounts as separate line items

P2-FR3: Totals Calculation

• subtotal = sum of non-discount item totals
• discount_total = sum of discount line amounts
• tax = sum of per-item tax amounts
• total_amount = subtotal - discount_total + tax
• Recalculate on any item add/update/remove
• Optional items: included in totals unless toggled off

P2-FR4: Versioning — Create Revision

• "Revise" action on sent/rejected quotes
• Creates new quotes row: version = prev + 1, parent_quote_id = original quote_id
• Copies all quote_items to new version
• Old version status → superseded
• Same quote_number across versions (display as "Q-0042 v2")

P2-FR5: Version History

• Query all versions by parent_quote_id chain
• UI: version history sidebar/dropdown on quote detail
• Navigate between versions

P2-FR6: Totals Display in UI

• Subtotal, discounts, tax, total prominently displayed
• Live recalculation as items are edited
• Currency formatting consistent with invoice display

Phase 3 — Quote Templates & PDF Generation

P3-FR1: Quote Template Tables

• quote_templates table (parallel to invoice_templates): tenant, template_id, name, version, templateAst (JSONB), is_default, timestamps
• standard_quote_templates table: system-wide default templates
• quote_template_assignments table: tenant → template selection mapping

P3-FR2: QuoteViewModel Type

• New interface in packages/types/: quote_number, quote_date, valid_until, status, client info, contact info, tenant info, line items (with is_optional, is_recurring, phase), totals, T&C, client_notes, version
• Serves as the data contract between DB and template engine

P3-FR3: Quote-Specific AST Bindings

• Standard bindings: quoteNumber, quoteDate, validUntil, status, scope/description
• Collection bindings: lineItems (with optional/recurring flags), phases
• Totals bindings: subtotal, discountTotal, tax, total
• Additional bindings: termsAndConditions, clientNotes, version

P3-FR4: Standard Quote Templates

• standard-quote-default: Clean layout with scope section, line items table (optional items visually marked), totals, validity notice, T&C
• standard-quote-detailed: Full branding, phase grouping, recurring vs one-time sections, optional items section, acceptance instructions

P3-FR5: mapDbQuoteToViewModel Adapter

• Fetches quote + items + client + contact + tenant data
• Maps to QuoteViewModel
• Handles currency formatting, date formatting
• Marks optional items, groups by phase

P3-FR6: PDF Generation

• Reuse Puppeteer pipeline from pdfGenerationService.ts
• Create QuotePDFGenerationService or extend existing service with document type
• Flow: fetch quote → map to ViewModel → evaluate AST → render HTML → generate PDF
• Store PDF in file storage

P3-FR7: Quote Preview

• In-browser preview component (renders template without Puppeteer)
• Preview button on quote form and detail view
• Uses same AST evaluation + React rendering as invoices

P3-FR8: Template Selection

• Per-quote template override (template_id field)
• Tenant default quote template
• Fallback to standard-quote-default

Phase 4 — Email Sending & Client Portal

P4-FR1: Send Quote Action

• Server action: validate quote is in sendable state (draft or approved)
• Generate PDF
• Send email to multiple addresses (array of emails) — defaults to primary contact, supports adding additional recipients
• Set sent_at timestamp, status → sent
• Log activity

P4-FR2: Quote Email Templates

• "Quote Sent" email: subject line, quote summary, PDF attachment, link to portal
• "Quote Reminder" email: for approaching expiration
• "Quote Accepted Confirmation" email: sent to MSP when client accepts

P4-FR3: Email Logging

• Log sent emails in email_sending_logs with entity_type = 'quote'
• Track delivery status

P4-FR4: Client Portal — Quotes Tab

• Add "Quotes" tab to BillingOverview.tsx (lazy loaded)
• Accessible to all client portal users with billing permissions (not just the primary contact)
• Quote list: DataTable with Quote #, Title, Amount, Status, Date
• Filter by status

P4-FR5: Client Portal — Quote Detail

• Full quote view with line items, totals, T&C
• Optional items shown with toggle switches
• Toggling optional items recalculates totals client-side
• Optional item selections persisted server-side (per quote, per client — survives page reload)
• Client-friendly status text

P4-FR6: Client Portal — Accept/Reject

• Accept button: persists client's optional item selections, sets accepted_at, accepted_by (portal user), status → accepted
• The accept flow sends the client's configuration (selected optional items) back to the MSP for review before conversion
• MSP sees accepted quote with client's selections highlighted, then decides to convert
• Reject button: opens comment field, sets rejected_at, rejection_reason, status → rejected
• Activity logged

P4-FR7: Viewed Tracking

• Set viewed_at timestamp when client first opens quote in portal
• Activity logged
• Visible to MSP on quote detail

P4-FR8: Resend/Reminder

• "Resend" action on sent quotes
• "Send Reminder" for quotes approaching valid_until date

Phase 5 — Conversion Workflows

P5-FR1: Quote → Contract Conversion

• Action on accepted quotes
• Creates a new contract (status: draft)
• For each recurring quote_item:
  • Create contract_line matching billing method
  • Create appropriate service configuration (_fixed_config, _hourly_config, _usage_config)
  • Map service, rate, description
• Create client_contracts assignment with start_date
• Set quote.converted_contract_id
• Wrap in transaction

P5-FR2: Quote → Invoice Conversion

• Action on accepted quotes
• Creates a new invoice (status: draft, is_manual: true)
• For each one-time quote_item:
  • Create invoice_charge with matching fields
  • Copy tax, discount, pricing data
• Calculate invoice totals
• Set quote.converted_invoice_id
• Wrap in transaction

P5-FR3: Combined Conversion

• For quotes with both recurring and one-time items
• Run contract conversion for recurring items
• Run invoice conversion for one-time items
• Both in single transaction
• Set both converted_contract_id and converted_invoice_id
• Status → converted

P5-FR4: Conversion Preview

• Before converting, show preview of what will be created
• List which items → contract lines vs invoice charges
• Show contract details (name, dates, billing config)
• User confirms before proceeding

P5-FR5: Conversion UI

• "Convert" button on accepted quote detail
• Options: "To Contract", "To Invoice", "To Both" (auto-detected based on item types)
• Dialog with preview and confirmation
• Success: link to created contract/invoice

P5-FR6: Post-Conversion Links

• Quote detail shows links to converted contract/invoice
• Contract/invoice detail can link back to source quote

Phase 6 — Approval Workflow & Advanced Features

P6-FR1: Internal Approval Workflow

• New statuses: pending_approval, approved
• "Submit for Approval" action on drafts
• Approval dashboard (follow ManagerApprovalDashboard pattern)
• Approve/reject with comment
• Configurable: can be disabled per tenant (draft → sent directly)

P6-FR2: quotes:approve Permission

• New permission for approving quotes
• Separate from billing:update

P6-FR3: CRM/Opportunity Linking

• opportunity_id field on quotes (nullable)
• Link to CRM opportunity if module exists
• Display on quote detail

P6-FR4: Phase/Section Grouping UI

• Visual section headers in quote builder
• Drag items between sections
• Collapsible sections
• Phase labels in PDF template

P6-FR5: Quote Document Template Editor

• Adapt invoice template designer for quote document templates (PDF rendering templates)
• Support quote-specific nodes (optional item markers, validity, CTA)
• Custom document template creation and editing

P6-FR6: Auto-Expiration Background Job

• Scheduled job to bulk-expire quotes past valid_until
• Complements the on-access check from Phase 1
• Sends notification to quote creator

P6-FR7: Quote Duplication

• "Duplicate" action to create a new quote from an existing one (not from template, but from an actual quote)
• Copies items, resets status to draft, generates new number
• Also available: "Save as Template" to create a business template from an existing quote

Data Model

See detailed field definitions in the plan context above. Key tables:

• quotes — main entity, modeled on invoices with quote-specific fields. Includes is_template boolean for reusable business templates (following contract template pattern).
• quote_items — line items, modeled on invoice_charges with is_optional, is_recurring, phase. Includes is_selected boolean for tracking client's optional item selections.
• quote_activities — audit trail
• quote_document_templates / standard_quote_document_templates / quote_document_template_assignments — PDF rendering template storage (Phase 3). Uses shared AST engine.

Naming Clarification

• Quote templates (is_template on quotes table) = reusable business configurations with predefined line items (like contract templates)
• Quote document templates (quote_document_templates table) = PDF/HTML rendering templates using AST engine (like invoice templates)

Key Schema Decisions

• All monetary amounts as BIGINT (cents) — matches invoice pattern
• quantity as BIGINT (integer units) — matches invoice_charges post-migration
• service_item_kind column name — matches invoice_charges
• No contract_line_id on quote_items — mapping happens at conversion time
• superseded status distinct from cancelled
• viewed_at timestamp instead of viewed status (simpler state machine)
• is_selected on quote_items — tracks client's optional item choices (default true, toggled by client in portal, persisted server-side)

Testing Strategy

The project uses Vitest (v4.0.18) with three test levels. Each phase should produce tests at the appropriate level.

Test Infrastructure

• Test framework: Vitest with environment: 'node', sequential execution (maxConcurrency: 1)
• DB test context: server/test-utils/testContext.ts — TestContext class with transaction-based rollback per test
• Data factories: server/test-utils/testDataFactory.ts — createTenant(), createClient(), createUser() helpers
• DB config: .env.localtest for PostgreSQL direct connection (port 5432)
• Run commands: cd server && dotenv -e ../.env.localtest -- vitest src/test/infrastructure/billing/
• Billing package tests: packages/billing/tests/ with own vitest.config.ts (10s timeout)
• Playwright: server/playwright.config.ts, files match **/*.playwright.test.ts

Test Levels per Phase

Phase 1 — Unit + Infrastructure

• Unit (packages/billing/tests/quote/):
  • Zod schema validation (createQuoteSchema, createQuoteItemSchema, status transitions)
  • Status transition logic (allowed/rejected transitions)
  • QuoteStatusBadge component rendering
• Infrastructure (server/src/test/infrastructure/billing/quotes/):
  • Quote CRUD via model (create, read, update, delete with TestContext)
  • Quote numbering (sequential generation, tenant isolation)
  • Quote item CRUD (create with service catalog lookup, rate override, reorder)
  • Auto-expiration on read
  • Deletion validation (drafts deletable, non-drafts blocked)
  • Business template CRUD and createQuoteFromTemplate

Phase 2 — Unit + Infrastructure

• Unit:
  • Totals calculation logic (subtotal, discounts, tax, total)
  • Optional item inclusion/exclusion in totals
  • Discount amount calculation (percentage, fixed, scoped)
• Infrastructure:
  • Tax calculation integration (taxService per item, exemption, reverse charge)
  • Discount line items (applies_to_item_id, applies_to_service_id)
  • Versioning (create revision, copy items, supersede old version, version chain query)
  • Totals recalculation on item changes

Phase 3 — Unit + Infrastructure

• Unit:
  • QuoteViewModel mapping (field mapping, currency formatting)
  • AST binding resolution (quoteNumber, validUntil, lineItems collection)
  • Standard quote template AST validity (schema validation)
• Infrastructure:
  • Quote document template CRUD
  • Template selection logic (per-quote → tenant default → standard fallback)
  • PDF generation (produces valid buffer, stores in file storage)

Phase 4 — Infrastructure + Playwright

• Infrastructure:
  • Send quote action (PDF generation, email sending, status update, multi-address)
  • Email logging (entity_type='quote')
  • Client portal server actions (list quotes by client, accept, reject, viewed_at tracking)
  • Optional item selection persistence (is_selected)
• Playwright (server/src/test/e2e/quote-*.playwright.test.ts):
  • Quote list page loads with correct columns and filters
  • Quote form: create, add items, save draft
  • Client portal: view quote, toggle optional items, accept/reject

Phase 5 — Infrastructure

• Infrastructure:
  • Quote→Contract conversion (contract lines, service configs, client_contracts assignment)
  • Quote→Invoice conversion (invoice_charges, totals, is_manual=true)
  • Combined conversion (atomicity, rollback on failure)
  • Optional item exclusion from conversion (is_selected=false)
  • Post-conversion field updates (converted_contract_id, converted_invoice_id, status=converted)

Phase 6 — Unit + Infrastructure

• Unit:
  • Approval status transition validation
• Infrastructure:
  • Approval workflow (submit, approve, reject, tenant config)
  • quotes:approve permission enforcement
  • Auto-expiration background job
  • Quote duplication and save-as-template

Test File Naming Conventions

Follow existing patterns:

• Unit: packages/billing/tests/quote/<topic>.test.ts
• Infrastructure: server/src/test/infrastructure/billing/quotes/<topic>.test.ts
• Playwright: server/src/test/e2e/quote-<feature>.playwright.test.ts

Test Data Setup Pattern

// Infrastructure test example (follow existing billing test patterns)
import { TestContext } from '../../../../test-utils/testContext';

describe('Quote CRUD', () => {
  const ctx = new TestContext();

  beforeAll(async () => { await ctx.setupContext(); });
  beforeEach(async () => { await ctx.resetContext(); });
  afterEach(async () => { await ctx.rollbackContext(); });
  afterAll(async () => { await ctx.cleanupContext(); });

  it('creates a quote with generated number', async () => {
    const tenant = await ctx.createTenant();
    const client = await ctx.createClient(tenant);
    // ... test logic using ctx.knex for DB operations
  });
});

Security / Permissions

• Phase 1–5: Use existing billing:read, billing:create, billing:update, billing:delete permissions
• Phase 6: Add quotes:approve permission for internal approval workflow
• Client portal: clients can view their own quotes, accept/reject, toggle optional items
• Client portal: clients cannot edit quote content or manually change status
• All actions tenant-isolated
• Server actions use withAuth() wrapper

Rollout / Migration

• Phase 1 migration: Creates quotes, quote_items, quote_activities tables + seeds next_number for QUOTE entity type
• Phase 3 migration: Creates quote_templates, standard_quote_templates, quote_template_assignments tables + seeds standard templates
• Phase 6 migration: Adds opportunity_id to quotes if not present from Phase 1
• All migrations are additive — no changes to existing tables
• No backfill needed (new feature)
• No feature flag required — feature is additive. Tab visibility could be gated but not mandatory.

Open Questions

1. Contact handling Resolved: Single primary contact on quote. Email can be sent to any address. Portal access for all client users with billing permissions.
2. Delete behavior Resolved: Hard delete for drafts with no business history. Archive (via deleteEntityWithValidation with supportsArchive: true) for anything with history.
3. Quote business templates Resolved: Add is_template boolean to quotes table, following contract template pattern. Reusable configurations with predefined line items.
4. Optional item selections Resolved: Client selections persisted server-side (is_selected on quote_items). On accept, selections sent back to MSP for review before conversion.
5. Quote template wizard Resolved: Both — wizard for new templates + quick create for simple ones (matching contract template pattern). "Save as Template" from existing quotes in Phase 6.
6. Archived quotes visibility Resolved: Status filter dropdown in quote list includes archived. Filter options: All, Drafts, Sent, Accepted, Rejected, Expired, Converted, Cancelled, Archived.

Acceptance Criteria (Definition of Done)

Phase 1

• Database tables created with proper indexes and Citus compatibility
• Quote numbering generates sequential Q-XXXX numbers
• CRUD operations work for quotes and line items
• Service catalog items can be added as line items with rate overrides
• Optional and recurring flags function on line items
• Status transitions enforced
• Auto-expiration works on access
• Quotes tab visible in billing dashboard
• Quote list, form, and detail views functional
• Quote business templates: create, edit, delete templates
• "Create from Template" populates new draft with template's items
• Deletion validation: drafts deletable, non-drafts blocked with archive alternative

Phase 2

• Tax calculates correctly per line item using existing tax service
• Discounts (percentage and fixed) apply correctly
• Totals recalculate on any item change
• Quote versioning creates proper revision chain
• Version history navigable in UI

Phase 3

• Quote template tables created
• Standard quote templates render correctly
• PDF generation produces professional documents
• Preview works in-browser
• Template selection per quote or tenant default

Phase 4

• Quotes sent via email to any address with PDF attachment
• Client portal shows quotes tab (accessible to all users with billing permissions)
• Clients can view quote details with optional item toggles (selections persisted server-side)
• Accept sends client's optional item configuration to MSP for review
• Reject with comment works end-to-end
• Viewed tracking works

Phase 5

• Recurring items convert to contract with proper service configurations
• One-time items convert to invoice charges
• Combined conversion works atomically
• Conversion preview shows accurate mapping
• Post-conversion links work bidirectionally

Phase 6

• Approval workflow routes quotes through pending_approval → approved
• quotes:approve permission controls access
• Phase grouping renders in UI and PDF
• Quote template editor works
• Auto-expiration job runs on schedule