app/README.md

# 🍽️ Dish Planner

A Laravel-based meal planning application that helps households organize and schedule their dishes among multiple users. Built with Laravel, Livewire, and FrankenPHP for a modern, single-container deployment.

## ✨ Features

- **Multi-user dish management** - Assign dishes to specific household members
- **Smart scheduling** - Automatic schedule generation with recurrence patterns
- **Calendar view** - Visual 31-day schedule overview
- **Real-time updates** - Livewire-powered reactive interface
- **Dark theme UI** - Modern interface with purple/pink accents
- **Single container deployment** - Simplified hosting with FrankenPHP

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose
- Make (optional, for convenience commands)

### First Time Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/dish-planner.git
cd dish-planner

# Quick install with Make
make install

# Or manually:
cp .env.example .env
docker compose build
docker compose up -d
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate
```

The application will be available at **http://localhost:8000**

## 🔧 Development

### Starting the Development Environment

```bash
# Start all services
make dev

# Or with Docker Compose directly
docker compose up -d
```

**Available services:**
- **App**: http://localhost:8000 (Laravel + FrankenPHP)
- **Vite**: http://localhost:5173 (Asset hot-reload)
- **Mailhog**: http://localhost:8025 (Email testing)
- **Database**: localhost:3306 (MariaDB)

### Common Development Commands

```bash
# View logs
make logs                    # App logs
make logs-db                 # Database logs

# Laravel commands
make artisan cmd="migrate"  # Run artisan commands
make tinker                  # Start Laravel tinker
make test                    # Run tests

# Database
make migrate                 # Run migrations
make seed                    # Seed database
make fresh                   # Fresh migrate with seeds

# Utilities
make shell                   # Enter app container
make db-shell               # Enter database shell
make clear                  # Clear all caches
```

### Project Structure

```
dish-planner/
├── app/
│   ├── Livewire/          # Livewire components
│   │   ├── Auth/          # Authentication
│   │   ├── Dishes/        # Dish management
│   │   ├── Schedule/      # Schedule calendar
│   │   └── Users/         # User management
│   └── Models/            # Eloquent models
├── resources/
│   └── views/
│       └── livewire/      # Livewire component views
├── docker-compose.yml     # Development environment
├── docker-compose.prod.yml # Production environment
├── Dockerfile             # Production image
├── Dockerfile.dev         # Development image
└── Makefile              # Convenience commands
```

## 🚢 Production Deployment

### Building for Production

```bash
# Build production image
make prod-build

# Start production environment
make prod

# Or with Docker Compose
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
```

### Production Environment Variables

Required environment variables for production:

```env
# Required - Generate APP_KEY (see instructions below)
APP_KEY=base64:your-generated-key-here
APP_URL=https://your-domain.com

# Database Configuration
DB_DATABASE=dishplanner
DB_USERNAME=dishplanner
DB_PASSWORD=strong-password-here
DB_ROOT_PASSWORD=strong-root-password

# Optional Email Configuration
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS=noreply@your-domain.com
```

#### Generating APP_KEY

The APP_KEY is critical for encryption and must be kept consistent across deployments. Generate one using any of these methods:

**Option 1: Using OpenSSL (Linux/Mac/Windows with Git Bash)**
```bash
echo "base64:$(openssl rand -base64 32)"
```

**Option 2: Using Node.js (Cross-platform)**
```bash
node -e "console.log('base64:' + require('crypto').randomBytes(32).toString('base64'))"
```

**Option 3: Using Python (Cross-platform)**
```bash
python -c "import base64, os; print('base64:' + base64.b64encode(os.urandom(32)).decode())"
```

**Option 4: Online Generator**
Generate a random 32-character string at https://randomkeygen.com/ and prepend with `base64:`

⚠️ **Important**: Save this key securely! If lost, you won't be able to decrypt existing data.

### Deployment with DockGE

The production setup is optimized for DockGE deployment with just 2 containers:

1. **app** - Laravel application with FrankenPHP
2. **db** - MariaDB database

Simply import the `docker-compose.prod.yml` into DockGE and configure your environment variables.

## 🛠️ Technology Stack

- **Backend**: Laravel 12 with Livewire 3
- **Web Server**: FrankenPHP (PHP 8.3 + Caddy)
- **Database**: MariaDB 11
- **Frontend**: Blade + Livewire + Alpine.js
- **Styling**: TailwindCSS with custom dark theme
- **Assets**: Vite for bundling

## 📦 Docker Architecture

### Development (`docker-compose.yml`)
- **Hot reload** - Volume mounts for live code editing
- **Debug tools** - Xdebug configured for debugging
- **Email testing** - Mailhog for capturing emails
- **Asset watching** - Vite dev server for instant updates

### Production (`docker-compose.prod.yml`)
- **Optimized** - Multi-stage builds with caching
- **Secure** - No debug tools, proper permissions
- **Health checks** - Automatic container monitoring
- **Single container** - FrankenPHP serves everything

## 🔨 Make Commands Reference

```bash
# Development
make dev            # Start development environment
make dev-build      # Build and start development
make dev-stop       # Stop development environment
make dev-clean      # Stop and remove volumes (CAUTION)

# Production
make prod           # Start production environment
make prod-build     # Build production image
make prod-stop      # Stop production environment
make prod-logs      # Show production logs

# Laravel
make artisan cmd="..." # Run artisan command
make composer cmd="..." # Run composer command
make npm cmd="..."     # Run npm command
make migrate        # Run migrations
make seed           # Seed database
make fresh          # Fresh migrate and seed
make tinker         # Start tinker session
make test           # Run tests

# Utilities
make shell          # Enter app container
make db-shell       # Enter database shell
make logs           # Show app logs
make logs-db        # Show database logs
make clear          # Clear all caches
make optimize       # Optimize for production
```

## 🐛 Troubleshooting

### Container won't start
```bash
# Check logs
docker compose logs app

# Rebuild containers
docker compose build --no-cache
docker compose up -d
```

### Database connection issues
```bash
# Verify database is running
docker compose ps

# Check database logs
docker compose logs db

# Try manual connection
make db-shell
```

### Permission issues
```bash
# Fix storage permissions
docker compose exec app chmod -R 777 storage bootstrap/cache
```

### Clear all caches
```bash
make clear
# Or manually
docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
docker compose exec app php artisan route:clear
docker compose exec app php artisan view:clear
```

## 📄 License

This project is open-source software licensed under the [MIT license](LICENSE.md).

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

## 📞 Support

For issues and questions, please use the [GitHub Issues](https://github.com/yourusername/dish-planner/issues) page.

---

Built with ❤️ using Laravel and Livewire