--- title: AGENTS.md --- # Home Spa Booking System --- AI Development Guidelines ## 1. Project Context Build a premium home-spa booking website for international tourists, especially English-speaking foreign guests visiting Lombok. Technology: - Laravel 12 - PHP - MySQL / MariaDB - Blade - Tailwind CSS - Alpine.js where useful - Vite - Laravel authentication - Responsive design, mobile-first The product is a direct-booking website, not a marketplace. Core customer promise: > Book a professional spa treatment at your hotel or villa. No > prepayment required. Pay your therapist directly on arrival. ## 2. Product Principles ### Human-first design The website must feel like a real local hospitality/spa business, not an AI-generated SaaS template. Avoid: - excessive gradients - glowing cards - glassmorphism everywhere - generic purple/blue AI aesthetics - excessive rounded cards - giant text surrounded by empty space - meaningless decorative blobs - excessive animation - stock-looking fake UI - repetitive cards with identical visual treatment - overly perfect symmetrical layouts Prefer: - editorial hospitality layouts - warm natural photography - restrained typography - generous but purposeful whitespace - subtle borders - real content - asymmetric image/text compositions - natural colors inspired by Lombok - clear booking CTAs - small details that communicate hospitality ## 3. Visual Direction Design reference: boutique resort / luxury villa / independent spa. Suggested visual character: - warm ivory / sand background - deep charcoal text - muted earth or botanical accent - natural wood / stone feeling - photography should carry much of the visual identity Do not force a tropical theme with clichés such as excessive palm leaves, turquoise gradients, or generic Bali imagery. Use a restrained palette. Example direction: - Ivory: #F7F3EC - Charcoal: #25231F - Warm brown: #8A6A4A - Muted sage: #7C8772 - Soft sand: #E6D9C8 These are references, not mandatory values. ## 4. Typography Use a refined combination: - elegant serif for selected headings - clean sans-serif for UI/body Possible fonts: - Cormorant Garamond / DM Serif Display for editorial headings - Inter / Manrope / DM Sans for UI Do not use huge headings on every section. Typography hierarchy should feel like hospitality branding, not a software dashboard. ## 5. Homepage Direction Recommended structure: 1. Slim announcement bar 2. Minimal navigation 3. Large photographic hero 4. Short brand statement 5. Featured treatments 6. "How it works" in 3 simple steps 7. Hotel/villa service section 8. Service area section 9. Customer reviews 10. Small FAQ 11. Strong final booking CTA 12. Footer Hero example: "Relax, wherever you stay." "Professional spa treatments delivered to your hotel or villa in Lombok." CTA: "Book a Treatment" Secondary: "Explore Treatments" Do not make the homepage look like a startup landing page. ## 6. Booking UX Booking is the primary conversion path. Flow: Treatment → Date → Time → Guests → Location → Customer details → Review → Confirm → Pay on arrival Payment copy: "Pay Directly to Your Therapist" "No prepayment required. Pay after your treatment." Never label this as "COD" in the customer-facing English UI. ## 7. Authentication Customers can register/login. Do not block browsing before login. Recommended: - Browse freely - Select treatment - Login/register before final booking - Return customer to the booking flow after authentication Support: - email - password - forgot password - profile - booking history ## 8. Booking Status Keep booking and payment status separate. Booking statuses: - pending - confirmed - assigned - on_the_way - in_progress - completed - cancelled - rescheduled Payment statuses: - unpaid - paid ## 9. Rescheduling Customer must be able to reschedule an upcoming booking. The system must: - check therapist/service availability - prevent overlapping bookings - show available dates/times - update booking history - notify admin - notify therapist if already assigned ## 10. Therapist UX Therapist interface should be extremely simple and mobile-friendly. Prioritize: - today's appointments - customer name - treatment - time - hotel/villa - room number - map - phone/contact - special request - mark status - mark payment received Avoid giving therapists unnecessary administrative complexity. ## 11. Admin UX Admin dashboard should prioritize operations. Important views: - today's bookings - upcoming bookings - unassigned bookings - therapist schedule - completed bookings - unpaid bookings - revenue/reporting Use tables and compact operational interfaces in admin. Do not apply the decorative public website design to the admin dashboard. ## 12. Engineering Rules - Use Laravel 12 conventions. - Prefer Laravel built-in features over unnecessary packages. - Keep controllers thin. - Put business logic into appropriate services/actions when complexity grows. - Use Form Requests for validation. - Use Policies/Gates for authorization. - Use Eloquent relationships clearly. - Use database transactions for booking operations. - Validate availability server-side, not only in JavaScript. - Prevent race conditions when creating bookings. - Never trust price values submitted by the browser. - Calculate totals from database records. - Store money as integer minor units where appropriate. - Use timezone-aware date/time handling. - Keep booking timestamps consistent. - Use queued jobs for non-critical notifications when appropriate. - Do not expose sensitive customer data unnecessarily. ## 13. Security Required: - CSRF protection - authorization policies - request validation - password hashing through Laravel - rate limiting where appropriate - secure file uploads - escaped output - no mass-assignment vulnerabilities - no trusting hidden form fields for permissions, prices, or ownership A customer must only access their own bookings. A therapist must only access bookings assigned to them. ## 14. UX Rules Every page must answer: - Where am I? - What can I do here? - What is the next action? Use obvious CTA labels: - Book a Treatment - View Treatment - Continue - Confirm Booking - Reschedule - Cancel Booking Avoid vague CTA labels such as: - Explore - Discover - Get Started when a more specific action is possible. ## 15. Responsive Rules Mobile is a first-class experience. Test: - 360px - 390px - 768px - 1024px - desktop Booking should be easy with one hand on mobile. Do not create horizontal scrolling. ## 16. Images Use real spa/hospitality photography whenever available. Prefer: - therapist preparing treatment - clean treatment room - natural oils/towels - hotel/villa setting - subtle Lombok environment - authentic therapist/customer interaction Avoid generic AI-looking spa images. If no final photography exists, use clearly replaceable image placeholders rather than pretending generic images are final brand assets. ## 17. Accessibility - semantic HTML - keyboard navigation - visible focus states - sufficient contrast - alt text - labels for forms - error messages beside relevant fields - do not rely on color alone ## 18. Copywriting Default public language: English. Tone: - warm - calm - professional - concise - welcoming - trustworthy Avoid: - exaggerated luxury claims - fake scarcity - overly salesy language - robotic marketing phrases - "AI-generated" sounding copy ## 19. Definition of Done A feature is not complete until: - desktop works - mobile works - validation works - authorization works - empty/error states exist - loading states exist where necessary - database constraints are considered - booking conflicts are handled - user-facing copy is understandable - no console errors remain - no placeholder content is accidentally presented as final content ## 20. Therapist Tracking The product may include a lightweight therapist tracking experience inspired by delivery/ride-hailing apps, but it must not become a Gojek clone. Purpose: - reassure the customer that the therapist is coming - provide approximate location/ETA - help the customer know when the therapist has arrived Recommended MVP behavior: - therapist explicitly starts tracking by pressing "I'm On My Way" - browser requests location permission - therapist location is sent periodically while the tracking page is active - customer can open "Track Your Therapist" - customer sees therapist location, approximate distance/ETA when available, and booking status - therapist can press "I've Arrived" - tracking stops when the therapist arrives or the booking is cancelled/completed Important browser limitation: - Do not promise continuous background GPS tracking like a native Gojek application. - Browser geolocation can be restricted when a tab is closed or backgrounded. - The UI must gracefully handle unavailable/stale location. Tracking states: - preparing - on_the_way - arriving_soon - arrived Customer-facing copy: - "Your therapist is on the way." - "Track Your Therapist" - "Estimated arrival" - "Your therapist has arrived." Therapist-facing actions: - "I'm On My Way" - "Open Navigation" - "I've Arrived" Privacy: - only expose therapist location to the relevant customer for the active booking - do not expose therapist location publicly - minimize location retention - stop tracking when no longer operationally necessary - protect location endpoints with authorization policies Technical direction: - browser Geolocation API for MVP - Leaflet + OpenStreetMap can be used for an initial map implementation - Google Maps or Mapbox may be introduced later for improved routing/ETA - realtime/WebSocket infrastructure can be introduced in V2 if true live updates are required - never trust client-submitted booking ownership or therapist identity Database concept: therapist_locations: - id - booking_id - therapist_id - latitude - longitude - accuracy - recorded_at Tracking should be designed as an operational hospitality feature, not a marketing gimmick.