# KYN POS — Phase 2 Database Dictionary

This dictionary explains the intent of the Phase 2 tables in plain English.

## Foundation tables from Phase 1

| Table | Purpose |
|---|---|
| `pos_location_links` | Connects this POS app to a KYN organization/location. |
| `pos_app_settings` | Stores location-specific app settings. |
| `pos_devices` | Registers POS terminals, kitchen displays, tablets, and manager stations. |
| `pos_staff_sessions` | Tracks staff/device sessions. Phase 2 staff tables are added separately. |
| `pos_audit_logs` | Stores important security and business events. |

## Staff and permissions

| Table | Purpose |
|---|---|
| `pos_staff_roles` | Defines roles such as owner/admin, manager, server, cashier, kitchen, and auditor. |
| `pos_staff` | Stores staff identity for the POS. Passwords/PINs are hashed, not plain text. |
| `pos_staff_role_assignments` | Allows one staff member to have one or more roles. |
| `pos_staff_pins` | Stores hashed staff PINs and lockout information. |
| `pos_shifts` | Tracks clock-in/clock-out style POS shifts for staff and reporting. |

## Dining room

| Table | Purpose |
|---|---|
| `pos_dining_zones` | Groups tables by room or area, such as dining room, patio, bar, or takeout. |
| `pos_dining_tables` | Stores the physical/virtual tables used by the POS table map. |
| `pos_table_merge_rules` | Defines which tables may be joined together and the combined seat count. |

## Menu and modifiers

| Table | Purpose |
|---|---|
| `pos_service_types` | Defines dine-in, takeout, delivery, bar, catering, etc. |
| `pos_tax_rates` | Stores location-specific tax rates and effective dates. |
| `pos_sales_departments` | Maps POS revenue to KYN departments like Food, Beer, Wine, Liquor, Soft Beverages, and Other. |
| `pos_menu_categories` | Groups menu items under departments, such as Pasta, Pizza, Appetizers, Desserts. |
| `pos_menu_items` | Stores sellable items with price, course default, tax rate, and availability. |
| `pos_menu_item_prices` | Keeps price history so old sales can stay historically accurate. |
| `pos_modifier_groups` | Defines modifier groups, such as sauce choice, protein add-on, cooking temp, or side choice. |
| `pos_modifiers` | Defines modifier options and their price/food-cost behavior. |
| `pos_modifier_group_options` | Links modifier options to groups. |
| `pos_menu_item_modifier_groups` | Links menu items to the modifier groups they require or allow. |

## Checks and kitchen workflow

| Table | Purpose |
|---|---|
| `pos_checks` | The check/order header. Tracks table, service type, guest count, status, totals, and open/close times. |
| `pos_check_lines` | The individual sold items on a check. Stores item snapshot, quantity, course, seat, price, and status. |
| `pos_check_line_modifiers` | The modifiers chosen for each sold item. Stores display snapshot and price delta. |
| `pos_check_line_events` | Tracks lifecycle changes on each line, such as sent, fired, ready, served, voided, or comped. |
| `pos_course_events` | Tracks course-level events for timing and kitchen intelligence. |

## Financial adjustments and payments

| Table | Purpose |
|---|---|
| `pos_discount_reason_codes` | Standard reasons for discounts. |
| `pos_void_reason_codes` | Standard reasons for voids, including food-cost impact. |
| `pos_check_discounts` | Records check-level or line-level discounts with staff/approval. |
| `pos_check_line_voids` | Records voided lines without deleting evidence. |
| `pos_check_tax_lines` | Stores tax detail for reporting and reconciliation. |
| `pos_payment_methods` | Defines cash, credit card, debit card, gift card, check, and other tenders. |
| `pos_payments` | Stores every payment row as a proper ledger-like record. |
| `pos_payment_allocations` | Allows payment allocation to checks. This prepares for split checks and more advanced flows. |
| `pos_tip_lines` | Stores tip amounts by check/payment/staff. |

## Cash drawer and daily close

| Table | Purpose |
|---|---|
| `pos_cash_drawer_sessions` | Tracks cash drawer open/close and over/short. |
| `pos_cash_drawer_entries` | Tracks paid-in, paid-out, corrections, and cash movements. |
| `pos_daily_close_batches` | The daily close header and main boundary for KYN posting. |
| `pos_daily_close_tenders` | Daily close totals by payment method. |
| `pos_daily_close_departments` | Daily close totals by sales department. |
| `pos_daily_close_items` | Daily close totals by menu item. |

## KYN / Food Cost / TFF bridge placeholders

| Table | Purpose |
|---|---|
| `pos_menu_item_kyn_links` | Links POS menu items to KYN sales items, Food Cost recipes, packaging profiles, and TFF resupply SKUs. |
| `pos_modifier_kyn_links` | Links POS modifiers to Food Cost deltas, packaging deltas, or TFF resupply SKUs. |
| `pos_kyn_export_batches` | Tracks idempotent export batches from POS to KYN. |

## Important build rule

The POS should store clean real-time operational data. KYN should become the intelligence/reporting layer. Food Cost should translate sales into theoretical usage. TFF Auto-Resupply should convert usage and par levels into replenishment recommendations.