---
phase: 13-data-flow-architecture-document
plan: 01
subsystem: documentation
tags: [data-flow, architecture, data-dictionary, agent-rules, sqlite, github-issues, shopify]

requires:
  - phase: 12.1.1-shopify-first-card-source-pipeline
    provides: Shopify-first sync pipeline (run_sync_cycle, unassigned cards, recipient matching) that this document describes

provides:
  - Authoritative data flow reference (.planning/DATA-FLOW.md) covering all four data layers
  - AGENT RULES section with RULE-01 through RULE-08 (prohibitions and mandatories)
  - CLAUDE.md enforcement blurb with mandatory read and update obligation

affects:
  - All future phases touching data structs, sync logic, or storage
  - SQLite implementation phase (Layer 3/4 schema)
  - GH Issues cloud persistence phase (ww-card, ww-product)
  - Product catalog and serial instance tracking phases

tech-stack:
  added: []
  patterns:
    - "RULE-NN format for prescriptive agent rules (Status / Background / Action)"
    - "Layered reference document style: field tables + ASCII diagrams + prescriptive rules"
    - "Parallel-array GH Project column encoding for product data per recipient"

key-files:
  created:
    - .planning/DATA-FLOW.md
    - CLAUDE.md
  modified: []

key-decisions:
  - "DATA-FLOW.md is the single source of truth for data architecture; all future agents must read it before touching data"
  - "github_profile_url is PROHIBITED (RULE-01) — does not exist as a GH Project column, present only as technical debt"
  - "shipment_status / tracking_state belong on Cards not Recipients (RULE-02) — current Recipient fields are migration debt"
  - "Cards exist only from Shopify orders (RULE-04) — GH-only recipients do not produce cards"
  - "GH Issues (ww-card, ww-product in BigscreenVR/beyond-outgoing) are the cloud of record (RULE-05)"
  - "recipient_id and recipient_key are currently the same field; SQLite will introduce a true UUID PK alongside the human-readable key"
  - "SQLite target schema uses nine normalized tables with FK constraints, not JSON blobs"
  - "Offline mode: full read/write against local SQLite cache; pending_edits table queues writes for flush on reconnect"

patterns-established:
  - "AGENT RULES section at document top with numbered RULE-NN format for high-visibility prescriptive constraints"
  - "Update obligation: DATA-FLOW.md must be updated in the same commit as data architecture changes"

requirements-completed: []

duration: 4min
completed: 2026-03-22
---

# Phase 13 Plan 01: Data Flow Architecture Document Summary

**Authoritative DATA-FLOW.md covering all four data layers (Recipients, Cards, Products, Serial Instances) with RULE-01 through RULE-08 prohibitions, ASCII flow diagrams, SQLite target schema, and CLAUDE.md enforcement blurb.**

## Performance

- **Duration:** 4 min
- **Started:** 2026-03-22T09:45:46Z
- **Completed:** 2026-03-22T09:50:04Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments
- Created `.planning/DATA-FLOW.md` (811 lines) as a professional, authoritative layered reference covering all data entities in the app
- Documented eight AGENT RULES with PROHIBITED/MANDATORY/DEPRECATED status, explicit background context, and binding action requirements — prominently placed at document top
- Added CLAUDE.md enforcement section with mandatory read and update obligation for all data-touching work

## Task Commits

Each task was committed atomically:

1. **Task 1: Write DATA-FLOW.md authoritative reference document** - `5df751a` (feat)
2. **Task 2: Add DATA-FLOW.md enforcement blurb to CLAUDE.md** - `11aeab1` (feat)

**Plan metadata:** (docs commit — created below)

## Files Created/Modified
- `.planning/DATA-FLOW.md` - 811-line authoritative data flow reference (four layers, AGENT RULES, SQL schema, transformation pipeline, sync pipeline, ASCII diagrams)
- `CLAUDE.md` - Added Data Architecture enforcement section with mandatory read/update obligation

## Decisions Made
- AGENT RULES section placed at document top (before layer docs) so agents cannot miss prohibitions
- RULE-NN format uses Status/Background/Action fields for machine-parseable and scannable rule definitions
- Open questions documented as OQ-01/OQ-02/OQ-03 for items that remain TBD (serial instance storage location, recipient_key naming, GH Issue body format)
- Deprecated fields consolidated in a single table with replacement guidance rather than scattered inline
- Both descriptive (current state) and prescriptive (target architecture) documented explicitly for each layer

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- DATA-FLOW.md is ready as a reference for all future phases
- SQLite implementation phase can use the documented schema as the starting point for table creation
- GH Issues persistence phase can use the ww-card / ww-product structure documented here
- Product catalog and serial instance tracking phases have clear field definitions and lifecycle documented

---
*Phase: 13-data-flow-architecture-document*
*Completed: 2026-03-22*