Smart Restaurant OS — Skill Layer (Domain Intelligence for AI Agents)

A. System Overview

Smart Restaurant OS (SR-OS) is an Integrated Restaurant Ordering & Kitchen Management System (iROKMS). It is NOT a standalone POS. Its core function is to digitise the entire guest lifecycle: from table scan → ordering → kitchen execution → payment → table reset. The system follows a "Paperless Restaurant" model.

Business Objectives

| Objective | Metric | Target | |---|---|---| | Service speed | Order submission → kitchen confirmation | < 3 minutes | | Order error rate | Disputed orders | Reduce ≥ 70% | | Revenue leakage | Cancellations without audit log | 0% | | Table turnover | Restaurant floor plan management | Reduce ≥ 15% |

Architecture Direction

• Backend: FastAPI (Python 3.11+) — async, WebSocket-native
• Frontend: React.js + TypeScript — type-safe, real-time state
• Database: PostgreSQL 15+ — ACID, NOT SQLite (SQLite is forbidden in any environment except unit tests)
• Real-time: WebSocket channels per actor type; Redis Pub/Sub for multi-instance broadcast
• Auth: JWT (access: 15 min, refresh: 8 hours) + RBAC
• Caching: Redis for menu and session state during peak hours
• Deployment: Docker + Docker Compose

Core Modules

| Module | Users | Purpose | |---|---|---| | customer-web | Guests | QR scan, menu browse, cart, order, payment request | | staff-web | Waiters | Table map, order queue, confirm/reject, table transfer | | cashier-web | Cashiers | Invoice, payment recording, split bill, session close | | kds | Kitchen staff | Cooking queue, status update, out-of-stock, busy mode | | admin-portal | Admin / Manager | Menu CRUD, staff management, reports, audit log | | auth-service | All staff | JWT issue/refresh, RBAC | | realtime-core | Internal | WebSocket hub, Redis Pub/Sub broker |

B. Domain Knowledge

SR-OS targets Vietnamese dine-in restaurant operations. Guests interact via QR-scanned sessions, staff use dedicated portals, and all communication is real-time via WebSocket.

Key operational constraints:

• A table always belongs to at most one active session at any time.
• Guests cannot see or interact with other tables' sessions.
• The order creator (Staff) and payment processor (Cashier) MUST be different accounts (Segregation of Duties).
• All monetary values are in VND with 2 decimal places.

C. Core Entities

• StaffUser
• Table
• Session
• Order
• OrderDetail
• MenuItem
• Category
• Payment
• TaxConfig
• AuditLog

D. Scope & Boundaries

• In scope: Dine-in operations, KDS workflow, staff/cashier/admin portals, session lifecycle, real-time synchronization.
• Out of scope: Delivery, reservations, loyalty, multi-branch, inventory management, or external payment gateways.

E. Safety & Compliance

• All financial calculations are server-side.
• Audit logs are immutable and must be created within the same transaction as state changes.
• WebSocket broadcasts occur only after transaction commits.
• RBAC is enforced at middleware level for all endpoints.

F. Quick Start (High-level)

• Deploy backend and frontend services via the provided orchestrator.
• Seed database with sample data.
• Access Admin portal to configure VAT and service charges.
• Begin a dine-in flow using QR, staff confirmation, kitchen processing, and cashier payment.

G. Design Principles

• Centralised state machine for all transitions.
• Deterministic, auditable flows with explicit error codes (BR-*).
• Stateless backend with Redis Pub/Sub for WS distribution.
• Strict separation of concerns across modules and services.

H. References

• ERS v2.0 Enterprise Requirements
• Domain rule sets for sessions, orders, and payments
• API and WS channel specifications

I. Terminology

SR-OS terminology is canonical and must be used consistently across all components and documentation.

J. Glossary

• Session: a guest dining instance tied to a table
• Order: a collection of order details for a session
• OrderDetail: a line item within an order
• KDS: Kitchen Display System
• RBAC: Role-based access control

K. Security & Privacy

• Tokens: JWT with short-lived access tokens and longer-lived refresh tokens
• Secrets loaded from environment variables
• RBAC enforced at the middleware level
• Audit logs provide traceability for critical actions

L. Operational Practices

• Use PostgreSQL 15+ for all environments
• Docker-based deployment with explicit port mappings per frontend module
• Seed data for quick start and demo environments

M. Philosophies

• “Paperless Restaurant” model to minimise paper-based processes
• End-to-end auditability for all financial and operational changes
• Real-time, resilient user experience with fallback to polling

N. Quick Start

Install and configure environment, seed data, and start the full stack. Then open the Admin Portal to adjust VAT and service charges and begin end-to-end dine-in scenarios.

O. Additional Notes

This SR-OS Skill Layer provides governance instructions and domain knowledge to AI agents responsible for extending or validating SR-OS implementations. It emphasizes strict adherence to BR rules, event-driven architecture, and robust auditing.

P. Change History

This Skill Layer doc is maintained to reflect governance updates aligned with ERS v2.0.

Q. Future Enhancements

• Multi-branch deployment
• Loyalty and promotions (Out of scope for v2.0)
• Enhanced inventory integration (Out of scope for v2.0)

Core Entities & Relationships

• Session → Table
• Order → Session
• OrderDetail → Order, MenuItem
• Payment → Session, StaffUser
• AuditLog → StaffUser
• TaxConfig → Order

Quick Start

Use the SR-OS skill layer to validate or generate metadata for Skill Units, ensuring frontmatter integrity and description completeness. For example, to validate a Skill Unit, ensure it has SKILL.md with a name and a description, and that any referenced resources exist if declared in scripts/references/assets.