# Phase 19: Reference Item Model & Tags Schema - 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-04-05
**Phase:** 19-reference-item-model-tags-schema
**Areas discussed:** Reference item structure, Merged data strategy, Tag data model, Migration path
**Mode:** Auto (--auto flag) — all areas selected, recommended defaults chosen

---

## Reference Item Structure

| Option | Description | Selected |
|--------|-------------|----------|
| Add globalItemId to items, remove itemGlobalLinks | Direct FK on items table, drop junction table | ✓ |
| Keep itemGlobalLinks alongside globalItemId | Both mechanisms coexist | |
| Keep only itemGlobalLinks | No schema change to items | |

**User's choice:** Add globalItemId to items, remove itemGlobalLinks
**Notes:** [auto] 1:1 relationship doesn't need a junction table. Direct FK is simpler. Migration moves existing link data first.

---

## Merged Data Strategy

| Option | Description | Selected |
|--------|-------------|----------|
| Same Item shape — services merge transparently | Client sees one type, services handle joins | ✓ |
| Separate ReferenceItem type | Different response shape for reference items | |
| Client-side merge | API returns raw, client resolves | |

**User's choice:** Same Item shape — services merge transparently
**Notes:** [auto] No client-side changes needed for existing views. Service layer joins global data when globalItemId is set.

---

## Tag Data Model

| Option | Description | Selected |
|--------|-------------|----------|
| Separate tables, flat | tags + global_item_tags tables, no type column | ✓ |
| Separate tables, typed | tags + global_item_tags, tags have type column | |
| JSON column on globalItems | tags as JSON array, no separate tables | |

**User's choice:** Separate tables, flat
**Notes:** [auto] Proper querying, many-to-many, type categorization can be added later.

---

## Migration Path

| Option | Description | Selected |
|--------|-------------|----------|
| Migrate links, keep old data as fallback | Set globalItemId from links, don't null out item fields | ✓ |
| Migrate links, null out duplicated fields | Clean break, reference items have no local data | |
| No migration, only new items use references | Existing items stay as copies forever | |

**User's choice:** Migrate links, keep old data as fallback
**Notes:** [auto] Safe transition — old data remains as fallback while service layer prefers global data.

---

## Claude's Discretion

- Seed tag list content
- SQL migration ordering
- MCP tool updates timing
- Tag filtering logic (AND vs OR)

## Deferred Ideas

- Catalog submission system (admin review workflow)
- Price intelligence aggregation
- Weight intelligence aggregation
- Admin tag management UI
- Tag type categorization
- Personal weight override
