# Phase 10: PAX8 Client & Auth Foundation - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-07-10
**Phase:** 10-pax8-client-auth-foundation
**Areas discussed:** Orders/invoices granularity

---

## Gray areas presented (multiSelect)

| Area | Description | Selected |
|------|-------------|----------|
| Match/review table shape | Model on `device_link_review` (candidate array + confidences) vs. simpler single-best-guess + status enum | |
| Product catalog scope | Full PAX8 catalog vs. lazily populated from referenced subscriptions only | |
| Orders/invoices granularity | Line-item grain with header+items tables vs. flat single table | ✓ |
| Raw payload retention | JSONB safety-net column per row vs. fully typed columns only | |

**User selected:** Orders/invoices granularity only. The other three were left to the planner's discretion (see CONTEXT.md "Claude's Discretion").

---

## Orders/Invoices Granularity

### Q1 — Grain

| Option | Description | Selected |
|--------|-------------|----------|
| Two tables (header + line items) | `pax8_orders` (order id, company, order date, total, status) + `pax8_order_items` (order_id FK, product/SKU, quantity, unit price, line total). Matches PAX8's own order shape. | ✓ |
| One flat table | `pax8_order_items` only, order-level fields repeated per line. Simpler queries, no natural home for order status/totals. | |

**User's choice:** Two tables (header + line items)

### Q2 — Backfill window

| Option | Description | Selected |
|--------|-------------|----------|
| Full history, no bound | Pull everything on first sync, no lookback-window column needed. | ✓ |
| Bounded lookback window | e.g. last 24 months; requires a config value and sync logic to respect it. | |

**User's choice:** Full history, no bound

### Q3 — Raw JSON safety net

| Option | Description | Selected |
|--------|-------------|----------|
| Yes, keep raw_payload JSONB | Typed columns for used fields + raw_payload JSONB per row for anything not yet modeled. | ✓ |
| No, typed columns only | Fully committed to normalized columns per PROJECT.md's "avoid PAX8-API-shaped blobs" guidance. | |

**User's choice:** Yes, keep raw_payload JSONB

### Q4 — Currency handling

| Option | Description | Selected |
|--------|-------------|----------|
| NUMERIC amount + currency code column | `NUMERIC(12,2)` + `CHAR(3) DEFAULT 'USD'` on orders and line items. | ✓ |
| USD-only, no currency column | `NUMERIC(12,2)` only, assume USD everywhere. | |

**User's choice:** NUMERIC amount + currency code column

**Notes:** No additional follow-up questions requested — user moved straight to wrap-up after the 4 questions.

---

## Claude's Discretion

- Company match/review table shape — follow `device_link_review` (migration 080) as the closest precedent, adapted for PAX8 company → Autotask company matching.
- Product catalog scope (full vs. lazy/referenced-only) — deferred to Phase 11's sync-service design; schema should not preclude either approach.
- Raw payload retention on `pax8_companies` / `pax8_subscriptions` / `pax8_products` — reasonable to apply the same JSONB safety-net pattern established for orders (D-03), for consistency, unless the planner has a specific reason not to.

## Deferred Ideas

None — discussion stayed within Phase 10's boundary. Company matching logic (Phase 12), product catalog population (Phase 11), the `/pax8` UI (Phase 14), and scheduler wiring (Phase 13) are already sequenced elsewhere in ROADMAP.md/REQUIREMENTS.md.
