# Phase Handover — 12.1 Digital Menu Catalog

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | hospitality-12.1 |
| Title | Digital Menu Catalog |
| Status | Complete |
| Service(s) | hospitality |
| Version | 0.12.1.0 |
| Date | 2026-07-25 |
| ADR(s) | ADR-017 (no new ADR — catalog depth within Hospitality boundary) |

## Summary

Phase 12.1 deepened the **Torbat Food** digital menu catalog on `hospitality-service` / `hospitality_db` (port **8009**, version **0.12.1.0**). Additive migration `0002_phase_121_digital_menu_catalog` added catalog tables and MenuItem enrichment fields. **No POS / kitchen / QR ordering / reservation engines.**

## What Changed

| Area | Change |
| --- | --- |
| Models | `app/models/catalog.py` + MenuItem additive columns |
| Migration | Alembic `0002_phase_121_digital_menu_catalog` |
| APIs | Allergens, modifiers, availability, media refs, localizations |
| Events / Permissions | Catalog `hospitality.*` types and trees |
| Capabilities | `phase: 12.1`, `digital_menu_catalog: true` |
| Tests | `test_catalog.py` + updated architecture/migration/docs/API |

## Public APIs

| Method | Path | Notes |
| --- | --- | --- |
| POST/GET | `/api/v1/allergens` | Venue-scoped allergen catalog |
| POST/GET | `/api/v1/modifier-groups` | Selection rules only |
| POST/GET | `/api/v1/modifier-options` | Price deltas |
| POST | `/api/v1/menu-item-modifiers/link` | Link item → group |
| POST | `/api/v1/menu-item-allergens/link` | Link item → allergen |
| POST/GET | `/api/v1/availability-windows` | Time windows by scope |
| POST/GET | `/api/v1/menu-media-refs` | Storage file_ref only |
| POST | `/api/v1/menu-localizations/upsert` | Multi-language shells |

Plus existing 12.0 foundation surfaces unchanged (additive MenuItem fields).

## Events

| Event type | Aggregate |
| --- | --- |
| `hospitality.allergen.created` | allergen |
| `hospitality.modifier_group.created` | modifier_group |
| `hospitality.modifier_option.created` | modifier_option |
| `hospitality.menu_item_modifier.linked` | menu_item_modifier |
| `hospitality.menu_item_allergen.linked` | menu_item_allergen |
| `hospitality.availability_window.created` | availability_window |
| `hospitality.menu_media_ref.created` | menu_media_ref |
| `hospitality.menu_localization.upserted` | menu_localization |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| Media `file_ref` | Resolve via Storage API/Events | Do not store blobs in hospitality_db |
| Availability windows | Consume in QR Menu / Ordering later | Do not embed ordering engine here |
| Modifier selection rules | Drive cart/POS later | Do not implement cart/checkout in 12.1 |

## Known Limitations

- No QR Menu public rendering or ordering cart
- No kitchen ticket mapping from modifiers
- Media is reference-only (no binary upload API in Hospitality)
- Bundle gating of catalog APIs not enforced at middleware yet (permission keys registered)

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0002_phase_121_digital_menu_catalog` (down_revision `0001_initial`) |
| Upgrade steps | Run alembic upgrade head on `hospitality_db` |
| Downgrade support | Drops catalog tables; removes additive MenuItem columns |
| Data backfill | N/A (new nullable / defaulted columns) |
| Breaking changes | None — additive only |

## Quality Gates

| Gate | Result |
| --- | --- |
| Architecture | Pass |
| Dependency | Pass |
| Backward Compatibility | Pass (additive) |
| Health / Capability | Pass |
| Permission | Pass |
| API | Pass |
| Repository / Service | Pass |
| Migration | Pass |
| Tenant Isolation | Pass |
| Security | Pass |
| Performance | Pass |
| Documentation | Pass |
| Integration (contracts only) | Pass |
| Self Audit | Pass |

## Next Phase Entry

1. This handover + [hospitality-phase-12-1.md](../hospitality-phase-12-1.md)
2. Updated module registry / manifests (version `0.12.1.0`)
3. Phase **12.2 — QR Menu & QR Ordering** (do not skip; no POS yet)

## Related Documents

- [hospitality-phase-12-1.md](../hospitality-phase-12-1.md)
- [hospitality-roadmap.md](../hospitality-roadmap.md)
- [phase-handover/phase-12-0.md](phase-12-0.md)
- [ADR-017](../architecture/adr/ADR-017.md)
- [module-registry.md](../module-registry.md#hospitality)