# WITwhat

## What This Is

WITwhat is a Windows desktop dashboard for tracking prototype-device packages distributed to testers and VIPs. It emphasizes glanceability: the user should rapidly understand shipping/return state and latest context from a card grid, with minimal clicks and instant fuzzy discovery. It integrates GitHub Project data and Shopify order/fulfillment/tracking data, while also managing WITwhat-specific fields for recipient package contents and notes.

## Core Value

From dashboard load, the user can find any recipient and confirm shipment state in under 10 seconds.

## Requirements

### Validated

- [x] User can manage WITwhat-owned package item data (non-1:1 with Shopify products), including editability. — *Validated in Phase 09: item-note-crud-wiring*

### Active

- [ ] User can view package cards sourced from GitHub Project recipient records.
- [ ] User can see Shopify order/fulfillment/tracking status on each card.
- [ ] User can use instant fuzzy search that begins when typing any letter or space.
- [ ] User can switch discovery modes (By Status Updated, By Ship Date, By Recipient, By Product Shipped) with keyboard and UI controls.
- [ ] User can view Discord identity context per recipient and quickly open DM context.
- [x] User can refresh data per-card, refresh-all, and with F5. — *Validated in Phase 10: refresh-auto-archive-wiring*
- [x] User can use archived-card filtering with default-off and automatic archive behavior for returned items, with manual override. — *Validated in Phase 10: refresh-auto-archive-wiring (archive persistence + manual-archive preservation)*
- [ ] Multiple users can share WITwhat state via a simple secure shared backend.

### Out of Scope

- Cross-platform desktop support — v1.x is Windows only.
- Full in-app Discord messaging/bot workflows — v1.x focuses on identity/avatar + DM launch.

## Current Milestone: v1.1 — Data Architecture & Product Catalog

**Goal:** Complete the data architecture vision: SQLite persistence, GH Issues cloud storage, product catalog with serial tracking, and operational features (returns, lists) — closing every gap identified in DATA-FLOW.md.

**Target features:**
- ~~v1.0 gap closure (Phase 9 item CRUD remaining, Phase 14 card layout)~~ — *Done in Phase 15*
- ~~SQLite full-mirror cache replacing in-memory Repository~~ — *Foundation in Phase 15 (SqliteStore + LiveClient wired)*
- ~~GH Issues cloud storage for cards (`ww-card`) and products (`ww-product`)~~ — *Products done in Phase 17; cards done in Phase 18 (ww-card issues, note comments, PendingEditFlusher)*
- ~~Product catalog with standalone product entities~~ — *Done in Phase 17 (SQLite + GH Issues + UI catalog)*
- ~~Serial instance tracking with lifecycle state machine~~ — *Done in Phase 17 (subissue units, inline SN input, radio-button selection)*
- ~~Deprecated field cleanup (github_profile_url, shipment on Recipient, item_summary, latest_note)~~ — *Done in Phase 15*
- Offline mode with pending edit flush-on-reconnect
- New GH Project columns (Purpose, Vision Rx, product parallel-arrays)
- Start Return feature for Shopify orders
- Lists feature with viewing mode and card management

## Context

- Data source of recipient records is GitHub Project: https://github.com/orgs/BigscreenVR/projects/11/views/19
- Recipients also map to Shopify customer profiles and related order/fulfillment state.
- WITwhat must store API credentials for GitHub and Shopify.
- Browser links should open system default browser for Shopify customer/order views.
- UX discovery model includes left-side tabs and layered views for recipient/product exploration.
- Keyboard behavior expectations:
  - Up/Down arrow cycles discovery mode.
  - Esc once returns current discovery mode to its home.
  - Esc twice returns to default discovery mode (By Status Updated).
- Auto-polling target is every 5 minutes.

## Constraints

- **Platform**: Windows desktop only — initial deployment target is single platform.
- **Tech stack**: Rust + Slint — preselected stack for frontend GUI.
- **Persistence**: Shared multi-user state with low operational complexity — prefer simple secure deployment over heavy infra.
- **Integration security**: GitHub and Shopify credentials required — must be stored and handled securely.
- **Usability**: Glanceability-first and speed-critical workflows — minimal interaction cost is required.

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Use Rust + Slint for desktop app | Existing technical preference and fit for native Windows UI | — Pending |
| Use a simple self-hosted shared service with SQLite for shared state | Better concurrency and safety than file-sync SQLite | — Pending |
| Defer Shopify write actions to v2 | Reduce v1 scope/risk while preserving core tracking value | — Pending |
| Default archive derived from `Returned` status with manual override | Keeps live views clean while preserving operator control | — Pending |

---
*Last updated: 2026-04-16 — Phase 20.5 complete: Modal State Architectural Audit — canonical MODAL-STATE.md with 9 overlay components, callback chains, state diagrams, Agent Rules (RULE-M-01 through RULE-M-04)*