# WineMatch API 🍷

A high-performance FastAPI gateway for wine pairing and recommendation

![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)
![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=for-the-badge&logo=python&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge&logo=postgresql&logoColor=white)
![Alembic](https://img.shields.io/badge/Alembic-000000?style=for-the-badge)
![Pytest](https://img.shields.io/badge/Pytest-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white)

## Table of Contents
- [Features](#features-)
- [System Requirements](#system-requirements-)
- [Installation Guide](#installation-guide-)
  - [1. Clone Repository](#1-clone-repository)
  - [2. Virtual Environment Setup](#2-virtual-environment-setup)
  - [3. Install Dependencies](#3-install-dependencies)
  - [4. Database Setup](#4-database-setup)
- [Running the Application](#running-the-application-)
- [Database Migrations](#database-migrations-)
- [Development Workflow](#development-workflow-)
  - [Code Formatting](#code-formatting)
  - [Pre-commit Hooks](#pre-commit-hooks)
- [API Documentation](#api-documentation-)

## Project Structure

```
winematch-api/
├── main.py                   # Application entry point
├── requirements.txt          # Project dependencies
├── alembic.ini               # Alembic configuration
├── docker-compose.yml        # Docker configuration
├── uploads/                  # File upload directory
│   ├── avatars/              # User avatar storage
│   └── files/                # General file storage
└── src/                      # Source code
    ├── apps/                 # Application modules
    │   └── users/            # Users module
    │       ├── models/       # User models
    │       ├── routers/      # User API endpoints
    │       ├── schemas/      # User data schemas
    │       └── services/     # User business logic services
    ├── core/                 # Core application components
    │   ├── config.py         # Application configuration
    │   ├── database.py       # Database connection setup
    │   ├── dependencies.py   # FastAPI dependencies
    │   ├── router.py         # Router registration
    │   └── middlewares/      # Request/response middlewares
    ├── routers/              # Main API router registration
    │   └── api_routers.py    # Combines all versioned routers
    ├── utils/                # Utility functions and helpers
    │   ├── constants.py      # Application constants
    │   ├── enums.py          # Enumeration classes
    │   ├── guard.py          # Password security utilities
    │   ├── io.py             # File I/O operations
    │   ├── pagination.py     # Pagination utilities
    │   └── helpers/          # Helper functions
    │       ├── pagination_schema.py # Pagination schema
    │       └── response.py   # Response formatting helpers
    └── versions/             # API version organization
        └── v1/               # Version 1 API
            └── routers/      # Version 1 specific routers
                └── api_router.py  # Version 1 router aggregator
```

## Features ✨
- RESTful API endpoints with FastAPI
- PostgreSQL relational database backend
- Alembic for database schema migrations
- JWT Authentication
- HMVC architecture for modular structure
- API versioning for future compatibility
- Automated testing with Pytest
- Pydantic data validation
- File uploads management
- Swagger and ReDoc API documentation
- Docker container support
- Pre-commit hooks for code quality

## System Requirements 💻
- Python 3.12 or higher
- PostgreSQL 12+
- pip 22.0+
- Git 2.30+

## Installation Guide 📥

### 1. Clone Repository
```bash
git clone https://your-repository-url/winematch-api.git
cd winematch-api
```

### 2. Virtual Environment Setup

#### For Windows Systems

1. Create the virtual environment:
```bash
python -m .venv venv_
```
2. Activate the virtual environment:
```bash
venv_\Scripts\activate
```
3. Verify activation (you should see (venv) before your prompt):
```bash
(.venv) C:\path\to\your\project>
```
#### For Linux/Mac Systems
1. Create the virtual environment:
```bash
python3 -m .venv ..venv
```
2. Activate the virtual environment:
```bash
source ..venv/bin/activate
```
3. Verify activation (you should see (.venv) before your prompt):
```bash
(..venv) user@hostname:~/path/to/your/project$
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
### 4. Database Setup
1. Start PostgreSQL Container
```bash
docker-compose up -d
```

## Running the Application 🚀
### 1. Start the FastAPI server
```bash
uvicorn main:app --reload
```
### 2. Access the API
- Open your browser and navigate to `http://localhost:8000/docs` for Swagger UI or `http://localhost:8000/redoc` for ReDoc documentation.
- You can also access the API at `http://localhost:8000/api/v1/` for the main endpoint.

## Database Migrations 🔄
### 1. Create a new migration
```bash
alembic revision --autogenerate -m "migration_name"
```
### 2. Apply migrations
```bash
alembic upgrade head
```
### 3. Downgrade migrations
```bash
alembic downgrade -1
```
### 4. View migration history
```bash
alembic history
```
### 5. View current migration
```bash
alembic current
```

## Development Workflow 🔄
### Code Formatting
- Use `black` for code formatting:
```bash
black .
```
### Pre-commit Hooks
- Install pre-commit hooks:
```bash
pre-commit install
```
- This will automatically format your code and run tests before each commit.
- To manually run pre-commit hooks:
```bash
pre-commit run --all-files
```

## API Documentation 📜
- The API documentation is automatically generated and can be accessed at:
  - Swagger UI: `http://localhost:8000/docs`
  - ReDoc: `http://localhost:8000/redoc`

## API Endpoints

All API endpoints are now versioned under `/api/v1/...` to support future API changes.

### Users
- POST `/api/v1/users/` - Create a new user
- GET `/api/v1/users/` - Get all users (admin only)
- GET `/api/v1/users/{user_id}` - Get user by ID
- PUT `/api/v1/users/{user_id}` - Update user
- DELETE `/api/v1/users/{user_id}` - Delete user (soft delete)

## API Versioning

The API has been structured with versioning to ensure backward compatibility as the API evolves:

- **Current Version**: v1 (accessible at `/api/v1/...`)
- **Future Versions**: The structure is prepared for v2 and beyond

When new breaking changes are needed, they can be implemented in a new version (e.g., v2) while maintaining the existing v1 API for backward compatibility.