# Hubwallet Payment Portal API

A payment portal API built with FastAPI, featuring PostgreSQL, SQLAlchemy, Alembic migrations, Celery background tasks, and Docker support for seamless payment processing.

## 🚀 Features

- **FastAPI** with async support
- **PostgreSQL** database with SQLAlchemy ORM
- **Alembic** for database migrations
- **Celery** with RabbitMQ and Redis for background task processing
- **Docker & Docker Compose** for easy deployment
- **Pydantic** for data validation
- **Structured project layout** with modular architecture
- **Health checks** and monitoring endpoints
- **CORS** middleware configuration
- **Environment-based configuration**

## 📁 Project Structure

```
hw-payment-portal-api/
├── .env.sample                # Environment variables template
├── requirements.txt            # Python dependencies
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Multi-container setup
├── alembic.ini                # Alembic configuration
├── migrations/                # Database migrations
│   ├── env.py                 # Alembic environment
│   └── versions/              # Migration versions
├── src/                       # Application source code
│   ├── main.py                # FastAPI app entry point
│   ├── api/                   # API layer
│   │   ├── __init__.py
│   │   ├── api.py             # Main API router
│   │   └── dependencies.py    # API dependencies
│   ├── apps/                  # Application modules
│   │   └── example/           # Example CRUD app
│   │       ├── __init__.py
│   │       ├── models.py      # SQLAlchemy models
│   │       ├── schemas.py     # Pydantic schemas
│   │       ├── crud.py        # CRUD operations
│   │       └── router.py      # API routes
│   ├── database/              # Database configuration
│   │   ├── __init__.py
│   │   └── session.py         # SQLAlchemy setup
│   ├── core/                  # Core utilities
│   ├── events/                # Event handlers
│   ├── plugins/               # Plugin system
│   ├── views/                 # Views and templates
│   ├── webhooks/              # Webhook handlers
│   └── worker/                # Celery background workers
│       ├── __init__.py
│       ├── celery_app.py      # Celery application factory
│       ├── config.py          # Celery configuration
│       └── tasks.py           # Background tasks
└── README.md                  # This file
```

## 🛠️ Quick Start

### Prerequisites

- Docker and Docker Compose
- Python 3.12+ (for local development)

### 1. Clone and Setup

```bash
# Clone or create the project
cd hw-payment-portal-api

# Copy environment file
cp .env.sample .env

# Edit .env file with your configurations (optional for development)
```

### 2. Run with Docker (Recommended)

```bash
# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up --build -d
```

The application will be available at:
- **API**: http://localhost:8000
- **Docs**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **Health Check**: http://localhost:8000/health
- **RabbitMQ Management**: http://localhost:15672 (guest/guest)

### 3. Background Tasks with Celery

This boilerplate includes Celery for background task processing:

```bash
# Check Celery worker status
docker-compose exec celery_worker celery -A src.worker.celery_app:celery_app inspect ping

# Monitor Celery tasks
docker-compose logs celery_worker

# Test background task via API
curl -X POST "http://localhost:8000/api/v1/tasks/send-welcome-email" \
     -H "Content-Type: application/json" \
     -d '{"user_email": "test@example.com", "user_name": "Test User"}'

# Check task status
curl "http://localhost:8000/api/v1/tasks/{task_id}/status"
```

**Available Services:**
- **FastAPI App**: Web application server
- **Celery Worker**: Background task processor
- **RabbitMQ**: Message broker for task queuing
- **Redis**: Result backend and caching
- **PostgreSQL**: Primary database

### 3. Database Migrations

```bash
# Create a new migration
docker-compose exec web alembic revision --autogenerate -m "Initial migration"

# Run migrations
docker-compose exec web alembic upgrade head

# Check migration status
docker-compose exec web alembic current
```

### 4. Local Development Setup

```bash
# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL="postgresql+psycopg://postgres:password@localhost:5432/fastapi_db"
export APP_HOST="0.0.0.0"
export APP_PORT="8000"

# Run database (you can use docker-compose for just the database)
docker-compose up db -d

# Run migrations
alembic upgrade head

# Start the application
python src/main.py
# or
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

## 🔧 Configuration

### Environment Variables

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

```bash
# Database
DATABASE_URL=postgresql+psycopg://postgres:password@db:5432/fastapi_db
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=fastapi_db

