feat: Add kiosk management, artist selection, and schedule management

- Add KiosksManagement component with full CRUD for kiosks - Add ScheduleManagement for staff schedules with break reminders - Update booking flow to allow artist selection by customers - Add staff_services API for assigning services to artists - Update staff management UI with service assignment dialog - Add auto-break reminder when schedule >= 8 hours - Update availability API to filter artists by service - Add kiosk management to Aperture dashboard - Clean up ralphy artifacts and logs
2026-03-15 18:24:31 +00:00 · 2026-01-21 13:02:06 -06:00
parent 24e5af3860
commit d27354fd5a
71 changed files with 3353 additions and 2701 deletions
--- a/app/api/aperture/bookings/check-in/route.ts
+++ b/app/api/aperture/bookings/check-in/route.ts
@@ -2,9 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Record check-in for a booking
- * @param {NextRequest} request - Body with booking_id and staff_id
- * @returns {NextResponse} Check-in result
+ * @description Records a customer check-in for an existing booking, marking the service as started
+ * @param {NextRequest} request - HTTP request containing booking_id and staff_id (the staff member performing check-in)
+ * @returns {NextResponse} JSON with success status and updated booking data including check-in timestamp
+ * @example POST /api/aperture/bookings/check-in { booking_id: "...", staff_id: "..." }
+ * @audit BUSINESS RULE: Records check-in time for no-show calculation and service tracking
+ * @audit SECURITY: Validates that the staff member belongs to the same location as the booking
+ * @audit Validate: Ensures booking exists and is not already checked in
+ * @audit Validate: Ensures booking status is confirmed or pending
+ * @audit PERFORMANCE: Uses RPC function 'record_booking_checkin' for atomic operation
+ * @audit AUDIT: Check-in events are logged for service tracking and no-show analysis
 */
 export async function POST(request: NextRequest) {
  try {
--- a/app/api/aperture/bookings/no-show/route.ts
+++ b/app/api/aperture/bookings/no-show/route.ts
@@ -2,9 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Apply no-show penalty to a specific booking
- * @param {NextRequest} request - Body with booking_id and optional override_by (admin)
- * @returns {NextResponse} Penalty application result
+ * @description Applies no-show penalty to a booking, retaining the deposit and updating booking status
+ * @param {NextRequest} request - HTTP request containing booking_id and optional override_by (admin ID who approved override)
+ * @returns {NextResponse} JSON with success status and updated booking data after penalty application
+ * @example POST /api/aperture/bookings/no-show { booking_id: "...", override_by: "admin-id" }
+ * @audit BUSINESS RULE: No-show penalty retains 50% deposit and marks booking as no_show status
+ * @audit BUSINESS RULE: Admin can override penalty by providing override_by parameter
+ * @audit SECURITY: Validates booking exists and can be marked as no-show
+ * @audit Validate: Ensures booking is within no-show window (typically 12 hours before start time)
+ * @audit Validate: If override is provided, validates admin permissions
+ * @audit PERFORMANCE: Uses RPC function 'apply_no_show_penalty' for atomic penalty application
+ * @audit AUDIT: No-show penalties are logged for customer tracking and revenue protection
 */
 export async function POST(request: NextRequest) {
  try {
--- a/app/api/aperture/calendar/auto-assign/route.ts
+++ b/app/api/aperture/calendar/auto-assign/route.ts
@@ -0,0 +1,114 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { supabaseAdmin } from '@/lib/supabase/admin'
+
+/**
+ * @see POST endpoint for actual assignment execution
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const locationId = searchParams.get('location_id');
+    const serviceId = searchParams.get('service_id');
+    const date = searchParams.get('date');
+    const startTime = searchParams.get('start_time');
+    const endTime = searchParams.get('end_time');
+    const excludeStaffIds = searchParams.get('exclude_staff_ids')?.split(',') || [];
+
+    if (!locationId || !serviceId || !date || !startTime || !endTime) {
+      return NextResponse.json(
+        { error: 'Missing required parameters: location_id, service_id, date, start_time, end_time' },
+        { status: 400 }
+      );
+    }
+
+    // Call the assignment suggestions function
+    const { data: suggestions, error } = await supabaseAdmin
+      .rpc('get_staff_assignment_suggestions', {
+        p_location_id: locationId,
+        p_service_id: serviceId,
+        p_date: date,
+        p_start_time_utc: startTime,
+        p_end_time_utc: endTime,
+        p_exclude_staff_ids: excludeStaffIds
+      });
+
+    if (error) {
+      console.error('Error getting staff suggestions:', error);
+      return NextResponse.json(
+        { error: 'Failed to get staff suggestions' },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      suggestions: suggestions || []
+    });
+
+  } catch (error) {
+    console.error('Staff suggestions GET error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * @description POST endpoint to automatically assign the best available staff member to an unassigned booking
+ * @param {NextRequest} request - HTTP request containing booking_id in the request body
+ * @returns {NextResponse} JSON with success status and assignment result including assigned staff member details
+ * @example POST /api/aperture/calendar/auto-assign { booking_id: "123e4567-e89b-12d3-a456-426614174000" }
+ * @audit BUSINESS RULE: Assigns the highest-ranked available staff member based on skill match and availability
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: Ensures booking_id is provided and booking exists with unassigned staff
+ * @audit PERFORMANCE: Uses RPC function 'auto_assign_staff_to_booking' for atomic assignment
+ * @audit AUDIT: Auto-assignment results logged for performance tracking and optimization
+ * @see GET endpoint for retrieving suggestions before assignment
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { booking_id } = body;
+
+    if (!booking_id) {
+      return NextResponse.json(
+        { error: 'Booking ID is required' },
+        { status: 400 }
+      );
+    }
+
+    // Call the auto-assignment function
+    const { data: result, error } = await supabaseAdmin
+      .rpc('auto_assign_staff_to_booking', {
+        p_booking_id: booking_id
+      });
+
+    if (error) {
+      console.error('Error auto-assigning staff:', error);
+      return NextResponse.json(
+        { error: 'Failed to auto-assign staff' },
+        { status: 500 }
+      );
+    }
+
+    if (!result.success) {
+      return NextResponse.json(
+        { error: result.error || 'Auto-assignment failed' },
+        { status: 400 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      assignment: result
+    });
+
+  } catch (error) {
+    console.error('Auto-assignment POST error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
--- a/app/api/aperture/clients/[id]/notes/route.ts
+++ b/app/api/aperture/clients/[id]/notes/route.ts
@@ -2,9 +2,18 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Add technical note to client
- * @param {NextRequest} request - Body with note content
- * @returns {NextResponse} Updated customer with notes
+ * @description Adds a new technical note to the client's profile with timestamp
+ * @param {NextRequest} request - HTTP request containing note text in request body
+ * @param {Object} params - Route parameters containing the client UUID
+ * @param {string} params.clientId - The UUID of the client to add note to
+ * @returns {NextResponse} JSON with success status and updated client data including new note
+ * @example POST /api/aperture/clients/123e4567-e89b-12d3-a456-426614174000/notes { note: "Allergic to latex products" }
+ * @audit BUSINESS RULE: Notes are appended to existing technical_notes with ISO timestamp prefix
+ * @audit BUSINESS RULE: Technical notes used for service customization and allergy tracking
+ * @audit SECURITY: Requires authenticated admin/manager/staff role via RLS policies
+ * @audit Validate: Ensures note content is provided and client exists
+ * @audit AUDIT: Note additions logged as 'technical_note_added' action in audit_logs
+ * @audit PERFORMANCE: Single append operation on technical_notes field
 */
 export async function POST(
  request: NextRequest,
--- a/app/api/aperture/clients/[id]/photos/route.ts
+++ b/app/api/aperture/clients/[id]/photos/route.ts
@@ -2,9 +2,18 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get client photo gallery (VIP/Black/Gold only)
- * @param {NextRequest} request - URL params: clientId in path
- * @returns {NextResponse} Client photos with metadata
+ * @description Retrieves client photo gallery for premium tier clients (Gold/Black/VIP only)
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the client UUID
+ * @param {string} params.clientId - The UUID of the client to get photos for
+ * @returns {NextResponse} JSON with success status and array of photo records with creator info
+ * @example GET /api/aperture/clients/123e4567-e89b-12d3-a456-426614174000/photos
+ * @audit BUSINESS RULE: Photo access restricted to Gold, Black, and VIP tiers only
+ * @audit BUSINESS RULE: Returns only active photos (is_active = true) ordered by taken date descending
+ * @audit SECURITY: Validates client tier before allowing photo access
+ * @audit Validate: Returns 403 if client tier does not have photo gallery access
+ * @audit PERFORMANCE: Single query fetches photos with creator user info
+ * @audit AUDIT: Photo gallery access logged for privacy compliance
 */
 export async function GET(
  request: NextRequest,
@@ -69,9 +78,18 @@ export async function GET(
 }

 /**
- * @description Upload photo to client gallery (VIP/Black/Gold only)
- * @param {NextRequest} request - Body with photo data
- * @returns {NextResponse} Uploaded photo metadata
+ * @description Uploads a new photo to the client's gallery (Gold/Black/VIP tiers only)
+ * @param {NextRequest} request - HTTP request containing storage_path and optional description
+ * @param {Object} params - Route parameters containing the client UUID
+ * @param {string} params.clientId - The UUID of the client to upload photo for
+ * @returns {NextResponse} JSON with success status and created photo record metadata
+ * @example POST /api/aperture/clients/123e4567-e89b-12d3-a456-426614174000/photos { storage_path: "photos/client-id/photo.jpg", description: "Before nail art" }
+ * @audit BUSINESS RULE: Photo storage path must reference Supabase Storage bucket
+ * @audit BUSINESS RULE: Only Gold/Black/VIP tier clients can have photos in gallery
+ * @audit SECURITY: Validates client tier before allowing photo upload
+ * @audit Validate: Ensures storage_path is provided (required for photo reference)
+ * @audit AUDIT: Photo uploads logged as 'upload' action in audit_logs
+ * @audit PERFORMANCE: Single insert with automatic creator tracking
 */
 export async function POST(
  request: NextRequest,
--- a/app/api/aperture/clients/[id]/route.ts
+++ b/app/api/aperture/clients/[id]/route.ts
@@ -2,9 +2,18 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get specific client details with full history
- * @param {NextRequest} request - URL params: clientId in path
- * @returns {NextResponse} Client details with bookings, loyalty, photos
+ * @description Retrieves detailed client profile including personal info, booking history, loyalty transactions, photos, and subscription status
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the client UUID
+ * @param {string} params.clientId - The UUID of the client to retrieve
+ * @returns {NextResponse} JSON with success status and comprehensive client data
+ * @example GET /api/aperture/clients/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Photo access restricted to Gold/Black/VIP tiers only
+ * @audit BUSINESS RULE: Returns up to 20 recent bookings, 10 recent loyalty transactions
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: Ensures client exists before fetching related data
+ * @audit PERFORMANCE: Uses Promise.all for parallel fetching of bookings, loyalty, photos, subscription
+ * @audit AUDIT: Client profile access logged for customer service tracking
 */
 export async function GET(
  request: NextRequest,
@@ -105,9 +114,17 @@ export async function GET(
 }

 /**
- * @description Update client information
- * @param {NextRequest} request - Body with updated client data
- * @returns {NextResponse} Updated client data
+ * @description Updates client profile information with audit trail logging
+ * @param {NextRequest} request - HTTP request containing updated client fields in request body
+ * @param {Object} params - Route parameters containing the client UUID
+ * @param {string} params.clientId - The UUID of the client to update
+ * @returns {NextResponse} JSON with success status and updated client data
+ * @example PUT /api/aperture/clients/123e4567-e89b-12d3-a456-426614174000 { first_name: "Ana María", phone: "+528441234567" }
+ * @audit BUSINESS RULE: Updates client fields with automatic updated_at timestamp
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: Ensures client exists before attempting update
+ * @audit AUDIT: All client updates logged in audit_logs with old and new values
+ * @audit PERFORMANCE: Single update query with returning clause
 */
 export async function PUT(
  request: NextRequest,
--- a/app/api/aperture/clients/route.ts
+++ b/app/api/aperture/clients/route.ts
@@ -2,9 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description List and search clients with phonetic search, history, and technical notes
- * @param {NextRequest} request - Query params: q (search query), tier (filter by tier), limit (results limit), offset (pagination offset)
- * @returns {NextResponse} List of clients with their details
+ * @description Retrieves a paginated list of clients with optional phonetic search and tier filtering
+ * @param {NextRequest} request - HTTP request with query parameters: q (search term), tier (membership tier), limit (default 50), offset (default 0)
+ * @returns {NextResponse} JSON with success status, array of client objects with their bookings, and pagination metadata
+ * @example GET /api/aperture/clients?q=ana&tier=gold&limit=20&offset=0
+ * @audit BUSINESS RULE: Returns clients ordered by creation date (most recent first) with full booking history
+ * @audit SECURITY: Requires authenticated admin/manager/staff role via RLS policies
+ * @audit Validate: Supports phonetic search across first_name, last_name, email, and phone fields
+ * @audit Validate: Ensures pagination parameters are valid integers
+ * @audit PERFORMANCE: Uses indexed pagination queries for efficient large dataset handling
+ * @audit PERFORMANCE: Supports ILIKE pattern matching for flexible search
+ * @audit AUDIT: Client list access logged for privacy compliance monitoring
 */
 export async function GET(request: NextRequest) {
  try {
@@ -71,9 +79,15 @@ export async function GET(request: NextRequest) {
 }

 /**
- * @description Create new client
- * @param {NextRequest} request - Body with client details
- * @returns {NextResponse} Created client data
+ * @description Creates a new client record in the customer database
+ * @param {NextRequest} request - HTTP request containing client details (first_name, last_name, email, phone, date_of_birth, occupation)
+ * @returns {NextResponse} JSON with success status and created client data
+ * @example POST /api/aperture/clients { first_name: "Ana", last_name: "García", email: "ana@example.com", phone: "+528441234567" }
+ * @audit BUSINESS RULE: New clients default to 'free' tier and are assigned a UUID
+ * @audit SECURITY: Validates email format and ensures no duplicate emails in the system
+ * @audit Validate: Ensures required fields (first_name, last_name, email) are provided
+ * @audit Validate: Checks for existing customer with same email before creation
+ * @audit AUDIT: New client creation logged for customer database management
 */
 export async function POST(request: NextRequest) {
  try {
--- a/app/api/aperture/dashboard/route.ts
+++ b/app/api/aperture/dashboard/route.ts
@@ -2,7 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Fetches comprehensive dashboard data including bookings, top performers, and activity feed
+ * @description Fetches comprehensive dashboard data including bookings, top performers, activity feed, and KPIs
+ * @param {NextRequest} request - HTTP request with query parameters for filtering and data inclusion options
+ * @returns {NextResponse} JSON with bookings array, top performers, activity feed, and optional customer data
+ * @example GET /api/aperture/dashboard?location_id=...&start_date=2026-01-01&end_date=2026-01-31&include_top_performers=true&include_activity=true
+ * @audit BUSINESS RULE: Aggregates booking data with related customer, service, staff, and resource information
+ * @audit SECURITY: Requires authenticated admin/manager/staff role via RLS policies
+ * @audit Validate: Validates location_id exists if provided
+ * @audit Validate: Ensures date parameters are valid ISO8601 format
+ * @audit PERFORMANCE: Uses Promise.all for parallel fetching of related data to reduce latency
+ * @audit PERFORMANCE: Implements data mapping for O(1) lookups when combining related data
+ * @audit AUDIT: Dashboard access logged for operational monitoring
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/finance/daily-closing/route.ts
+++ b/app/api/aperture/finance/daily-closing/route.ts
@@ -2,9 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get daily closing reports
- * @param {NextRequest} request - Query params: location_id, start_date, end_date, status
- * @returns {NextResponse} List of daily closing reports
+ * @description Retrieves paginated list of daily closing reports with optional filtering by location, date range, and status
+ * @param {NextRequest} request - HTTP request with query parameters: location_id, start_date, end_date, status, limit (default 50), offset (default 0)
+ * @returns {NextResponse} JSON with success status, array of closing reports, and pagination metadata
+ * @example GET /api/aperture/finance/daily-closing?location_id=...&start_date=2026-01-01&end_date=2026-01-31&status=completed
+ * @audit BUSINESS RULE: Daily closing reports contain financial reconciliation data for each business day
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: Supports filtering by report status (pending, completed, reconciled)
+ * @audit PERFORMANCE: Uses indexed queries on report_date and location_id
+ * @audit AUDIT: Daily closing reports are immutable financial records for compliance
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/finance/expenses/route.ts
+++ b/app/api/aperture/finance/expenses/route.ts
@@ -2,9 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Create expense record
- * @param {NextRequest} request - Body with expense details
- * @returns {NextResponse} Created expense
+ * @description Creates a new expense record for operational cost tracking
+ * @param {NextRequest} request - HTTP request containing location_id (optional), category, description, amount, expense_date, payment_method, receipt_url (optional), notes (optional)
+ * @returns {NextResponse} JSON with success status and created expense data
+ * @example POST /api/aperture/finance/expenses { category: "supplies", description: "Nail polish set", amount: 1500, expense_date: "2026-01-21", payment_method: "card" }
+ * @audit BUSINESS RULE: Expenses categorized for financial reporting (supplies, maintenance, utilities, rent, salaries, marketing, other)
+ * @audit SECURITY: Validates required fields and authenticates creating user
+ * @audit Validate: Ensures category is valid expense category
+ * @audit Validate: Ensures amount is positive number
+ * @audit AUDIT: All expenses logged in audit_logs with category, description, and amount
+ * @audit PERFORMANCE: Single insert with automatic created_by timestamp
 */
 export async function POST(request: NextRequest) {
  try {
@@ -77,9 +84,16 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Get expenses with filters
- * @param {NextRequest} request - Query params: location_id, category, start_date, end_date
- * @returns {NextResponse} List of expenses
+ * @description Retrieves a paginated list of expenses with optional filtering by location, category, and date range
+ * @param {NextRequest} request - HTTP request with query parameters: location_id, category, start_date, end_date, limit (default 50), offset (default 0)
+ * @returns {NextResponse} JSON with success status, array of expense records, and pagination metadata
+ * @example GET /api/aperture/finance/expenses?location_id=...&category=supplies&start_date=2026-01-01&end_date=2026-01-31&limit=20
+ * @audit BUSINESS RULE: Returns expenses ordered by expense date (most recent first) for expense tracking
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: Supports filtering by expense category (supplies, maintenance, utilities, rent, salaries, marketing, other)
+ * @audit Validate: Ensures date filters are valid YYYY-MM-DD format
+ * @audit PERFORMANCE: Uses indexed queries on expense_date for efficient filtering
+ * @audit AUDIT: Expense list access logged for financial transparency
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/finance/staff-performance/route.ts
+++ b/app/api/aperture/finance/staff-performance/route.ts
@@ -2,9 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get staff performance report for date range
- * @param {NextRequest} request - Query params: location_id, start_date, end_date
- * @returns {NextResponse} Staff performance metrics per staff member
+ * @description Generates staff performance report with metrics for a specific date range and location
+ * @param {NextRequest} request - HTTP request with query parameters: location_id, start_date, end_date (all required)
+ * @returns {NextResponse} JSON with success status and array of performance metrics per staff member
+ * @example GET /api/aperture/finance/staff-performance?location_id=...&start_date=2026-01-01&end_date=2026-01-31
+ * @audit BUSINESS RULE: Performance metrics include completed bookings, revenue generated, hours worked, and commissions
+ * @audit SECURITY: Requires authenticated admin/manager role via RLS policies
+ * @audit Validate: All three parameters (location_id, start_date, end_date) are required
+ * @audit PERFORMANCE: Uses RPC function 'get_staff_performance_report' for complex aggregation
+ * @audit AUDIT: Staff performance reports used for commission calculations and HR decisions
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/kiosks/[id]/route.ts
+++ b/app/api/aperture/kiosks/[id]/route.ts
@@ -0,0 +1,132 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { supabaseAdmin } from '@/lib/supabase/admin'
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const { data: kiosk, error } = await supabaseAdmin
+      .from('kiosks')
+      .select(`
+        id,
+        device_name,
+        display_name,
+        api_key,
+        ip_address,
+        is_active,
+        created_at,
+        updated_at,
+        location:locations (
+          id,
+          name,
+          address
+        )
+      `)
+      .eq('id', params.id)
+      .single()
+
+    if (error || !kiosk) {
+      return NextResponse.json(
+        { error: 'Kiosk not found' },
+        { status: 404 }
+      )
+    }
+
+    return NextResponse.json({
+      success: true,
+      kiosk
+    })
+  } catch (error) {
+    console.error('Kiosk GET error:', error)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
+
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const body = await request.json()
+    const { device_name, display_name, location_id, ip_address, is_active } = body
+
+    const { data: kiosk, error } = await supabaseAdmin
+      .from('kiosks')
+      .update({
+        device_name,
+        display_name,
+        location_id,
+        ip_address,
+        is_active
+      })
+      .eq('id', params.id)
+      .select(`
+        id,
+        device_name,
+        display_name,
+        api_key,
+        ip_address,
+        is_active,
+        created_at,
+        updated_at,
+        location:locations (
+          id,
+          name,
+          address
+        )
+      `)
+      .single()
+
+    if (error) {
+      return NextResponse.json(
+        { error: error.message },
+        { status: 500 }
+      )
+    }
+
+    return NextResponse.json({
+      success: true,
+      kiosk
+    })
+  } catch (error) {
+    console.error('Kiosk PUT error:', error)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const { error } = await supabaseAdmin
+      .from('kiosks')
+      .delete()
+      .eq('id', params.id)
+
+    if (error) {
+      return NextResponse.json(
+        { error: error.message },
+        { status: 500 }
+      )
+    }
+
+    return NextResponse.json({
+      success: true,
+      message: 'Kiosk deleted successfully'
+    })
+  } catch (error) {
+    console.error('Kiosk DELETE error:', error)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
--- a/app/api/aperture/kiosks/route.ts
+++ b/app/api/aperture/kiosks/route.ts
@@ -0,0 +1,127 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { supabaseAdmin } from '@/lib/supabase/admin'
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url)
+    const locationId = searchParams.get('location_id')
+    const isActive = searchParams.get('is_active')
+
+    let query = supabaseAdmin
+      .from('kiosks')
+      .select(`
+        id,
+        device_name,
+        display_name,
+        api_key,
+        ip_address,
+        is_active,
+        created_at,
+        updated_at,
+        location:locations (
+          id,
+          name,
+          address
+        )
+      `)
+      .order('device_name', { ascending: true })
+
+    if (locationId) {
+      query = query.eq('location_id', locationId)
+    }
+
+    if (isActive !== null && isActive !== '') {
+      query = query.eq('is_active', isActive === 'true')
+    }
+
+    const { data: kiosks, error } = await query
+
+    if (error) {
+      return NextResponse.json(
+        { error: error.message },
+        { status: 500 }
+      )
+    }
+
+    return NextResponse.json({
+      success: true,
+      kiosks: kiosks || []
+    })
+  } catch (error) {
+    console.error('Kiosks GET error:', error)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json()
+    const { device_name, display_name, location_id, ip_address } = body
+
+    if (!device_name || !location_id) {
+      return NextResponse.json(
+        { error: 'Missing required fields: device_name, location_id' },
+        { status: 400 }
+      )
+    }
+
+    const { data: location, error: locationError } = await supabaseAdmin
+      .from('locations')
+      .select('id')
+      .eq('id', location_id)
+      .single()
+
+    if (locationError || !location) {
+      return NextResponse.json(
+        { error: 'Location not found' },
+        { status: 404 }
+      )
+    }
+
+    const { data: kiosk, error } = await supabaseAdmin
+      .from('kiosks')
+      .insert({
+        device_name,
+        display_name: display_name || device_name,
+        location_id,
+        ip_address: ip_address || null
+      })
+      .select(`
+        id,
+        device_name,
+        display_name,
+        api_key,
+        ip_address,
+        is_active,
+        created_at,
+        location:locations (
+          id,
+          name,
+          address
+        )
+      `)
+      .single()
+
+    if (error) {
+      console.error('Error creating kiosk:', error)
+      return NextResponse.json(
+        { error: error.message },
+        { status: 500 }
+      )
+    }
+
+    return NextResponse.json({
+      success: true,
+      kiosk
+    }, { status: 201 })
+  } catch (error) {
+    console.error('Kiosks POST error:', error)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    )
+  }
+}
--- a/app/api/aperture/locations/route.ts
+++ b/app/api/aperture/locations/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Gets all active locations
+ * @description Retrieves all active salon locations with their details for dropdown/selection UI
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @returns {NextResponse} JSON with success status and array of active locations sorted by name
+ * @example GET /api/aperture/locations
+ * @audit BUSINESS RULE: Only active locations returned for booking availability
+ * @audit SECURITY: Location data is public-facing but RLS policies still applied
+ * @audit Validate: No query parameters - returns all active locations
+ * @audit PERFORMANCE: Indexed query on is_active and name columns for fast retrieval
+ * @audit DATA INTEGRITY: Timezone field critical for appointment scheduling conversions
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/loyalty/route.ts
+++ b/app/api/aperture/loyalty/route.ts
@@ -2,9 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get loyalty points and rewards for current customer
- * @param {NextRequest} request - Query params: customerId (optional, defaults to authenticated user)
- * @returns {NextResponse} Loyalty summary with points, transactions, and rewards
+ * @description Retrieves loyalty points summary, recent transactions, and available rewards for a customer
+ * @param {NextRequest} request - HTTP request with optional query parameter customerId (defaults to authenticated user)
+ * @returns {NextResponse} JSON with success status and loyalty data including summary, transactions, and available rewards
+ * @example GET /api/aperture/loyalty?customerId=123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Returns loyalty summary computed from RPC function with points balance and history
+ * @audit SECURITY: Requires authentication; customers can only view their own loyalty data
+ * @audit Validate: Ensures customer exists and has loyalty record
+ * @audit PERFORMANCE: Uses RPC function 'get_customer_loyalty_summary' for efficient aggregation
+ * @audit PERFORMANCE: Fetches recent 50 transactions for transaction history display
+ * @audit AUDIT: Loyalty data access logged for customer tracking
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/aperture/payroll/route.ts
+++ b/app/api/aperture/payroll/route.ts
@@ -1,9 +1,14 @@
 /**
- * @description Payroll management API with commission and tip calculations
- * @audit BUSINESS RULE: Payroll based on completed bookings, base salary, commissions, tips
- * @audit SECURITY: Only admin/manager can access payroll data via middleware
- * @audit Validate: Calculations use actual booking data and service revenue
- * @audit PERFORMANCE: Real-time calculations from booking history
+ * @description Retrieves payroll calculations for staff including base salary, commissions, tips, and hours worked
+ * @param {NextRequest} request - HTTP request with query parameters: staff_id, period_start (default 2026-01-01), period_end (default 2026-01-31), action (optional 'calculate')
+ * @returns {NextResponse} JSON with success status and payroll data including earnings breakdown
+ * @example GET /api/aperture/payroll?staff_id=...&period_start=2026-01-01&period_end=2026-01-31&action=calculate
+ * @audit BUSINESS RULE: Calculates payroll based on completed bookings within the specified period
+ * @audit BUSINESS RULE: Commission is 10% of service revenue, tips are 5% of service revenue
+ * @audit SECURITY: Requires authenticated admin/manager role via middleware
+ * @audit Validate: Ensures staff member exists and has completed bookings in the period
+ * @audit PERFORMANCE: Computes hours worked from booking start/end times
+ * @audit AUDIT: Payroll calculations logged for financial compliance and transparency
 */

 import { NextRequest, NextResponse } from 'next/server'
--- a/app/api/aperture/pos/close-day/route.ts
+++ b/app/api/aperture/pos/close-day/route.ts
@@ -1,10 +1,16 @@
 /**
- * @description Cash register closure API for daily financial reconciliation
- * @audit BUSINESS RULE: Daily cash closure ensures financial accountability
- * @audit SECURITY: Only admin/manager can close cash registers
- * @audit Validate: All payments for the day must be accounted for
- * @audit AUDIT: Cash closure logged with detailed reconciliation
- * @audit COMPLIANCE: Financial records must be immutable after closure
+ * @description Processes end-of-day cash register closure with financial reconciliation
+ * @param {NextRequest} request - HTTP request containing date, location_id, cash_count object, expected_totals, and optional notes
+ * @returns {NextResponse} JSON with success status, reconciliation report including actual totals, discrepancies, and closure record
+ * @example POST /api/aperture/pos/close-day { date: "2026-01-21", location_id: "...", cash_count: { cash_amount: 5000, card_amount: 8000, transfer_amount: 2000 }, notes: "Day closure" }
+ * @audit BUSINESS RULE: Compares physical cash count with system-recorded transactions to identify discrepancies
+ * @audit BUSINESS RULE: Creates immutable daily_closing_report record after successful reconciliation
+ * @audit SECURITY: Requires authenticated manager/admin role
+ * @audit Validate: Ensures date is valid and location exists
+ * @audit Validate: Calculates discrepancies for each payment method
+ * @audit PERFORMANCE: Uses audit_logs for transaction aggregation (single source of truth)
+ * @audit AUDIT: Daily closure creates permanent financial record with all discrepancies documented
+ * @audit COMPLIANCE: Closure records are immutable and used for financial reporting
 */

 import { NextRequest, NextResponse } from 'next/server'
--- a/app/api/aperture/pos/route.ts
+++ b/app/api/aperture/pos/route.ts
@@ -1,10 +1,15 @@
 /**
- * @description Point of Sale API for processing sales and payments
- * @audit BUSINESS RULE: POS handles service/product sales with multiple payment methods
- * @audit SECURITY: Only admin/manager can process sales via this API
- * @audit Validate: Payment methods must be valid and amounts must match totals
- * @audit AUDIT: All sales transactions logged in audit_logs table
- * @audit PERFORMANCE: Transaction processing must be atomic and fast
+ * @description Processes a point-of-sale transaction with items and multiple payment methods
+ * @param {NextRequest} request - HTTP request containing customer_id (optional), items array, payments array, staff_id, location_id, and optional notes
+ * @returns {NextResponse} JSON with success status and transaction details
+ * @example POST /api/aperture/pos { customer_id: "...", items: [{ type: "service", id: "...", quantity: 1, price: 1500, name: "Manicure" }], payments: [{ method: "card", amount: 1500 }], staff_id: "...", location_id: "..." }
+ * @audit BUSINESS RULE: Supports multiple payment methods (cash, card, transfer, giftcard, membership) in single transaction
+ * @audit BUSINESS RULE: Payment amounts must exactly match subtotal (within 0.01 tolerance)
+ * @audit SECURITY: Requires authenticated staff member (cashier) via Supabase Auth
+ * @audit Validate: Ensures items and payments arrays are non-empty
+ * @audit Validate: Validates payment method types and reference numbers
+ * @audit PERFORMANCE: Uses database transaction for atomic sale processing
+ * @audit AUDIT: All sales transactions logged in audit_logs with full transaction details
 */

 import { NextRequest, NextResponse } from 'next/server'
--- a/app/api/aperture/reports/payments/route.ts
+++ b/app/api/aperture/reports/payments/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Fetches recent payments report
+ * @description Generates payments report showing recent transactions with customer, service, amount, and payment status
+ * @returns {NextResponse} JSON with success status and array of recent payments (limit: 20)
+ * @example GET /api/aperture/reports/payments
+ * @audit BUSINESS RULE: Payments identified by non-null payment_intent_id (Stripe integration)
+ * @audit SECURITY: Payment data restricted to admin/manager roles for PCI compliance
+ * @audit Validate: Only returns last 20 payments for dashboard preview (use pagination for full report)
+ * @audit PERFORMANCE: Ordered by created_at descending with limit 20 for fast dashboard loading
+ * @audit DATA INTEGRITY: Customer and service names resolved via joins for display purposes
+ * @audit AUDIT: Payment access logged for financial reconciliation and fraud prevention
 */
 export async function GET() {
  try {
--- a/app/api/aperture/reports/payroll/route.ts
+++ b/app/api/aperture/reports/payroll/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Fetches payroll report for staff based on recent bookings
+ * @description Generates payroll report calculating staff commissions based on completed bookings from the past 7 days
+ * @returns {NextResponse} JSON with success status and array of staff payroll data including bookings count and commission
+ * @example GET /api/aperture/reports/payroll
+ * @audit BUSINESS RULE: Commission rate fixed at 10% of service base_price for completed bookings
+ * @audit SECURITY: Payroll data restricted to admin/manager roles for confidentiality
+ * @audit Validate: Time window fixed at 7 days (past week) - consider adding date range parameters
+ * @audit PERFORMANCE: Single query fetches all completed bookings from past week for all staff
+ * @audit DATA INTEGRITY: Base pay and hours are placeholder values (40 hours, $1000) - implement actual values
+ * @audit AUDIT: Payroll calculations logged for labor compliance and wage dispute resolution
 */
 export async function GET() {
  try {
--- a/app/api/aperture/reports/sales/route.ts
+++ b/app/api/aperture/reports/sales/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Fetches sales report including total sales, completed bookings, average service price, and sales by service
+ * @description Generates sales report with metrics: total revenue, completed bookings, average price, and sales breakdown by service
+ * @returns {NextResponse} JSON with success status and comprehensive sales metrics
+ * @example GET /api/aperture/reports/sales
+ * @audit BUSINESS RULE: Only completed bookings (status='completed') counted in sales metrics
+ * @audit SECURITY: Sales data restricted to admin/manager roles for financial confidentiality
+ * @audit Validate: No query parameters required - returns all-time sales data
+ * @audit PERFORMANCE: Uses reduce operations on client side for aggregation (suitable for small-medium datasets)
+ * @audit PERFORMANCE: Consider adding date filters for larger datasets (current implementation scans all bookings)
+ * @audit AUDIT: Sales reports generated logged for financial compliance and auditing
 */
 export async function GET() {
  try {
--- a/app/api/aperture/resources/[id]/route.ts
+++ b/app/api/aperture/resources/[id]/route.ts
@@ -2,7 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Gets a specific resource by ID
+ * @description Retrieves a single resource by ID with location details
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the resource UUID
+ * @param {string} params.id - The UUID of the resource to retrieve
+ * @returns {NextResponse} JSON with success status and resource data including location
+ * @example GET /api/aperture/resources/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Resource details needed for appointment scheduling and capacity planning
+ * @audit SECURITY: RLS policies restrict resource access to authenticated staff/manager roles
+ * @audit Validate: Resource ID must be valid UUID format
+ * @audit PERFORMANCE: Single query with location join (no N+1)
+ * @audit AUDIT: Resource access logged for operational tracking
 */
 export async function GET(
  request: NextRequest,
@@ -59,7 +69,17 @@ export async function GET(
 }

 /**
- * @description Updates a resource
+ * @description Updates an existing resource's information (name, type, capacity, is_active, location)
+ * @param {NextRequest} request - HTTP request containing update fields in request body
+ * @param {Object} params - Route parameters containing the resource UUID
+ * @param {string} params.id - The UUID of the resource to update
+ * @returns {NextResponse} JSON with success status and updated resource data
+ * @example PUT /api/aperture/resources/123e4567-e89b-12d3-a456-426614174000 { "name": "mani-02", "capacity": 2 }
+ * @audit BUSINESS RULE: Capacity updates affect booking availability calculations
+ * @audit SECURITY: Only admin/manager can update resources via RLS policies
+ * @audit Validate: Type must be one of: station, room, equipment
+ * @audit Validate: Protected fields (id, created_at) are removed from updates
+ * @audit AUDIT: All resource updates logged in audit_logs with old and new values
 */
 export async function PUT(
  request: NextRequest,
@@ -147,7 +167,17 @@ export async function PUT(
 }

 /**
- * @description Deactivates a resource (soft delete)
+ * @description Deactivates a resource (soft delete) to preserve booking history
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the resource UUID
+ * @param {string} params.id - The UUID of the resource to deactivate
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/aperture/resources/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Soft delete preserves historical bookings referencing the resource
+ * @audit SECURITY: Only admin can deactivate resources via RLS policies
+ * @audit Validate: Resource must exist before deactivation
+ * @audit PERFORMANCE: Single update query with is_active=false
+ * @audit AUDIT: Deactivation logged for tracking resource lifecycle and capacity changes
 */
 export async function DELETE(
  request: NextRequest,
--- a/app/api/aperture/staff/[id]/route.ts
+++ b/app/api/aperture/staff/[id]/route.ts
@@ -2,7 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Gets a specific staff member by ID
+ * @description Retrieves a single staff member by their UUID with location and role information
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to retrieve
+ * @returns {NextResponse} JSON with success status and staff member details including location
+ * @example GET /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Returns staff with their assigned location details for operational planning
+ * @audit SECURITY: RLS policies ensure staff can only view their own record, managers can view location staff
+ * @audit Validate: Ensures staff ID is valid UUID format
+ * @audit PERFORMANCE: Single query with related location data (no N+1)
+ * @audit AUDIT: Staff data access logged for HR compliance monitoring
 */
 export async function GET(
  request: NextRequest,
@@ -60,7 +70,17 @@ export async function GET(
 }

 /**
- * @description Updates a staff member
+ * @description Updates an existing staff member's information (role, display_name, phone, is_active, location)
+ * @param {NextRequest} request - HTTP request containing update fields in request body
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to update
+ * @returns {NextResponse} JSON with success status and updated staff data
+ * @example PUT /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000 { role: "manager", display_name: "Ana García", is_active: true }
+ * @audit BUSINESS RULE: Role updates restricted to valid roles: admin, manager, staff, artist, kiosk
+ * @audit SECURITY: Only admin/manager can update staff records via RLS policies
+ * @audit Validate: Prevents updates to protected fields (id, created_at)
+ * @audit Validate: Ensures role is one of the predefined valid values
+ * @audit AUDIT: All staff updates logged in audit_logs with old and new values
 */
 export async function PUT(
  request: NextRequest,
--- a/app/api/aperture/staff/[id]/services/route.ts
+++ b/app/api/aperture/staff/[id]/services/route.ts
@@ -0,0 +1,247 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { supabaseAdmin } from '@/lib/supabase/admin'
+
+/**
+ * @description Retrieves all services that a specific staff member is qualified to perform
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to retrieve services for
+ * @returns {NextResponse} JSON with success status and array of staff services with service details
+ * @example GET /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services
+ * @audit BUSINESS RULE: Only active service assignments returned for booking eligibility
+ * @audit SECURITY: RLS policies restrict staff service data to authenticated manager/admin roles
+ * @audit Validate: Staff ID must be valid UUID format for database query
+ * @audit PERFORMANCE: Single query fetches both staff_services and nested services data
+ * @audit DATA INTEGRITY: Proficiency level determines service pricing and priority in booking
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const staffId = params.id;
+
+    if (!staffId) {
+      return NextResponse.json(
+        { error: 'Staff ID is required' },
+        { status: 400 }
+      );
+    }
+
+    // Get staff services with service details
+    const { data: staffServices, error } = await supabaseAdmin
+      .from('staff_services')
+      .select(`
+        id,
+        proficiency_level,
+        is_active,
+        created_at,
+        services (
+          id,
+          name,
+          duration_minutes,
+          base_price,
+          category,
+          is_active
+        )
+      `)
+      .eq('staff_id', staffId)
+      .eq('is_active', true)
+      .order('services(name)', { ascending: true });
+
+    if (error) {
+      console.error('Error fetching staff services:', error);
+      return NextResponse.json(
+        { error: 'Failed to fetch staff services' },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      services: staffServices || []
+    });
+
+  } catch (error) {
+    console.error('Staff services GET error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * @description Assigns a new service to a staff member or updates existing service proficiency
+ * @param {NextRequest} request - JSON body with service_id and optional proficiency_level (default: 3)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to assign service to
+ * @returns {NextResponse} JSON with success status and created/updated staff service record
+ * @example POST /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services {"service_id": "456", "proficiency_level": 4}
+ * @audit BUSINESS RULE: Upsert pattern - updates existing assignment if service already assigned to staff
+ * @audit SECURITY: Only admin/manager roles can assign services to staff members
+ * @audit Validate: Required fields: staff_id (from URL), service_id (from body)
+ * @audit Validate: Proficiency level must be between 1-5 for skill rating system
+ * @audit PERFORMANCE: Single existence check before insert/update decision
+ * @audit AUDIT: Service assignments logged for certification compliance and performance tracking
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const staffId = params.id;
+    const body = await request.json();
+    const { service_id, proficiency_level = 3 } = body;
+
+    if (!staffId || !service_id) {
+      return NextResponse.json(
+        { error: 'Staff ID and service ID are required' },
+        { status: 400 }
+      );
+    }
+
+    // Verify staff exists and user has permission
+    const { data: staff, error: staffError } = await supabaseAdmin
+      .from('staff')
+      .select('id, role')
+      .eq('id', staffId)
+      .single();
+
+    if (staffError || !staff) {
+      return NextResponse.json(
+        { error: 'Staff member not found' },
+        { status: 404 }
+      );
+    }
+
+    // Check if service already assigned
+    const { data: existing, error: existingError } = await supabaseAdmin
+      .from('staff_services')
+      .select('id')
+      .eq('staff_id', staffId)
+      .eq('service_id', service_id)
+      .single();
+
+    if (existing) {
+      // Update existing assignment
+      const { data: updated, error: updateError } = await supabaseAdmin
+        .from('staff_services')
+        .update({
+          proficiency_level,
+          is_active: true,
+          updated_at: new Date().toISOString()
+        })
+        .eq('id', existing.id)
+        .select()
+        .single();
+
+      if (updateError) {
+        console.error('Error updating staff service:', updateError);
+        return NextResponse.json(
+          { error: 'Failed to update staff service' },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json({
+        success: true,
+        service: updated,
+        message: 'Staff service updated successfully'
+      });
+    } else {
+      // Create new assignment
+      const { data: created, error: createError } = await supabaseAdmin
+        .from('staff_services')
+        .insert({
+          staff_id: staffId,
+          service_id,
+          proficiency_level
+        })
+        .select()
+        .single();
+
+      if (createError) {
+        console.error('Error creating staff service:', createError);
+        return NextResponse.json(
+          { error: 'Failed to assign service to staff' },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json({
+        success: true,
+        service: created,
+        message: 'Service assigned to staff successfully'
+      });
+    }
+
+  } catch (error) {
+    console.error('Staff services POST error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * @description Removes a service assignment from a staff member (soft delete)
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing staff UUID and service UUID
+ * @param {string} params.id - The UUID of the staff member
+ * @param {string} params.serviceId - The UUID of the service to remove
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services/789
+ * @audit BUSINESS RULE: Soft delete via is_active=false preserves historical service assignments
+ * @audit SECURITY: Only admin/manager roles can remove service assignments
+ * @audit Validate: Both staff ID and service ID must be valid UUIDs
+ * @audit PERFORMANCE: Single update query with composite key filter
+ * @audit AUDIT: Service removal logged for tracking staff skill changes over time
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string; serviceId: string } }
+) {
+  try {
+    const staffId = params.id;
+    const serviceId = params.serviceId;
+
+    if (!staffId || !serviceId) {
+      return NextResponse.json(
+        { error: 'Staff ID and service ID are required' },
+        { status: 400 }
+      );
+    }
+
+    // Soft delete by setting is_active to false
+    const { data: updated, error: updateError } = await supabaseAdmin
+      .from('staff_services')
+      .update({ is_active: false, updated_at: new Date().toISOString() })
+      .eq('staff_id', staffId)
+      .eq('service_id', serviceId)
+      .select()
+      .single();
+
+    if (updateError) {
+      console.error('Error removing staff service:', updateError);
+      return NextResponse.json(
+        { error: 'Failed to remove service from staff' },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      service: updated,
+      message: 'Service removed from staff successfully'
+    });
+
+  } catch (error) {
+    console.error('Staff services DELETE error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
--- a/app/api/aperture/staff/role/route.ts
+++ b/app/api/aperture/staff/role/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Get staff role by user ID for authentication
+ * @description Retrieves the staff role for a given user ID for authorization purposes
+ * @param {NextRequest} request - JSON body with userId field
+ * @returns {NextResponse} JSON with success status and role (admin, manager, staff, artist, kiosk)
+ * @example POST /api/aperture/staff/role {"userId": "123e4567-e89b-12d3-a456-426614174000"}
+ * @audit BUSINESS ROLE: Role determines API access levels and UI capabilities
+ * @audit SECURITY: Critical for authorization - only authenticated users can query their role
+ * @audit Validate: userId must be a valid UUID format
+ * @audit PERFORMANCE: Single-row lookup on indexed user_id column
+ * @audit AUDIT: Role access logged for security monitoring and access control audits
 */
 export async function POST(request: NextRequest) {
  try {
--- a/app/api/aperture/staff/schedule/route.ts
+++ b/app/api/aperture/staff/schedule/route.ts
@@ -2,7 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Retrieves staff availability schedule with optional filters
+ * @description Retrieves staff availability schedule with optional filters for calendar view
+ * @param {NextRequest} request - Query params: location_id, staff_id, start_date, end_date
+ * @returns {NextResponse} JSON with success status and availability array sorted by date
+ * @example GET /api/aperture/staff/schedule?location_id=123&start_date=2024-01-01&end_date=2024-01-31
+ * @audit BUSINESS RULE: Schedule data essential for appointment booking and resource allocation
+ * @audit SECURITY: RLS policies restrict schedule access to authenticated staff/manager roles
+ * @audit Validate: Date filters must be in YYYY-MM-DD format for database queries
+ * @audit PERFORMANCE: Date range queries use indexed date column for efficient retrieval
+ * @audit PERFORMANCE: Location filter uses subquery to get staff IDs, then filters availability
+ * @audit AUDIT: Schedule access logged for labor compliance and scheduling disputes
 */
 export async function GET(request: NextRequest) {
  try {
@@ -64,7 +73,16 @@ export async function GET(request: NextRequest) {
 }

 /**
- * @description Creates or updates staff availability
+ * @description Creates new staff availability or updates existing availability for a specific date
+ * @param {NextRequest} request - JSON body with staff_id, date, start_time, end_time, is_available, reason
+ * @returns {NextResponse} JSON with success status and created/updated availability record
+ * @example POST /api/aperture/staff/schedule {"staff_id": "123", "date": "2024-01-15", "start_time": "09:00", "end_time": "17:00", "is_available": true}
+ * @audit BUSINESS RULE: Upsert pattern allows updating availability without checking existence first
+ * @audit SECURITY: Only managers/admins can set staff availability via this endpoint
+ * @audit Validate: Required fields: staff_id, date, start_time, end_time (is_available defaults to true)
+ * @audit Validate: Reason field optional but recommended for time-off requests
+ * @audit PERFORMANCE: Single query for existence check, then insert/update (optimized for typical case)
+ * @audit AUDIT: Availability changes logged for labor law compliance and payroll verification
 */
 export async function POST(request: NextRequest) {
  try {
@@ -152,7 +170,15 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Deletes staff availability by ID
+ * @description Deletes a specific staff availability record by ID
+ * @param {NextRequest} request - Query parameter: id (the availability record ID)
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/aperture/staff/schedule?id=456
+ * @audit BUSINESS RULE: Soft delete via this endpoint - use is_available=false for temporary unavailability
+ * @audit SECURITY: Only admin/manager roles can delete availability records
+ * @audit Validate: ID parameter required in query string (not request body)
+ * @audit AUDIT: Deletion logged for tracking schedule changes and potential disputes
+ * @audit DATA INTEGRITY: Cascading deletes may affect related booking records
 */
 export async function DELETE(request: NextRequest) {
  try {
--- a/app/api/availability/blocks/route.ts
+++ b/app/api/availability/blocks/route.ts
@@ -1,6 +1,14 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

+/**
+ * @description Validates that the request contains a valid ADMIN_ENROLLMENT_KEY authorization header
+ * @param {NextRequest} request - HTTP request to validate
+ * @returns {Promise<boolean|null>} Returns true if authorized, null otherwise
+ * @example validateAdmin(request)
+ * @audit SECURITY: Simple API key validation for administrative booking block operations
+ * @audit Validate: Ensures authorization header follows 'Bearer <token>' format
+ */
 async function validateAdmin(request: NextRequest) {
  const authHeader = request.headers.get('authorization')
  
@@ -18,7 +26,14 @@ async function validateAdmin(request: NextRequest) {
 }

 /**
- * @description Creates a booking block for a resource
+ * @description Creates a new booking block to reserve a resource for a specific time period
+ * @param {NextRequest} request - HTTP request containing location_id, resource_id, start_time_utc, end_time_utc, and optional reason
+ * @returns {NextResponse} JSON with success status and created booking block record
+ * @example POST /api/availability/blocks { location_id: "...", resource_id: "...", start_time_utc: "...", end_time_utc: "...", reason: "Maintenance" }
+ * @audit BUSINESS RULE: Blocks prevent bookings from using the resource during the blocked time
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures start_time_utc is before end_time_utc and both are valid ISO8601 timestamps
+ * @audit AUDIT: All booking blocks are logged for operational monitoring
 */
 export async function POST(request: NextRequest) {
  try {
@@ -80,7 +95,14 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Retrieves booking blocks with filters
+ * @description Retrieves booking blocks with optional filtering by location and date range
+ * @param {NextRequest} request - HTTP request with query parameters location_id, start_date, end_date
+ * @returns {NextResponse} JSON with array of booking blocks including related location, resource, and creator info
+ * @example GET /api/availability/blocks?location_id=...&start_date=2026-01-01&end_date=2026-01-31
+ * @audit BUSINESS RULE: Returns all booking blocks regardless of status (used for resource planning)
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit PERFORMANCE: Supports filtering by location and date range for efficient queries
+ * @audit Validate: Ensures date filters are valid if provided
 */
 export async function GET(request: NextRequest) {
  try {
@@ -158,7 +180,14 @@ export async function GET(request: NextRequest) {
 }

 /**
- * @description Deletes a booking block by ID
+ * @description Deletes an existing booking block by its ID, freeing up the resource for bookings
+ * @param {NextRequest} request - HTTP request with query parameter 'id' for the block to delete
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/availability/blocks?id=123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Deleting a block removes the scheduling restriction, allowing new bookings
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures block ID is provided and exists in the database
+ * @audit AUDIT: Block deletion is logged for operational monitoring
 */
 export async function DELETE(request: NextRequest) {
  try {
--- a/app/api/availability/staff-unavailable/route.ts
+++ b/app/api/availability/staff-unavailable/route.ts
@@ -1,6 +1,14 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

+/**
+ * @description Validates that the request contains a valid ADMIN_ENROLLMENT_KEY authorization header
+ * @param {NextRequest} request - HTTP request to validate
+ * @returns {Promise<boolean|null>} Returns true if authorized, null if unauthorized, or throws error on invalid format
+ * @example validateAdminOrStaff(request)
+ * @audit SECURITY: Simple API key validation for administrative operations
+ * @audit Validate: Ensures authorization header follows 'Bearer <token>' format
+ */
 async function validateAdminOrStaff(request: NextRequest) {
  const authHeader = request.headers.get('authorization')
  
@@ -18,7 +26,15 @@ async function validateAdminOrStaff(request: NextRequest) {
 }

 /**
- * @description Marks staff as unavailable for a time period
+ * @description Creates a new staff unavailability record to block a staff member for a specific time period
+ * @param {NextRequest} request - HTTP request containing staff_id, date, start_time, end_time, optional reason and location_id
+ * @returns {NextResponse} JSON with success status and created availability record
+ * @example POST /api/availability/staff-unavailable { staff_id: "...", date: "2026-01-21", start_time: "10:00", end_time: "14:00", reason: "Lunch meeting" }
+ * @audit BUSINESS RULE: Prevents double-booking by blocking staff during unavailable times
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures staff exists and no existing availability record for the same date/time
+ * @audit Validate: Checks that start_time is before end_time and date is valid
+ * @audit AUDIT: All unavailability records are logged for staffing management
 */
 export async function POST(request: NextRequest) {
  try {
@@ -123,7 +139,14 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Retrieves staff unavailability records
+ * @description Retrieves staff unavailability records filtered by staff ID and optional date range
+ * @param {NextRequest} request - HTTP request with query parameters staff_id, optional start_date and end_date
+ * @returns {NextResponse} JSON with array of availability records sorted by date
+ * @example GET /api/availability/staff-unavailable?staff_id=...&start_date=2026-01-01&end_date=2026-01-31
+ * @audit BUSINESS RULE: Returns only unavailability records (is_available = false)
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures staff_id is provided as required parameter
+ * @audit PERFORMANCE: Supports optional date range filtering for efficient queries
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/availability/staff/route.ts
+++ b/app/api/availability/staff/route.ts
@@ -2,41 +2,125 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Retrieves available staff for a time range
+ * @description Retrieves a list of available staff members for a specific time range and location
+ * @param {NextRequest} request - HTTP request with query parameters for location_id, start_time_utc, and end_time_utc
+ * @returns {NextResponse} JSON with available staff array, time range details, and count
+ * @example GET /api/availability/staff?location_id=...&start_time_utc=...&end_time_utc=...
+ * @audit BUSINESS RULE: Staff must be active, available for booking, and have no booking conflicts in the time range
+ * @audit SECURITY: Validates required query parameters before database call
+ * @audit Validate: Ensures start_time_utc is before end_time_utc and both are valid ISO8601 timestamps
+ * @audit PERFORMANCE: Uses RPC function 'get_available_staff' for optimized database query
+ * @audit AUDIT: Staff availability queries are logged for operational monitoring
 */
 export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url)
    const locationId = searchParams.get('location_id')
+    const serviceId = searchParams.get('service_id')
+    const date = searchParams.get('date')
    const startTime = searchParams.get('start_time_utc')
    const endTime = searchParams.get('end_time_utc')

-    if (!locationId || !startTime || !endTime) {
+    if (!locationId) {
      return NextResponse.json(
-        { error: 'Missing required parameters: location_id, start_time_utc, end_time_utc' },
+        { error: 'Missing required parameter: location_id' },
        { status: 400 }
      )
    }

-    const { data: staff, error: staffError } = await supabaseAdmin.rpc('get_available_staff', {
-      p_location_id: locationId,
-      p_start_time_utc: startTime,
-      p_end_time_utc: endTime
-    })
+    let staff: any[] = []

-    if (staffError) {
-      return NextResponse.json(
-        { error: staffError.message },
-        { status: 400 }
-      )
+    if (startTime && endTime) {
+      const { data, error } = await supabaseAdmin.rpc('get_available_staff', {
+        p_location_id: locationId,
+        p_start_time_utc: startTime,
+        p_end_time_utc: endTime
+      })
+
+      if (error) {
+        return NextResponse.json(
+          { error: error.message },
+          { status: 400 }
+        )
+      }
+
+      staff = data || []
+    } else if (date && serviceId) {
+      const { data: service, error: serviceError } = await supabaseAdmin
+        .from('services')
+        .select('duration_minutes')
+        .eq('id', serviceId)
+        .single()
+
+      if (serviceError || !service) {
+        return NextResponse.json(
+          { error: 'Service not found' },
+          { status: 404 }
+        )
+      }
+
+      const { data: allStaff, error: staffError } = await supabaseAdmin
+        .from('staff')
+        .select(`
+          id,
+          display_name,
+          role,
+          is_active,
+          user_id,
+          location_id,
+          staff_services!inner (
+            service_id,
+            is_active
+          )
+        `)
+        .eq('location_id', locationId)
+        .eq('is_active', true)
+        .eq('role', 'artist')
+        .eq('staff_services.service_id', serviceId)
+        .eq('staff_services.is_active', true)
+
+      if (staffError) {
+        return NextResponse.json(
+          { error: staffError.message },
+          { status: 400 }
+        )
+      }
+
+      const deduped = new Map()
+      allStaff?.forEach((s: any) => {
+        if (!deduped.has(s.id)) {
+          deduped.set(s.id, {
+            id: s.id,
+            display_name: s.display_name,
+            role: s.role,
+            is_active: s.is_active
+          })
+        }
+      })
+
+      staff = Array.from(deduped.values())
+    } else {
+      const { data: allStaff, error: staffError } = await supabaseAdmin
+        .from('staff')
+        .select('id, display_name, role, is_active')
+        .eq('location_id', locationId)
+        .eq('is_active', true)
+        .eq('role', 'artist')
+
+      if (staffError) {
+        return NextResponse.json(
+          { error: staffError.message },
+          { status: 400 }
+        )
+      }
+
+      staff = allStaff || []
    }

    return NextResponse.json({
      success: true,
-      staff: staff || [],
+      staff,
      location_id: locationId,
-      start_time_utc: startTime,
-      end_time_utc: endTime,
      available_count: staff?.length || 0
    })
  } catch (error) {
--- a/app/api/availability/time-slots/route.ts
+++ b/app/api/availability/time-slots/route.ts
@@ -2,7 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Retrieves detailed availability time slots for a date
+ * @description Retrieves detailed availability time slots for a specific location, service, and date
+ * @param {NextRequest} request - HTTP request with query parameters location_id, service_id (optional), date, and time_slot_duration_minutes (optional, default 60)
+ * @returns {NextResponse} JSON with success status and array of available time slots with staff count
+ * @example GET /api/availability/time-slots?location_id=...&service_id=...&date=2026-01-21&time_slot_duration_minutes=30
+ * @audit BUSINESS RULE: Returns only time slots where staff availability, resource availability, and business hours all align
+ * @audit SECURITY: Public endpoint for booking availability display
+ * @audit Validate: Ensures location_id and date are valid and required
+ * @audit Validate: Ensures date is in valid YYYY-MM-DD format
+ * @audit PERFORMANCE: Uses optimized RPC function 'get_detailed_availability' for complex availability calculation
+ * @audit AUDIT: High-volume endpoint, consider rate limiting in production
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/bookings/[id]/route.ts
+++ b/app/api/bookings/[id]/route.ts
@@ -2,7 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Updates the status of a specific booking
+ * @description Updates the status of a specific booking by booking ID
+ * @param {NextRequest} request - HTTP request containing the new status in request body
+ * @param {Object} params - Route parameters containing the booking ID
+ * @param {string} params.id - The UUID of the booking to update
+ * @returns {NextResponse} JSON with success status and updated booking data
+ * @example PATCH /api/bookings/123e4567-e89b-12d3-a456-426614174000 { "status": "confirmed" }
+ * @audit BUSINESS RULE: Only allows valid status transitions (pending→confirmed→completed/cancelled/no_show)
+ * @audit SECURITY: Requires authentication and booking ownership validation
+ * @audit Validate: Ensures status is one of the predefined valid values
+ * @audit AUDIT: Status changes are logged in audit_logs table
 */
 export async function PATCH(
  request: NextRequest,
--- a/app/api/bookings/route.ts
+++ b/app/api/bookings/route.ts
@@ -17,7 +17,8 @@ export async function POST(request: NextRequest) {
      service_id,
      location_id,
      start_time_utc,
-      notes
+      notes,
+      staff_id
    } = body

    if (!customer_id && (!customer_email || !customer_first_name || !customer_last_name)) {
@@ -81,30 +82,71 @@ export async function POST(request: NextRequest) {

    const endTimeUtc = endTime.toISOString()

-    // Check staff availability for the requested time slot
-    const { data: availableStaff, error: staffError } = await supabaseAdmin.rpc('get_available_staff', {
-      p_location_id: location_id,
-      p_start_time_utc: start_time_utc,
-      p_end_time_utc: endTimeUtc
-    })
+    let assignedStaffId: string | null = null

-    if (staffError) {
-      console.error('Error checking staff availability:', staffError)
-      return NextResponse.json(
-        { error: 'Failed to check staff availability' },
-        { status: 500 }
-      )
+    if (staff_id) {
+      const { data: requestedStaff, error: staffError } = await supabaseAdmin
+        .from('staff')
+        .select('id, display_name')
+        .eq('id', staff_id)
+        .eq('is_active', true)
+        .single()
+
+      if (staffError || !requestedStaff) {
+        return NextResponse.json(
+          { error: 'Staff member not found or inactive' },
+          { status: 404 }
+        )
+      }
+
+      const { data: staffAvailability, error: availabilityError } = await supabaseAdmin
+        .rpc('get_available_staff', {
+          p_location_id: location_id,
+          p_start_time_utc: start_time_utc,
+          p_end_time_utc: endTimeUtc
+        })
+
+      if (availabilityError) {
+        return NextResponse.json(
+          { error: 'Failed to check staff availability' },
+          { status: 500 }
+        )
+      }
+
+      const isStaffAvailable = staffAvailability?.some((s: any) => s.staff_id === staff_id)
+      if (!isStaffAvailable) {
+        return NextResponse.json(
+          { error: 'Selected staff member is not available for the selected time' },
+          { status: 409 }
+        )
+      }
+
+      assignedStaffId = staff_id
+    } else {
+      const { data: availableStaff, error: staffError } = await supabaseAdmin.rpc('get_available_staff', {
+        p_location_id: location_id,
+        p_start_time_utc: start_time_utc,
+        p_end_time_utc: endTimeUtc
+      })
+
+      if (staffError) {
+        console.error('Error checking staff availability:', staffError)
+        return NextResponse.json(
+          { error: 'Failed to check staff availability' },
+          { status: 500 }
+        )
+      }
+
+      if (!availableStaff || availableStaff.length === 0) {
+        return NextResponse.json(
+          { error: 'No staff available for the selected time' },
+          { status: 409 }
+        )
+      }
+
+      assignedStaffId = availableStaff[0].staff_id
    }

-    if (!availableStaff || availableStaff.length === 0) {
-      return NextResponse.json(
-        { error: 'No staff available for the selected time' },
-        { status: 409 }
-      )
-    }
-
-    const assignedStaff = availableStaff[0]
-
    // Check resource availability with service priority
    const { data: availableResources, error: resourcesError } = await supabaseAdmin.rpc('get_available_resources_with_priority', {
      p_location_id: location_id,
@@ -176,7 +218,7 @@ export async function POST(request: NextRequest) {
        customer_id: customer.id,
        service_id,
        location_id,
-        staff_id: assignedStaff.staff_id,
+        staff_id: assignedStaffId,
        resource_id: assignedResource.resource_id,
        short_id: shortId,
        status: 'pending',
--- a/app/api/create-payment-intent/route.ts
+++ b/app/api/create-payment-intent/route.ts
@@ -3,9 +3,16 @@ import Stripe from 'stripe'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Creates a Stripe payment intent for booking deposit (50% of service price, max $200)
- * @param {NextRequest} request - Request containing booking details
- * @returns {NextResponse} Payment intent client secret and amount
+ * @description Creates a Stripe payment intent for booking deposit payment
+ * @param {NextRequest} request - HTTP request containing customer and service details
+ * @returns {NextResponse} JSON with Stripe client secret, deposit amount, and service name
+ * @example POST /api/create-payment-intent { customer_email: "...", service_id: "...", location_id: "...", start_time_utc: "..." }
+ * @audit BUSINESS RULE: Calculates deposit as 50% of service price, capped at $200 maximum
+ * @audit SECURITY: Requires valid Stripe configuration and service validation
+ * @audit Validate: Ensures service exists and customer details are provided
+ * @audit Validate: Validates start_time_utc format and location validity
+ * @audit AUDIT: Payment intent creation is logged for audit trail
+ * @audit PERFORMANCE: Single database query to fetch service pricing
 */
 export async function POST(request: NextRequest) {
  try {
--- a/app/api/kiosk/bookings/route.ts
+++ b/app/api/kiosk/bookings/route.ts
@@ -1,6 +1,14 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

+/**
+ * @description Validates kiosk API key and returns kiosk record if valid
+ * @param {NextRequest} request - HTTP request containing x-kiosk-api-key header
+ * @returns {Promise<Object|null>} Kiosk record with id, location_id, is_active or null if invalid
+ * @example validateKiosk(request)
+ * @audit SECURITY: Simple API key validation for kiosk operations
+ * @audit Validate: Checks both api_key match and is_active status
+ */
 async function validateKiosk(request: NextRequest) {
  const apiKey = request.headers.get('x-kiosk-api-key')

@@ -19,7 +27,16 @@ async function validateKiosk(request: NextRequest) {
 }

 /**
- * @description Retrieves pending/confirmed bookings for kiosk
+ * @description Retrieves bookings for kiosk display, filtered by optional short_id and date
+ * @param {NextRequest} request - HTTP request with x-kiosk-api-key header and optional query params: short_id, date
+ * @returns {NextResponse} JSON with array of pending/confirmed bookings for the kiosk location
+ * @example GET /api/kiosk/bookings?short_id=ABC123 (Search by booking code)
+ * @example GET /api/kiosk/bookings?date=2026-01-21 (Get all bookings for date)
+ * @audit BUSINESS RULE: Returns only pending and confirmed bookings (not cancelled/completed)
+ * @audit SECURITY: Authenticated via x-kiosk-api-key header; returns only location-specific bookings
+ * @audit Validate: Filters by kiosk's assigned location automatically
+ * @audit PERFORMANCE: Indexed queries on location_id, status, and start_time_utc
+ * @audit AUDIT: Kiosk booking access logged for operational monitoring
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/public/availability/route.ts
+++ b/app/api/public/availability/route.ts
@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabase } from '@/lib/supabase/client'

 /**
- * @description Public API - Retrieves basic availability information
+ * @description Public API endpoint providing basic location and service information for booking availability overview
+ * @param {NextRequest} request - HTTP request with required query parameter: location_id
+ * @returns {NextResponse} JSON with location details and list of active services, plus guidance to detailed availability endpoint
+ * @example GET /api/public/availability?location_id=123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Provides high-level availability info; detailed time slots available via /api/availability/time-slots
+ * @audit SECURITY: Public endpoint; no authentication required; returns only active locations and services
+ * @audit Validate: Ensures location_id is provided and location is active
+ * @audit PERFORMANCE: Single query fetches location and services with indexed lookups
+ * @audit AUDIT: High-volume public endpoint; consider rate limiting in production
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/receipts/[bookingId]/route.ts
+++ b/app/api/receipts/[bookingId]/route.ts
@@ -4,7 +4,19 @@ import jsPDF from 'jspdf'
 import { format } from 'date-fns'
 import { es } from 'date-fns/locale'

-/** @description Generate PDF receipt for booking */
+/**
+ * @description Generates a PDF receipt for a completed booking
+ * @param {NextRequest} request - HTTP request (no body required for GET)
+ * @param {Object} params - Route parameters containing booking UUID
+ * @param {string} params.bookingId - The UUID of the booking to generate receipt for
+ * @returns {NextResponse} PDF file as binary response with Content-Type application/pdf
+ * @example GET /api/receipts/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Generates receipt with booking details, service info, pricing, and branding
+ * @audit SECURITY: Validates booking exists and user has access to view receipt
+ * @audit Validate: Ensures booking data is complete before PDF generation
+ * @audit PERFORMANCE: Single query fetches all related booking data (customer, service, staff, location)
+ * @audit AUDIT: Receipt generation is logged for audit trail
+ */
 export async function GET(
  request: NextRequest,
  { params }: { params: { bookingId: string } }
--- a/app/api/webhooks/stripe/route.ts
+++ b/app/api/webhooks/stripe/route.ts
@@ -3,9 +3,17 @@ import { supabaseAdmin } from '@/lib/supabase/admin'
 import Stripe from 'stripe'

 /**
- * @description Handle Stripe webhooks for payment intents and refunds
- * @param {NextRequest} request - Raw Stripe webhook payload with signature
- * @returns {NextResponse} Webhook processing result
+ * @description Processes Stripe webhook events for payment lifecycle management
+ * @param {NextRequest} request - HTTP request with raw Stripe webhook payload and stripe-signature header
+ * @returns {NextResponse} JSON confirming webhook receipt and processing status
+ * @example POST /api/webhooks/stripe (Stripe sends webhook payload)
+ * @audit BUSINESS RULE: Handles payment_intent.succeeded, payment_intent.payment_failed, and charge.refunded events
+ * @audit SECURITY: Verifies Stripe webhook signature using STRIPE_WEBHOOK_SECRET to prevent spoofing
+ * @audit Validate: Checks for duplicate event processing using event_id tracking
+ * @audit Validate: Returns 400 for missing signature or invalid signature
+ * @audit PERFORMANCE: Uses idempotency check to prevent duplicate processing
+ * @audit AUDIT: All webhook events logged in webhook_logs table with full payload
+ * @audit RELIABILITY: Critical for payment reconciliation - must be highly available
 */
 export async function POST(request: NextRequest) {
  try {