# Hangoutly - AI-Powered Group Event Planning Platform

## Project Overview

Hangoutly is a comprehensive AI-powered group event planning platform that revolutionizes how friends coordinate activities. Built with modern web technologies and enhanced with intelligent suggestions, real-time collaboration, and seamless multi-platform deployment.

**Live Demo**: https://hangoutly.pages.dev
**Repository**: https://github.com/p4r1ch4y/hangoutly_aryatechies
**Documentation**: https://hangoutly.pages.dev/docs/
**AI Integration Guide**: https://hangoutly.pages.dev/docs/AI_INTEGRATION.md

## Key Features

- **AI-Enhanced Planning**: Intelligent suggestions powered by Hugging Face models with rule-based fallbacks
- **Real-Time Collaboration**: Live chat, polling, and RSVP tracking using Supabase real-time subscriptions
- **Multi-Platform Deployment**: Supports Vercel, Netlify, and Cloudflare deployment
- **Progressive Web App**: Offline-capable with native app-like experience
- **Zero-Signup Participation**: Friends can join and participate without creating accounts
- **Specialized Planning Types**: Movies, food, trips, house hunting with NoBroker integration
- **Hybrid Database Architecture**: Supabase PostgreSQL primary with D1 SQLite fallback

## Technology Stack

**Frontend**: Vanilla JavaScript + Tailwind CSS + PWA
**Backend**: Hono.js Framework (v4.10.3)
**Database**: Supabase PostgreSQL (primary) + Cloudflare D1 (fallback)
**Authentication**: Supabase Auth with Google OAuth
**AI/ML**: Hugging Face Inference API + Enhanced Rule Engine
**Real-time**: Supabase Realtime subscriptions
**Deployment**: Multi-platform (Vercel, Netlify, Cloudflare)

## API Endpoints

### Authentication
- POST /api/auth/signup - Supabase user registration
- POST /api/auth/signin - Supabase authentication
- GET /api/auth/google - Google OAuth via Supabase
- GET /api/auth/user - Get current user profile
- POST /api/auth/signout - Sign out user

### Plans Management
- GET /api/plans - Get all public plans (hybrid database)
- GET /api/plans/:id - Get plan details with participants, chat, polls
- POST /api/plans - Create new plan with AI suggestions
- POST /api/plans/:id/participants - Join plan as participant
- PUT /api/plans/:id/rsvp - Update RSVP status (attending/maybe/declined)

### Real-Time Features
- POST /api/plans/:id/chat - Send chat message (triggers real-time updates)
- POST /api/plans/:id/reactions - Add emoji reaction to messages
- POST /api/polls/:optionId/vote - Vote on poll options

### AI Integration
- POST /api/chatbot - Enhanced AI assistant with context awareness
  - Supports plan types: movie, outing, trip, house, food
  - Mood-based responses: chill, adventurous, foodie
  - Hugging Face models: GPT-2, DialoGPT-Small, BlenderBot-400M
  - Fallback to enhanced rule-based system

### Smart Suggestions
- GET /api/suggestions/movies - Movie recommendations by mood/location
- GET /api/suggestions/restaurants - Restaurant suggestions by cuisine/mood
- GET /api/suggestions/activities - Activity recommendations by type/mood

### House Hunting (NoBroker Integration)
- GET /api/nobroker/search - Property search with filters
- GET /api/nobroker/property/:id - Property details
- POST /api/plans/:id/properties - Add property to house hunt plan
- POST /api/properties/:propertyHuntId/vote - Vote on properties
- GET /api/plans/:id/properties - Get properties for house hunt plan

### Social Features
- POST /api/plans/:id/share - Track social media shares
- POST /api/notifications/subscribe - Push notification subscription

### System Information
- GET /health - Health check endpoint
- GET /api/info - Structured platform information (JSON)
- GET /llm.txt - AI-readable documentation (this file)
- GET /.well-known/ai.txt - AI agent discovery file

## AI Chatbot Integration

### Context-Aware Responses

The AI chatbot understands context from:
- Plan type (movie, outing, trip, house, food)
- User mood (chill, adventurous, foodie)
- Plan title and description
- Conversation history (last 8 messages per user)
- Group dynamics and participant count

### Example API Usage

```javascript
// AI Chatbot Request
POST /api/chatbot
Content-Type: application/json

{
  "message": "Help me plan a movie night for 6 friends",
  "planId": "uuid-plan-id",
  "context": {
    "planType": "movie",
    "mood": "chill",
    "groupSize": 6,
    "location": "Bangalore"
  },
  "userId": "user-123"
}

// Response
{
  "response": "🎬 Perfect for a chill movie night with 6 friends! I can suggest some great feel-good movies that work well for groups...",
  "suggestions": [
    "Consider comedy or adventure movies for group viewing",
    "Set up polls for movie selection and snack preferences",
    "Plan for comfortable seating arrangements"
  ],
  "metadata": {
    "responseType": "contextual",
    "model": "huggingface-gpt2",
    "confidence": 0.85
  }
}
```

### Supported AI Capabilities

