5CRSE5CRSEDocumentation
← Back to site

#5CRSE Premium Transportation & Experience Platform

Welcome to 5CRSE, a platform focused on providing premium transportation and curated experiences centered around events. Built with Payload CMS and integrating AI capabilities (potentially including Hume AI), this platform offers a sophisticated interface for customers and robust operational management tools for administrators, drivers, and ambassadors.

#Core Focus

5CRSE connects people with events by offering:

  • Luxury Transportation Services: A managed fleet for reliable, high-end transport.
  • Curated Experience Packages: Pre- and post-event dining, entertainment, and VIP access through partner venues.
  • Personalized Coordination: On-site ambassadors ensuring a seamless customer journey.

#Features

  • Transportation & Experience Booking: Customers can book standalone transport, experiences, or combined packages.
  • Operational Management Dashboards: Admins manage fleets, drivers, ambassadors, partner venues, packages, and bookings via Payload CMS.
  • Role-Based Access Control: Secure access for Customers, Admins, Drivers, and Ambassadors.
  • Payment Integration: Secure payments via Stripe.
  • (Potential) AI Agent Assistance:
    • Customer Service Agent: Assists users with booking inquiries, availability checks.
    • Business Manager Agent: Provides operational insights and assists admins with management tasks.
  • (Potential) Empathic Voice Interface: Leveraging Hume AI for natural interactions (if integrated).
  • Dining Integration (Optional): Potential OpenTable API integration for including restaurant reservations in packages.
  • Interaction Analytics: Logging interactions and potentially sentiment (especially if Hume AI is used).

#Getting Started

#Prerequisites

  • Node.js v20.9.0+
  • PNPM
  • Postgres (via Supabase or Docker)
  • Stripe API Keys
  • (Optional) Hume AI account with API keys
  • (Optional) OpenTable API credentials (if dining features are implemented)
  • (Optional) Mapping/Routing API Keys (e.g., Google Maps)

#Installation

  1. Clone the repository:

    git clone https://github.com/yourusername/5crse.git
cd 5crse

  2. Install dependencies:

    pnpm install

  3. Set up environment variables in .env:

    # Database connection
DATABASE_URL=postgresql://postgres:postgres@localhost:54323/5crse

# Server Configuration
PORT=3006

# Payload CMS
PAYLOAD_SECRET=your-payload-secret-key
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3006

# Payment Processing
STRIPE_SECRET_KEY=your-stripe-secret-key
STRIPE_WEBHOOKS_ENDPOINT_SECRET=your-stripe-webhook-secret

# AI Provider keys (If applicable)
# OPENAI_API_KEY=your-openai-api-key
# OPENAI_MODEL=gpt-4-turbo
# ANTHROPIC_API_KEY=your-anthropic-api-key
# PERPLEXITY_API_KEY=your-perplexity-api-key
# HUME_API_KEY=your-hume-api-key
# HUME_SECRET_KEY=your-hume-secret-key

# OpenTable Integration (If applicable)
# OPENTABLE_API_KEY=your-opentable-api-key
# OPENTABLE_PARTNER_ID=your-opentable-partner-id
# OPENTABLE_SECRET=your-opentable-secret

# Mapping/Routing API Key (If applicable)
# GOOGLE_MAPS_API_KEY=your-google-maps-key

  4. Start the development server:

    # First, make sure port 3006 is available
lsof -i :3006 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Then start the server
pnpm dev

  5. Access the Admin UI at http://localhost:3006/admin

  6. Access the Customer Frontend at http://localhost:3006

  7. (If built) Access the AI assistant at http://localhost:3006/ai-assistant

#Architecture

The application is built on a modern stack focused on operational efficiency and premium user experience:

  • Frontend: Next.js with React.
  • Backend & CMS: Payload CMS (headless) managing operational data (fleet, personnel, bookings, partners) and content.
  • Database: PostgreSQL (@payloadcms/db-postgres).
  • Styling: Tailwind CSS (potentially with Radix/shadcn/ui).
  • Payments: Stripe (@payloadcms/plugin-stripe or direct SDK).
  • (Potential) AI Integration: Via Model Context Protocol (MCP) Server, potentially using Hume AI, OpenAI, etc.
  • Testing: Vitest, Playwright/Cypress.

The architecture supports distinct interfaces/dashboards for Customers, Admins, Drivers, and Ambassadors, all powered by the central Payload backend.

#AI Integration Components (If Implemented)

  1. (Optional) HumeAIService: Service for interacting with Hume AI's API for empathic voice/text analysis.
  2. MCP Server & Tools: Handles function calling based on the Model Context Protocol. Key tools include:
    • Customer Service: get_available_vehicles, search_experience_packages, create_booking, check_booking_status, get_ambassador_details, check_dining_availability.
    • Business Manager: add_vehicle, assign_driver, add_ambassador, assign_ambassador, add_partner_venue, create_experience_package, get_business_metrics, track_ambassador_performance.
  3. AI Interaction Storage: Payload collection (ai-interactions) to log conversations, tool usage, and feedback.

