Enzyme Room Next.js Project Guide

You are an expert at working with the Enzyme Room (효소방) codebase - a Next.js 16 App Router application for a 24-hour unmanned enzyme bath spa reservation system.

Project Context

This is a Next.js 16 (App Router) application for "효소방" (Enzyme Room) - a 24-hour unmanned enzyme bath spa reservation system supporting customer bookings and kiosk check-in.

**Tech Stack:**

**Development commands:**

```bash

npm run dev # localhost:3000

npm run build # Production build

npm start # Production server

npm run lint # Lint

```

Architecture Overview

Data Layer (lib/storage.ts)

The application uses **browser localStorage** as a temporary data persistence layer. This is a demo setup that should be replaced with a real database in production.

**Storage collections:**

**Key patterns:**

Route Structure

**Customer flows:**

**Kiosk flow:**

**Admin flows:**

Server Actions (app/actions/)

**bookings.ts:**

**payments.ts:**

**Important:** These Server Actions currently use localStorage which only works client-side. In production, replace with database queries.

Key Business Logic

Booking Flow

1. Customer selects duration (30/60/90 min), date, time slot, and enters contact info

2. `createBooking()` atomically creates both booking and payment records

3. Client-side payment modal (PortOne) collects payment

4. `processPayment()` verifies and completes the transaction

5. Booking status progression: pending → confirmed → completed (or cancelled/refunded)

Room Availability

Pricing

Payment Integration

**PortOne (Iamport) setup:**

**Type definitions:** `lib/types/portone.d.ts` extends Window interface for IMP global

Authentication

Simple email/password authentication stored in localStorage:

**Security note:** This is demo-level auth. Implement proper authentication (NextAuth, Supabase Auth, etc.) for production.

UI Components

Uses **shadcn/ui** (New York style) with components in `components/ui/`:

Common components: Button, Card, Calendar, Input, Label, RadioGroup, Table, Badge

Code Patterns

**Form handling:**

**Type safety:**

**Styling:**

When Working on This Codebase

ALWAYS:

1. Read `lib/storage.ts` first to understand data models and storage functions

2. Check existing route structure before creating new pages

3. Use Server Actions in `app/actions/` for data mutations

4. Maintain Korean language strings for user-facing content

5. Test kiosk mode with touch-friendly UI patterns

6. Inspect localStorage in DevTools → Application → Local Storage

NEVER:

1. Assume database functionality - remember this is localStorage only

2. Skip authentication checks on admin routes

3. Hardcode PortOne merchant ID - use environment variable

4. Break the atomic booking+payment creation pattern

5. Remove rollback logic from booking creation

When Adding Features:

1. Update data models in `lib/storage.ts` if needed

2. Create corresponding storage functions (get/create/update/delete)

3. Add Server Actions in `app/actions/` for mutations

4. Use shadcn/ui components for consistent UI

5. Test with localStorage inspection in DevTools

When Debugging:

1. Check DevTools → Application → Local Storage for data state

2. Clear localStorage to reset to defaults: `localStorage.clear()`

3. Verify PortOne script loaded correctly in Network tab

4. Check console for TypeScript errors or Server Action failures

5. Test both customer and kiosk flows

Known Limitations & Production Considerations

1. **localStorage is not a real database** - Replace with PostgreSQL/Supabase/etc.

2. **Server Actions access localStorage** - This only works because Next.js bundles them for client-side execution. Proper server actions need database access.

3. **PortOne payment verification is stubbed** - Implement actual API verification in `verifyPortOnePayment()`

4. **No authentication on admin routes** - Add proper auth middleware/protection

5. **No environment variable validation** - Set `NEXT_PUBLIC_PORTONE_MERCHANT_ID` in production

6. **Demo-level authentication** - Replace with production-grade auth system

7. **No data validation middleware** - Add Zod or similar for runtime validation

8. **No error boundary components** - Add error handling for better UX

Testing in Development

Since data is in localStorage:

File Reference Quick Guide