- **Natural Language Processing**: Understands planning-related queries
- **Context Retention**: Maintains conversation history per user
- **Mood-Based Responses**: Adapts tone based on plan mood
- **Smart Suggestions**: Provides actionable planning recommendations
- **Multi-Modal Responses**: Text + structured suggestions + metadata
- **Graceful Fallbacks**: Rule-based responses when AI models unavailable

## Database Schema

### Core Tables (Supabase PostgreSQL)

**user_profiles**: User accounts with Supabase Auth integration
- id (uuid), email, name, avatar_url, location, interests

**plans**: Event plans with comprehensive metadata
- id (uuid), title, type, description, date_time, owner_id, mood, is_public

**participants**: Plan membership and RSVP tracking
- id (uuid), plan_id, user_id, name, email, rsvp_status, joined_at

**chat_messages**: Real-time messaging with AI bot support
- id (uuid), plan_id, user_id, sender_name, message, message_type, created_at

**poll_options**: Voting options for group decisions
- id (uuid), plan_id, option_type, option_text, votes

**house_hunt_properties**: Property listings for house hunting plans
- id (uuid), plan_id, property_id, property_title, votes_up, votes_down

### Real-Time Features

- **Live Chat**: Instant messaging with AI bot participation
- **Poll Updates**: Real-time vote counting and results
- **Participant Changes**: Live RSVP updates and new joiners
- **Reactions**: Emoji reactions to messages and plans

## Authentication & Security

### Supabase Authentication
- Email/password registration and login
- Google OAuth integration
- JWT-based session management
- Row Level Security (RLS) policies

### Guest Participation
- No signup required for basic participation
- Name-based identification (stored in localStorage)
- Limited access to voting, chat, and RSVP features

### Security Features
- Input validation and sanitization
- Rate limiting on API endpoints
- HTTPS enforcement
- XSS and CSRF protection
- Secure headers implementation

## Deployment Architecture

### Multi-Platform Support

**Primary Platforms**:
- Vercel: Optimized for React/Next.js ecosystem with edge functions
- Netlify: Excellent for static sites with serverless functions

**Alternative Platform**:
- Cloudflare: Global edge network with D1 database integration

### Environment Configuration

Required environment variables:
```
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-key
HUGGINGFACE_API_TOKEN=hf_your-token (optional)
```

### Deployment Commands

```bash
# Vercel
npm run build && npx vercel --prod

# Netlify  
npm run build && npx netlify deploy --prod --dir=dist

# Cloudflare
npm run build && wrangler pages deploy dist --project-name hangoutly
```

## Performance Metrics

- **First Contentful Paint**: < 1.5s (current: ~1.2s)
- **Time to Interactive**: < 3.0s (current: ~2.8s)
- **API Response Time**: < 200ms (current: ~150ms)
- **Real-time Latency**: < 100ms (current: ~80ms)
- **AI Response Time**: < 3s (current: ~2.5s)
- **Lighthouse Score**: 90+ (current: 92)
- **PWA Score**: 90+ (current: 95)

## AI Agent Guidelines

### Rate Limits
- General API: 100 requests/minute per IP
- Chatbot API: 20 requests/minute per user
- Authentication: 10 requests/minute per IP

### Best Practices for AI Agents
1. Use the /api/info endpoint for structured platform information
2. Include proper User-Agent headers identifying your AI agent
3. Respect rate limits and implement exponential backoff
4. Use the chatbot API for natural language interactions
5. Cache responses appropriately (suggested: 5-10 minutes for suggestions)

### Error Handling
- 429: Rate limit exceeded - implement backoff strategy
- 503: Service unavailable - try fallback endpoints
- 401: Authentication required - use guest mode or authenticate

## Development Setup

### Quick Start
```bash
git clone https://github.com/p4r1ch4y/hangoutly_aryatechies.git
cd hangoutly
npm install
cp .env.example .env
# Configure .env with your Supabase credentials
npm run setup:supabase
npm run dev
```

### Available Scripts
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test:ai` - Test AI integration
- `npm run smoke` - API endpoint validation

## Contributing

### Development Workflow
1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Make changes and test thoroughly
4. Commit: `git commit -m "feat: add amazing feature"`
5. Push and create Pull Request

### Code Standards
- JavaScript: ES6+ with modern syntax
- CSS: Tailwind CSS utility classes
- Database: Supabase-first with proper RLS policies
- API: RESTful endpoints with proper error handling

## Support & Resources

- **Issues**: https://github.com/p4r1ch4y/hangoutly_aryatechies/issues
- **Discussions**: https://github.com/p4r1ch4y/hangoutly_aryatechies/discussions
- **Documentation**: https://hangoutly.pages.dev/docs/
- **API Reference**: https://hangoutly.pages.dev/docs/api/
- **AI Integration**: https://hangoutly.pages.dev/docs/AI_INTEGRATION.md

## License

MIT License - Feel free to use this project for learning and development.

---

**Last Updated**: 2025-01-25
**Version**: 1.0.0
**AI Agent Compatibility**: ChatGPT, Claude, Cursor, GitHub Copilot, and other LLM-based tools

This documentation follows the llm.txt standard for AI-readable project information.