cobalt-turf

As a UI/UX designer, I want to align all colors and theme tokens to the GoTurf brand palette so that the application has a cohesive visual identity. This includes configuring the design token system with Background #F4F9F4, Surface #E8F5E9, Text #1B5E20, Accent #FF6F00, Muted #BDBDBD, and applying them across all global components, shadows, borders, and interactive states.

As a user, I want to land on an engaging home page with an interactive India map so that I can visually explore and discover turf locations near me. The page should implement the v2 design including the hero section, location-based search entry, interactive SVG/map component highlighting turf-dense cities, featured listings carousel, multi-language toggle, and call-to-action sections.

As a user, I want a clean and accessible login page so that I can securely sign into my GoTurf account. This implements the v2 login design including the branded entry screen, input fields for credentials, social login options, forgot password link, role-aware redirect logic for Admin, Turf Owner, and User, and multi-language label support.

As an admin, I want a comprehensive dashboard overview so that I can monitor platform health, new registrations, pending approvals, and booking trends at a glance. This implements the v2 dashboard design with KPI cards, charts for bookings and revenue, recent activity feed, quick-action buttons to Users/Listings/Reports, and notification indicators.

As a user, I want to use the GoTurf platform in my preferred regional language so that the application is accessible to non-English speakers across India. Implement i18n using react-i18next with locale files for English, Hindi, Tamil, Telugu, Kannada, and Malayalam, language switcher component, and RTL layout fallback for supported locales.

As a user, I want a powerful search interface so that I can find turfs by location, sport type, date, time slot, and price range. This implements the v2 search page including the search bar with city autocomplete, filter panels for sport, amenities, price, and surface type, map-embedded search view, and recent searches history.

As an admin, I want to manage all registered users so that I can view profiles, deactivate accounts, resolve disputes, and ensure platform trust and safety. This implements the v2 users page with searchable and filterable user table, user detail drawer, account status toggle, role assignment, activity log view, and bulk action support.

As an admin, I want to review and approve turf listings so that only verified and quality turfs are available on the platform. This implements the v2 listings page with a table of all submitted turf listings, approval/rejection workflow with reason input, listing detail preview drawer, filter by status (pending, approved, rejected), and bulk approval actions.

As an admin, I want to access platform-wide reports so that I can analyze revenue, booking trends, top-performing turfs, and user growth metrics. This implements the v2 reports page with date-range picker, revenue and booking volume charts, downloadable CSV/PDF reports, leaderboard for top turfs, city-wise heatmap, and anomaly highlight indicators.

As a developer, I want FastAPI endpoints for user profile management so that users can update their personal information, preferences, and profile photo. Implement GET /users/{id}, PUT /users/{id}, profile photo upload to cloud storage, and user preferences storage in MySQL.

As a user, I want an interactive India map on the home page so that I can visually identify cities with available turfs and click to explore them. Implement an SVG or Mapbox-based India map with turf-density heatmap overlay, city hotspot click navigation to search results, animated markers for featured cities, and mobile-touch-friendly pan and zoom.

As a mobile user, I want a native mobile home screen with location-aware turf discovery so that I can quickly search and book turfs on my phone. Implement the React Native equivalent of the home page v2 design with device GPS integration, native bottom navigation, push notification permission prompt, and mobile-optimized map component.

As a user, I want to see a filtered list of available turfs so that I can compare options and choose the best fit for my game. This implements the v2 results page with turf cards showing thumbnail, rating, price per hour, distance, availability badge, sorting controls, pagination or infinite scroll, and map/list toggle view.

As a developer, I want a high-performance search API so that users can find turfs based on location, sport type, date, time, price range, and amenities. Implement GET /turfs/search with geospatial filtering using MySQL spatial indexes or MongoDB geo queries, full-text search, faceted filters, and paginated results with distance sorting.

As a developer, I want CRUD APIs for turf listings so that turf owners can create and manage their turf profiles and admins can approve or reject them. Implement POST /turfs, GET /turfs/{id}, PUT /turfs/{id}, PATCH /turfs/{id}/status for approval workflow, and image upload handling with cloud storage URLs stored in MongoDB.

As a developer, I want admin-only APIs for user management so that admins can list, search, suspend, and restore user accounts. Implement GET /admin/users with search and filter query params, PATCH /admin/users/{id}/status, GET /admin/users/{id}/activity-log, and role assignment endpoints with admin role guard middleware.

As a developer, I want reporting and analytics APIs so that admins can retrieve platform-wide metrics including booking volumes, revenue, user growth, and city-wise performance. Implement GET /admin/reports/bookings, GET /admin/reports/revenue, GET /admin/reports/users, GET /admin/reports/turfs with date range filters and CSV/PDF export endpoints.