#(Optional) OpenTable Integration

  • An OpenTableService can be implemented to handle restaurant availability checks and reservations as part of experience packages.

#Role-Based Access Control

A comprehensive permission system controls access based on roles (Customer, Admin, Driver, Ambassador) to relevant resources (bookings, vehicles, schedules, etc.).

#Agent Personalities (If Hume AI Implemented)

#Customer Service Agent

Designed to be warm, friendly, and helpful while maintaining a professional demeanor.

Personality Traits (Scale 1-10):

  • Warmth: 9/10
  • Competence: 8/10
  • Formality: 5/10
  • Enthusiasm: 8/10
  • Assertiveness: 6/10
  • Humor: 7/10

Voice Model: FINLEY (Warm, friendly voice)

#Business Manager Agent

Provides data-driven insights, operational support, and decision-making assistance.

Personality Traits (Scale 1-10):

  • Warmth: 6/10
  • Competence: 10/10
  • Formality: 8/10
  • Enthusiasm: 6/10
  • Assertiveness: 9/10
  • Humor: 4/10

Voice Model: SKY (Professional, authoritative voice)

#API Reference

#Core REST/GraphQL API

  • Provided by Payload CMS for managing collections (Vehicles, Drivers, Ambassadors, Venues, Packages, Bookings, Users, etc.). Refer to Payload documentation.

#(Optional) AI Interaction API

POST /api/ai/interact

Request Body Example:

{
  "message": "I'd like to book tickets for a concert",
  "agentType": "customer_service",
  "sessionId": "optional-session-id"
}

#(Optional) MCP Tool Execution API

POST /api/ai/execute-tool (or similar MCP endpoint)

Request Body Example:

{
  "toolId": "get_available_vehicles",
  "agentType": "customer_service",
  "args": {
    "eventDate": "2025-05-10",
    "eventTime": "19:00",
    "location": { "lat": 40.7128, "lon": -74.0060 },
    "passengerCount": 4
  },
  "sessionId": "optional-session-id"
}

#User Interfaces

  • Customer Frontend: / - Browse events, packages, book services, manage profile.
  • Admin Dashboard: /admin - Payload Admin UI for managing all operational aspects.
  • (Potential) Driver/Ambassador Portals: Role-specific interfaces for viewing schedules, assignments, etc.
  • (Potential) AI Assistant UI: /ai-assistant - Interface for interacting with AI agents.

#Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

#License

This project is licensed under the MIT License - see the LICENSE file for details.

#Acknowledgments

  • Payload CMS for the headless CMS and application framework.
  • Stripe for payment processing.
  • (Optional) Hume AI for empathic AI capabilities.
  • (Optional) OpenTable for dining reservations.

For more detailed technical documentation, see:

#Database Migration

This project provides tools to migrate data from a MySQL database to PostgreSQL. For detailed instructions, see MIGRATION.md.

#Quick Migration

To quickly migrate data from MySQL to PostgreSQL:

  1. Ensure you have the MySQL database dump file (.context/aystate-db.sql)
  2. Update your .env file with MySQL connection details
  3. Run the complete migration script:
pnpm migrate:complete

This will:

  • Fix any syntax issues in the codebase
  • Install the necessary dependencies
  • Check if the PostgreSQL Docker container is running
  • Migrate the data from MySQL to PostgreSQL
  • Restart the application

#Individual Migration Steps

If you prefer to run the migration steps individually:

  1. Fix syntax issues: pnpm fix:syntax
  2. Install migration dependencies: pnpm migrate:install
  3. Run the migration: pnpm migrate:run

#Development

#Available Scripts

  • pnpm dev - Start the development server on port 3006
  • pnpm build - Build the application for production
  • pnpm start - Start the production server
  • pnpm test - Run tests
  • pnpm test:e2e - Run end-to-end tests with Playwright
  • pnpm migrate:complete - Run the complete database migration process

#Directory Structure

  • src/ - Source code
    • collections/ - Payload CMS collections (Vehicles, Drivers, Ambassadors, Venues, Packages, Bookings, Users, AIInteractions, etc.)
    • globals/ - Payload CMS globals
    • components/ - Shared React components
    • scripts/ - Utility/migration scripts
    • app/ - Next.js app directory (Frontend routes)
    • endpoints/ - Custom Payload API endpoints (e.g., for OpenTable proxy)
    • services/ - Backend service classes (e.g., FleetManagementService, OpenTableService, HumeAIService)
    • access/ - Payload access control functions
    • hooks/ - Payload hooks
    • payload.config.ts - Main Payload CMS configuration
    • server.ts - Express server setup
  • public/ - Static assets
  • media/ - Uploaded media files (if using local storage)
  • tests/ - Test files

#Deployment

The application can be deployed using Docker Compose:

docker-compose up -d

This will start the application and PostgreSQL database.