# Application
APP_HOST=0.0.0.0
APP_PORT=8000
APP_DEBUG=True

# JWT
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRES=30

# Celery (Background Tasks)
CELERY_BROKER_URL=amqp://guest:guest@rabbitmq:5672//
CELERY_RESULT_BACKEND=redis://redis:6379/0
CELERY_TASK_DEFAULT_QUEUE=default
CELERY_TASK_ALWAYS_EAGER=false
CELERY_LOG_LEVEL=INFO
```

### Docker Services

The application uses these Docker services:

| Service | Purpose | Port | Health Check |
|---------|---------|------|--------------|
| `web` | FastAPI application | 8000 | `/health` endpoint |
| `celery_worker` | Background task processor | - | Celery ping |
| `db` | PostgreSQL database | 5432 | `pg_isready` |
| `rabbitmq` | Message broker | 5672, 15672 | RabbitMQ diagnostics |
| `redis` | Result backend & cache | 6379 | Redis ping |

## 📋 Usage Examples

### Background Tasks

The application includes example Celery tasks for background processing:

```python
# Example: Trigger a welcome email task
POST /api/v1/tasks/send-welcome-email
{
    "user_email": "user@example.com",
    "user_name": "John Doe"
}

# Response
{
    "message": "Welcome email task queued successfully",
    "task_id": "abc123-def456-789ghi",
    "status": "queued"
}

# Check task status
GET /api/v1/tasks/{task_id}/status

# Response
{
    "task_id": "abc123-def456-789ghi",
    "status": "SUCCESS",
    "result": {
        "email": "user@example.com",
        "name": "John Doe",
        "status": "sent",
        "timestamp": 1640995200
    }
}
```

### Adding New Tasks

Create new tasks in `src/worker/tasks.py`:

```python
@celery_app.task(bind=True, name="my_custom_task")
def my_custom_task(self, param1: str, param2: int) -> dict:
    """Custom background task"""
    # Your task logic here
    return {"result": "success", "processed": param1}
```

### Task Queues (Future Expansion)

The setup is ready for multiple queues:

```python
# Route tasks to specific queues
app.conf.task_routes = {
    'src.worker.tasks.send_welcome_email': {'queue': 'emails'},
    'src.worker.tasks.generate_report': {'queue': 'reports'},
    '*': {'queue': 'default'},
}
```
JWT_REFRESH_EXPIRES=7
```

## 📊 API Endpoints

### Health Checks
- `GET /health` - Application health check
- `GET /api/v1/health` - API health check
- `GET /api/v1/examples/health/database` - Database connection check

### Example CRUD Operations
- `GET /api/v1/examples/` - List all items
- `POST /api/v1/examples/` - Create new item
- `GET /api/v1/examples/{id}` - Get item by ID
- `PUT /api/v1/examples/{id}` - Update item
- `DELETE /api/v1/examples/{id}` - Delete item

### Interactive Documentation
- `GET /docs` - Swagger UI
- `GET /redoc` - ReDoc documentation

## 🗄️ Database Operations

### Create a new migration
```bash
docker-compose exec web alembic revision --autogenerate -m "Add new table"
```

### Apply migrations
```bash
docker-compose exec web alembic upgrade head
```

### Rollback migration
```bash
docker-compose exec web alembic downgrade -1
```

### Check current migration
```bash
docker-compose exec web alembic current
```

### View migration history
```bash
docker-compose exec web alembic history
```

## 🧪 Testing the API

### Using curl

```bash
# Health check
curl http://localhost:8000/health

# Create an item
curl -X POST "http://localhost:8000/api/v1/examples/" \
     -H "Content-Type: application/json" \
     -d '{"name": "Test Item", "description": "A test item"}'

# Get all items
curl http://localhost:8000/api/v1/examples/

# Get specific item
curl http://localhost:8000/api/v1/examples/1
```

### Using Python requests