As a user, I want to view a detailed turf profile so that I can make an informed booking decision based on amenities, photos, reviews, and real-time slot availability. This implements the v2 turf profile design with image gallery, sport and amenity tags, pricing table, availability calendar widget, owner info, ratings summary, and reviews list.

As a developer, I want a geolocation and mapping API so that the platform can resolve user coordinates to nearest city, compute turf distances, and serve city-level turf density data for the interactive map. Implement GET /geo/cities-density, GET /geo/nearest-turfs?lat=&lng=, and integrate Google Maps or Mapbox Geocoding API.

As a user, I want a streamlined booking flow so that I can select my preferred date, time slots, and sport type and confirm my reservation with clear pricing breakdown. This implements the v2 booking page with interactive slot grid showing real-time availability, multi-slot selection, booking summary panel, player count input, promo code entry, and proceed to payment CTA.

As a turf owner, I want to manage my turf's availability calendar so that I can block dates, define operating hours, set peak/off-peak pricing, and avoid double bookings. This implements the v2 availability page with weekly and monthly calendar grid, slot blocking tool, recurring availability pattern setup, and real-time sync indicator.

As a user, I want a secure and India-regulation-compliant payment page so that I can complete my turf booking using UPI, net banking, cards, or wallets. This implements the v2 payment page with order summary, multiple payment method tabs, UPI deep link integration, RazorPay/PayU embed, GST breakdown display, and success/failure confirmation states.

As a developer, I want real-time availability slot APIs so that users see up-to-date slot status and turf owners can define and block slots. Implement GET /turfs/{id}/slots?date=, POST /turfs/{id}/slots/block, DELETE /turfs/{id}/slots/block/{slot_id}, recurring availability patterns, and WebSocket or SSE channel for real-time slot status updates.

As a user or turf owner, I want to view all my bookings in one place so that I can track upcoming, ongoing, and past reservations. This implements the v2 bookings page with tabbed views for Upcoming, Completed, and Cancelled bookings, booking detail cards with status badges, cancellation and reschedule actions, and download invoice option.

As a developer, I want a robust booking API so that users can create, view, cancel, and reschedule bookings with proper conflict prevention. Implement POST /bookings with slot locking mechanism, GET /bookings?user_id=, GET /bookings?turf_id=, PATCH /bookings/{id}/cancel, PATCH /bookings/{id}/reschedule, and booking status state machine.

As a developer, I want an AI assistant API powered by GPT and Claude via Langchain/Litellm so that users can get smart turf recommendations, resolve booking queries, and get sport-specific suggestions through a conversational interface. Implement POST /ai/chat with session context, tool-calling for turf search and availability lookup, and streaming response support.

As a mobile user, I want a seamless native booking and payment experience so that I can complete a turf reservation without friction on my mobile device. Implement React Native screens for Turf Profile, Booking slot picker, and Payment with UPI intent deep links, native date/time pickers, and real-time slot availability updates via WebSocket.

As a user, I want to submit a review and rating after my turf session so that I can share my experience and help others make informed decisions. This implements the v2 review page with star rating selector, text feedback input, photo upload for the session, sport-specific rating dimensions (pitch quality, lighting, amenities), and submission confirmation.

As a turf owner, I want to view my earnings and payout details so that I can track revenue, understand platform fees, and request withdrawals. This implements the v2 earnings page with total earnings summary cards, booking-wise revenue table, payout history list, bank account management section, GST report export, and withdrawal request flow.

As a developer, I want a payment API that is compliant with Indian regulations so that users can pay via UPI, cards, net banking, and wallets with proper GST handling. Implement POST /payments/initiate, POST /payments/verify webhook, POST /payments/refund, integrate RazorPay or PayU SDK, store transaction records in MySQL, and generate GST-compliant invoices.

As a user, I want an embedded AI chat assistant widget on the platform so that I can ask questions about turfs, get personalized recommendations, and resolve booking issues without leaving the page. Implement the chat bubble UI, message thread with streaming token display, quick-action suggestion chips, and integration with the /ai/chat backend API.

As a developer, I want a reviews and ratings API so that users can submit post-session feedback and aggregated ratings are reflected on turf profiles. Implement POST /reviews, GET /reviews?turf_id=, GET /reviews?user_id=, PUT /reviews/{id}, aggregate rating computation, review moderation flags, and photo attachment storage.

As a developer, I want earnings and payout APIs for turf owners so that they can view revenue breakdowns, request withdrawals, and access GST reports. Implement GET /owner/earnings?turf_id=&date_range=, GET /owner/payouts, POST /owner/payouts/request, GET /owner/earnings/export, and platform fee deduction calculation logic.

As a developer, I want a notification service API so that users receive timely alerts for booking confirmations, payment status, cancellations, and reminders. Implement POST /notifications/send supporting push, SMS, and email channels, GET /notifications?user_id=, PATCH /notifications/{id}/read, and integrate Firebase Cloud Messaging for push delivery.