# Phase 1: Foundation and Shared State - Context

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

<domain>
## Phase Boundary

Deliver secure credential handling, shared persistence baseline, and core recipient model for multi-user operation on a Windows-first local development baseline. This phase defines operational behavior and data boundaries, not advanced sync logic or dashboard UX.

</domain>

<decisions>
## Implementation Decisions

### Credential setup and secret handling
- Credentials are configured manually via config file (no in-app setup UI in Phase 1).
- Credential types: GitHub OAuth credentials and Shopify admin token.
- Validation is format-only during entry/save; live API verification happens later during sync flows.

### Shared service multi-client contract
- Clients connect over localhost HTTP API.
- Service auto-starts when the first client launches.
- Client behavior on service issues: retry for a bounded window, then enter degraded mode with stale reads.
- Write conflict policy uses optimistic concurrency with version checks.

### Recipient/package model and normalization
- Canonical recipient identity is an internal UUID mapped to external IDs.
- Relationship shape: recipient has many packages; package has many items.
- Partial ingest is allowed with nullable fields.
- Missing required data must be explicitly surfaced as unresolved/missing-field indicators for follow-up.
- Ownership mapping uses mixed mode: Shopify-linked mappings with manual override support.

### Windows baseline and packaging
- Phase 1 runtime expectation is packaged app workflow (not raw multi-process dev launch as default path).
- Windows 10 and Windows 11 are both supported on a best-effort basis.
- Packaging baseline artifact is an unsandboxed ZIP distribution.
- Logging includes both console output and rotating file logs.

### Claude's Discretion
- Secret storage implementation: use Windows Credential Manager when available, with encrypted local fallback when unavailable.
- Exact retry window/backoff tuning before degraded mode.
- UX shape for how missing required fields are indicated, as long as unresolved data is clearly visible.
- Rotation policy details (file count/size thresholds) for bounded log growth.

</decisions>

<specifics>
## Specific Ideas

No style references were requested; user priority was concrete operational behavior and bounded log growth.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 01-foundation-and-shared-state*
*Context gathered: 2026-02-27*