```python
import requests

# Health check
response = requests.get("http://localhost:8000/health")
print(response.json())

# Create item
data = {"name": "Test Item", "description": "A test item"}
response = requests.post("http://localhost:8000/api/v1/examples/", json=data)
print(response.json())
```

## 🚀 Deployment

### Production Environment

1. **Update environment variables** in `.env`:
   ```bash
   APP_DEBUG=False
   DATABASE_URL=postgresql+psycopg://user:password@prod-db:5432/prod_db
   JWT_SECRET_KEY=your-super-secure-jwt-secret-key
   ```

2. **Update docker-compose.yml** for production:
   - Remove volume mounts for live reloading
   - Use environment variables from secure sources
   - Configure proper networks and security groups

3. **Run migrations**:
   ```bash
   docker-compose exec web alembic upgrade head
   ```

4. **Use production WSGI server** (uncomment in Dockerfile):
   ```dockerfile
   CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
   ```

### Docker Commands

```bash
# Build only
docker-compose build

# View logs
docker-compose logs web
docker-compose logs db

# Execute commands in containers
docker-compose exec web bash
docker-compose exec db psql -U postgres -d fastapi_db

# Stop services
docker-compose down

# Remove volumes (⚠️ deletes data)
docker-compose down -v
```

## 🛠️ Development

### Adding New Apps

1. Create new app directory:
   ```bash
   mkdir -p src/apps/your_app
   touch src/apps/your_app/__init__.py
   ```

2. Create models, schemas, CRUD, and router files
3. Import models in `migrations/env.py`
4. Include router in `src/api/api.py`

### Project Extensions

- **Authentication**: Add JWT authentication in `src/apps/auth/utils/auth.py`
- **Background Tasks**: ✅ Celery workers implemented in `src/worker/`
- **Caching**: Add Redis caching layer (Redis is already available)
- **Testing**: Add pytest configuration and test cases
- **Logging**: Configure structured logging
- **Monitoring**: Add Prometheus metrics

## � Celery Development & Troubleshooting

### Common Commands

```bash
# Start only web app and dependencies (without worker)
docker-compose up web db rabbitmq redis

# Start only the Celery worker
docker-compose up celery_worker

# View Celery worker logs
docker-compose logs -f celery_worker

# Restart Celery worker after code changes
docker-compose restart celery_worker

# Test Celery connectivity
docker-compose exec celery_worker celery -A src.worker.celery_app:celery_app inspect ping

# List active tasks
docker-compose exec celery_worker celery -A src.worker.celery_app:celery_app inspect active

# Purge all tasks
docker-compose exec celery_worker celery -A src.worker.celery_app:celery_app purge
```

### Development Tips

1. **Testing Tasks Locally**: Set `CELERY_TASK_ALWAYS_EAGER=true` in `.env` to run tasks synchronously during development

2. **Adding New Tasks**: 
   - Define tasks in `src/worker/tasks.py`
   - Use lazy imports in FastAPI endpoints to avoid circular dependencies
   - Add task routes in `src/worker/celery_app.py` for queue routing

3. **Queue Management**:
   - Default queue: `default`
   - Email queue: `emails` (future-ready)
   - Modify `task_routes` in `celery_app.py` for custom routing

4. **Monitoring**:
   - RabbitMQ Management UI: http://localhost:15672 (guest/guest)
   - Redis can be accessed via `redis-cli` in the container

### Troubleshooting

| Issue | Solution |
|-------|----------|
| Tasks not executing | Check if Celery worker is running and connected to broker |
| Import errors | Ensure proper module paths and avoid circular imports |
| Connection refused | Verify RabbitMQ and Redis services are healthy |
| Tasks hanging | Check task timeouts and retry configuration |
| Memory issues | Adjust `worker_max_tasks_per_child` in config |

## �📝 Notes

- The application uses SQLAlchemy 2.0+ syntax
- Database sessions are automatically managed via dependency injection
- All timestamps are timezone-aware
- CORS is configured for development (update for production)
- Health checks are included for container orchestration
- Environment variables are validated on startup
- Celery is configured with sensible defaults and ready for production scaling

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License.