hospitality/README.md

Digital Access and Serving System

A complete event management solution for handling VIP areas, serving quotas, and group management using QR codes. Built with .NET 9, React, TypeScript, and PostgreSQL.

Features

🔐 Authentication & Authorization

• JWT-based authentication
• Role-based access control (Admin, Staff, Guest)
• Protected routes with automatic token management
• Secure login with test accounts included

👨‍💼 Admin Interface

• Event management (create, list, view details)
• Group management with contact information
• Product management (drinks, meals, access, special)
• Person management with auto-generated QR codes
• Quota assignment to individuals
• Full QR code display with copy functionality

📱 Staff Scanner

• QR code lookup (manual entry)
• Person details and quota status display
• Transaction recording with "Use 1" and "Use 2" buttons
• Real-time quota updates

🎫 Guest View

• Auto-load personal data on login - No search required!
• Large scannable QR code display
• Quota status with progress bars
• Real-time remaining amounts

Technology Stack

Backend

• .NET 9 Web API
• ASP.NET Core Identity
• JWT Bearer Authentication
• Entity Framework Core 9
• PostgreSQL with Npgsql
• Swagger/OpenAPI

Frontend

• React 18 with TypeScript
• Vite (build tool)
• React Router 7
• TanStack Query (React Query)
• Bootstrap 5 + react-bootstrap
• Axios with JWT interceptors
• qrcode.react

Getting Started

Prerequisites

• .NET 9 SDK
• Node.js 18+
• Docker (for PostgreSQL)

Backend Setup

1. Start PostgreSQL:

docker-compose up -d

2. Run the backend:

dotnet run --project src/Hospitality.Backend

Backend runs on http://localhost:5163

Frontend Setup

cd src/hospitality-web
npm install
npm run dev

Frontend runs on http://localhost:5173

Test Accounts

The system is pre-seeded with test accounts:

• Admin: admin@example.com / Admin123!
• Staff: staff@example.com / Staff123!
• Guest: guest@example.com / Guest123!

Quick Start Guide

1. Login

1. Navigate to http://localhost:5173
2. You'll be redirected to /login
3. Login with one of the test accounts above

2. Admin Workflow

1. View events list
2. Click "Summer Festival 2025"
3. See groups and products
4. Click "VIP Sponsors" group
5. View people with full QR codes
6. Click "Copy QR Code" for John Doe
7. Assign new quotas to people

3. Staff Workflow

1. Login as staff@example.com
2. Navigate to "Staff Scanner"
3. Paste a QR code (copy from admin interface)
4. Click "Lookup Person"
5. See quotas and click "Use 1" to record consumption

4. Guest Workflow

1. Login as guest@example.com
2. Your QR code and quotas load automatically!
3. Show the QR code to staff for scanning
4. View your remaining quotas with progress bars

API Endpoints

Authentication

• POST /api/auth/login - Login
• POST /api/auth/register - Register new user (Admin only)
• GET /api/auth/me - Current user info
• GET /api/auth/me/person - Current user's person data (Guest)

Events

• GET /api/events - List all events
• GET /api/events/{id} - Get event details
• POST /api/events - Create event
• PUT /api/events/{id} - Update event
• DELETE /api/events/{id} - Delete event

Groups

• GET /api/groups/event/{eventId} - List groups for event
• GET /api/groups/{id} - Get group details
• POST /api/groups - Create group
• PUT /api/groups/{id} - Update group
• DELETE /api/groups/{id} - Delete group
• POST /api/groups/{groupId}/people - Add person to group
• POST /api/groups/{groupId}/people/{personId}/quotas - Assign quota

Products

• GET /api/products/event/{eventId} - List products for event
• POST /api/products - Create product
• PUT /api/products/{id} - Update product
• DELETE /api/products/{id} - Delete product

QR Code

• GET /api/qrcode/{qrCode} - Lookup person by QR code

Transactions

• POST /api/transactions - Record transaction
• GET /api/transactions/person/{personId} - Get person's transactions

Sample Data

The system includes comprehensive test data:

Events

• Summer Festival 2025 (July 1-3, Oslo)
• Winter Gala 2025 (December 15, Bergen)

Products

• Beer, Wine, Lunch, Dinner, VIP Lounge Access
• Champagne, Gala Dinner

Groups & People

• VIP Sponsors: John Doe, Jane Smith, Bob Wilson
• Event Staff: Alice Staff, Charlie Staff
• General Admission: Emily Guest, David Guest

Database Schema

Core Tables

• Events: Event information (name, dates, location)
• Products: Products/services (type: Access, Drink, Meal, Special)
• Groups: Guest groups with contact info
• People: Individual guests with QR codes
• PersonQuotas: Quota assignments (initial/used amounts)
• Transactions: Consumption history

Identity Tables

• AspNetUsers: User accounts (linked to People for guests)
• AspNetRoles: Roles (Admin, Staff, Guest)
• AspNetUserRoles: User-role mappings
• Plus standard Identity tables for claims, logins, tokens

Security Features

• JWT tokens with 8-hour expiration
• Password requirements (8+ chars, upper, lower, digit, special char)
• Role-based endpoint protection
• Automatic token refresh on API calls
• Auto-logout on 401 responses
• Protected routes on frontend

Development

Running Tests

dotnet test

Database Migrations

# Create a new migration
dotnet ef migrations add MigrationName --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend

# Apply migrations
dotnet ef database update --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend

# Drop database (reset)
dotnet ef database drop --force --project src/Hospitality.Infrastructure --startup-project src/Hospitality.Backend

Project Structure

hospitality/
├── src/
│   ├── Hospitality.Domain/          # Core entities and enums
│   ├── Hospitality.Infrastructure/  # EF Core, DbContext, migrations
│   ├── Hospitality.Backend/         # ASP.NET Core Web API
│   └── hospitality-web/             # React frontend
├── docker-compose.yml               # PostgreSQL container
└── README.md

Future Enhancements

• Camera QR scanner integration
• CSV import for bulk person creation
• Email/SMS QR code delivery
• Transaction history reports
• Offline support for staff app
• Real-time updates with SignalR

License

MIT

Support

For issues or questions, please open an issue on GitHub.