# Phase 2: External Sync Integrations - Context

**Gathered:** 2026-02-27
**Status:** Ready for planning

<domain>
## Phase Boundary

Sync recipient and shipment data from GitHub Project and Shopify with reliable polling, retry/backoff, and recoverable partial failures. This phase establishes ingestion, linkage, merge, and sync-status behavior; it does not expand archive lifecycle workflows or add new manual override feature surfaces beyond conflict signaling.

</domain>

<decisions>
## Implementation Decisions

### GitHub ingestion scope and mapping
- Source target is configurable project + view.
- Ingestion runs full refresh each poll, then computes local change diffs.
- Phase 2 maps identity and shipment-relevant operational fields (not generic mirror-all).
- Records with missing/invalid required mapped fields are skipped with warning logs.

### Shopify linkage and fulfillment data strategy
- Primary linkage should use Shopify profile URL stored in GitHub Project when available.
- Orders are filtered by configured tags/status before projection.
- Recipients with no Shopify match remain in shared state with null Shopify fields.
- Shipment truth comes from Shopify fulfillment status plus tracking events.

### Polling, retries, and stale-data signaling
- Polling interval is adaptive (not fixed 5-minute cadence).
- Retry policy uses exponential backoff within cycle, then rolls remaining failure into next adaptive cycle.
- Partial failure behavior applies successful provider updates while preserving stale data for the failed provider.
- UI exposes persistent sync status indicator without timestamp display.
- Staleness warning appears only when data exceeds 12 hours old.

### Merge and conflict policy
- Field precedence defaults: GitHub wins identity fields; Shopify wins commerce/shipment fields.
- Merge persists the merged result and stores conflict notes for diagnostics.
- Manual overrides persist until explicitly cleared.
- Discrepancies should be visibly indicated to users (warning styling + explanatory tooltip).
- Merge atomicity is per-recipient (independent recipient-level merges).

### Claude's Discretion
- Exact adaptive polling algorithm and interval bounds.
- Backoff parameters (initial delay, multiplier, max delay, max attempts).
- Conflict-note schema and storage shape.
- Specific UI affordance details for discrepancy indication while preserving requested warning/tooltip behavior.

</decisions>

<specifics>
## Specific Ideas

- Shopify profile URL in GitHub is the preferred linkage anchor where present.
- Sync status should stay visible but avoid timestamp noise; only stale over-12-hour states should warn.
- Persistent manual overrides should encourage source-of-truth correction by making discrepancies explicit.

</specifics>

<deferred>
## Deferred Ideas

- Auto-archive cards when order state is `Returned` (archive lifecycle behavior belongs to Phase 7 scope).
- Manual tracking-status override workflow as a standalone capability beyond Phase 2 requirement boundary.

</deferred>

---

*Phase: 02-external-sync-integrations*
*Context gathered: 2026-02-27*