# WAGW SaaS - Modern Laravel Docker Scaffold

WhatsApp Gateway Multi-Tenant Platform built with Laravel 12, Docker, PostgreSQL, Redis, and async queue workers.

## 🚀 Quick Start

### Prerequisites
- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/)
- [OrbStack](https://orbstack.dev/) (recommended for Mac)
- Git

### Development Setup

1. **Clone and navigate to project**
   ```bash
   cd /Applications/MAMP/htdocs/other/fpm/wagw-saas
   ```

2. **Start all services**
   ```bash
   docker compose up -d
   ```

3. **Install PHP dependencies** (first time only)
   ```bash
   docker compose exec app composer install
   ```

4. **Generate application key**
   ```bash
   docker compose exec app php artisan key:generate
   ```

5. **Run database migrations**
   ```bash
   docker compose exec app php artisan migrate
   ```

6. **Access the application**
   - Web: http://localhost:8088
   - API Health: http://localhost:8088/health
   - PostgreSQL: localhost:54328
   - Redis: localhost:63798
   - MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
   - GOWA: http://localhost:3000

## 📁 Project Structure

```
wagw-saas/
├── docker/                    # Docker configuration
│   ├── nginx/                # Nginx web server
│   │   ├── Dockerfile
│   │   └── conf.d/
│   └── php/                  # PHP-FPM application
│       ├── Dockerfile
│       └── php.ini
├── app/                      # Laravel application code
├── bootstrap/                # Application bootstrap
├── config/                   # Configuration files
├── database/                 # Migrations, seeders, factories
├── public/                   # Web root
├── resources/                # Views, translations, assets
├── routes/                   # Route definitions
├── storage/                  # Logs, cache, sessions
├── tests/                    # Test suites
├── .env.example              # Environment template
├── .env                      # Environment variables
├── composer.json             # PHP dependencies
├── artisan                   # Laravel CLI
├── docker-compose.yml        # Service orchestration
└── README.md                 # This file
```

## 🐳 Docker Services

| Service | Container | Port | Purpose |
|---------|-----------|------|---------|
| Web | `wagw-web` | 8088 | Nginx web server |
| App | `wagw-app` | 9000 | PHP-FPM Laravel application |
| PostgreSQL | `wagw-postgres` | 54328 | Primary database |
| Redis | `wagw-redis` | 63798 | Cache and queue |
| Worker | `wagw-worker` | - | Queue worker for async jobs |
| Scheduler | `wagw-scheduler` | - | Laravel scheduled tasks |
| MinIO | `wagw-minio` | 9000/9001 | S3-compatible object storage |
| GOWA | `wagw-gowa` | 3000 | WhatsApp Web multidevice engine |

## 🔧 Development Commands

### Docker Management
```bash
# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f [service]

# Rebuild containers
docker compose build

# Check service status
docker compose ps
```

### Application Commands
```bash
# Run inside app container
docker compose exec app [command]

# Install dependencies
docker compose exec app composer install

# Update dependencies
docker compose exec app composer update

# Run migrations
docker compose exec app php artisan migrate

# Run seeders
docker compose exec app php artisan db:seed

# Clear cache
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

# Generate key
docker compose exec app php artisan key:generate

# Run queue worker (if not using container)
docker compose exec app php artisan queue:work redis --tries=3 --backoff=10,60,300 --timeout=120

# Run scheduler (if not using container)
docker compose exec app php artisan schedule:work
```

### Database Access
```bash
# PostgreSQL shell
docker compose exec postgres psql -U wagw_user -d wagw_saas

# Redis CLI
docker compose exec redis redis-cli
```

## ⚙️ Environment Configuration

Copy `.env.example` to `.env` and configure:

```bash
# Database
DB_DATABASE=wagw_saas
DB_USERNAME=wagw_user
DB_PASSWORD=wagw_secret

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Queue
QUEUE_CONNECTION=redis

# MinIO (S3-compatible)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_ENDPOINT=http://minio:9000

# GOWA
GOWA_BASE_URL=http://gowa:3000
```

## 🧪 Testing

```bash
# Run tests
docker compose exec app php artisan test

# Run specific test
docker compose exec app php artisan test --filter=FeatureName
```

## 📚 Documentation

- `docs/PRD_MODERN_STACK.md` - Product requirements and architecture
- `docs/DESIGN_REFERENCE.md` - UI design system and tokens
- `docs/API.md` - API specifications
- `docs/DATABASE.md` - Database schema and models

## 🔐 Security Notes

- Never commit `.env` file
- Use strong passwords for production
- Configure proper firewall rules
- Enable HTTPS in production
- Regularly update dependencies

## 🚨 Troubleshooting

### Port Conflicts
If ports are already in use, modify `docker-compose.yml` port mappings.

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

### Database Connection
```bash
# Check PostgreSQL health
docker compose exec postgres pg_isready -U wagw_user

# Reset database
docker compose exec app php artisan migrate:fresh
```

### Container Issues
```bash
# Rebuild and restart
docker compose down
docker compose build --no-cache
docker compose up -d
```

## 📞 Support

- Check `docs/DEVELOPMENT.md` for development guidelines
- Review `AGENTS.md` for opencode agent configuration
- See `HINDSIGHT.md` for project memory and context

---

**Next Steps:**
1. Run `docker compose up -d` to start services
2. Install dependencies with `docker compose exec app composer install`
3. Generate app key and run migrations
4. Begin implementing features from `docs/PRD_MODERN_STACK.md`