aperonight/README.md

# Aperonight - Event Booking Platform

![Aperonight Screenshot](app/assets/images/screenshot-homepage.png)

## 🌃 Overview

**Aperonight** is a comprehensive ticket selling system that connects event-goers with event organizers. The platform provides a complete solution for event booking, payment processing, and ticket management.

## 🎯 Key Features

### For Event-Goers
✅ **User Dashboard** - Personalized metrics showing booked events, upcoming events, and event statistics
✅ **Event Discovery** - Browse upcoming events with detailed information and venue details
✅ **Secure Booking** - Multiple ticket types per event with quantity selection
✅ **Stripe Integration** - Secure payment processing with credit/debit cards
✅ **PDF Tickets** - Automatically generated tickets with unique QR codes for each purchase
✅ **Download System** - Instant PDF ticket downloads after successful payment

### For Event Organizers
✅ **Event Management** - Create and manage events with detailed information
✅ **Ticket Type Configuration** - Set up multiple ticket types with different pricing
✅ **Sales Tracking** - Monitor ticket sales and availability
✅ **User Authentication** - Secure user registration and login system

### Technical Implementation
✅ **Payment Processing** - Full Stripe Checkout integration with session management
✅ **PDF Generation** - Custom PDF tickets with QR codes using Prawn library
✅ **Responsive Design** - Mobile-friendly interface with Tailwind CSS
✅ **Database Relations** - Proper user-event-ticket relationships

## 🛠 Technical Stack

### Backend
- **Ruby on Rails 8.0+** with Hotwire for reactive UI
- **MySQL** database with comprehensive migrations
- **Devise** for user authentication and session management
- **Kaminari** for pagination

### Frontend
- **Hotwire (Turbo + Stimulus)** for interactive JavaScript behavior
- **Tailwind CSS** for responsive styling and modern UI
- **JavaScript Controllers** for cart management and checkout flow

### Key Integrations
- **Stripe** for secure payment processing and checkout sessions
- **Prawn & Prawn-QRCode** for PDF ticket generation
- **RQRCode** for unique QR code generation per ticket

## 📊 Database Schema

```mermaid
erDiagram
    USER ||--o{ EVENT : creates
    USER ||--o{ TICKET : purchases
    USER {
        integer id
        string email
        string encrypted_password
        string first_name
        string last_name
    }
    EVENT ||--o{ TICKET_TYPE : has
    EVENT {
        integer id
        integer user_id
        string name
        string slug
        text description
        string venue_name
        string venue_address
        decimal latitude
        decimal longitude
        datetime start_time
        datetime end_time
        string state
        boolean featured
        string image
    }
    TICKET_TYPE ||--o{ TICKET : defines
    TICKET_TYPE {
        integer id
        integer event_id
        string name
        text description
        integer price_cents
        integer quantity
        datetime sale_start_at
        datetime sale_end_at
        boolean requires_id
        integer minimum_age
    }
    TICKET {
        integer id
        integer user_id
        integer ticket_type_id
        string qr_code
        integer price_cents
        string status
    }
```

## 🚀 Getting Started

### Prerequisites
- Ruby 3.4+
- Rails 8.0+
- MySQL/MariaDB
- Node.js 18+ (for asset compilation)
- Stripe account (for payment processing)

### Installation

1. **Clone the repository**
```bash
git clone https://github.com/yourusername/aperonight.git
cd aperonight
```

2. **Install dependencies**
```bash
bundle install
npm install
```

3. **Database setup**
```bash
rails db:create
rails db:migrate
rails db:seed
```

4. **Configure environment variables**
Create a `.env` file or configure Rails credentials:
```bash
# Stripe configuration
STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here
STRIPE_SECRET_KEY=sk_test_your_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# Database configuration (if not using defaults)
DATABASE_URL=mysql2://username:password@localhost/aperonight_development
```

5. **Start the development server**
```bash
rails server
```

Visit `http://localhost:3000` to see the application running.

## 💳 Payment Configuration

### Setting up Stripe

1. Create a Stripe account at [stripe.com](https://stripe.com)
2. Get your API keys from the Stripe Dashboard
3. Add your keys to the Rails credentials or environment variables
4. Configure webhook endpoints for payment confirmations:
   - Endpoint URL: `your-domain.com/stripe/webhooks`
   - Events: `checkout.session.completed`, `payment_intent.succeeded`

## 🎫 Core Functionality

### User Flow
1. **Registration/Login** - Users create accounts or sign in
2. **Event Discovery** - Browse events from the homepage or events page
3. **Ticket Selection** - Choose ticket types and quantities
4. **Checkout** - Secure payment through Stripe Checkout
5. **Ticket Generation** - Automatic PDF ticket generation with QR codes
6. **Download** - Instant ticket download after payment

### Event Management
1. **Event Creation** - Create events with full details and images
2. **Ticket Types** - Configure multiple ticket types with pricing
3. **Sales Tracking** - Monitor ticket sales through the dashboard

### Dashboard Features
- **Personal Metrics** - View booked events and upcoming events
- **Event Sections** - Today's events, tomorrow's events, and upcoming events
- **Quick Actions** - Easy navigation to event discovery and booking

## 🔧 Development

### Key Files Structure
```
app/
├── controllers/
│   ├── events_controller.rb      # Event listing, booking, checkout
│   └── pages_controller.rb       # Dashboard and static pages
├── models/
│   ├── user.rb                   # User authentication with Devise
│   ├── event.rb                  # Event management and states
│   ├── ticket_type.rb            # Ticket configuration
│   └── ticket.rb                 # Ticket generation with QR codes
├── services/
│   └── ticket_pdf_generator.rb   # PDF ticket generation service
└── views/
    ├── events/
    │   ├── show.html.erb          # Event details and booking
    │   └── payment_success.html.erb # Post-purchase confirmation
    └── pages/
        └── dashboard.html.erb     # User dashboard with metrics
```

### Key Routes
- `GET /` - Homepage
- `GET /dashboard` - User dashboard (authenticated)
- `GET /events` - Event listings
- `GET /events/:slug.:id` - Event details and booking
- `POST /events/:slug.:id/checkout` - Stripe checkout initiation
- `GET /payment/success` - Payment confirmation
- `GET /tickets/:ticket_id/download` - PDF ticket download