vibing/backend/README.md

# Vibing Backend

A REST API backend service built with Spring Boot, Java 21, and Maven for the Vibing application.

## Features

- **RESTful API**: Complete CRUD operations for user management
- **Spring Boot 3.2.0**: Latest Spring Boot version with Java 21 support
- **JPA/Hibernate**: Database persistence with H2 in-memory database
- **Spring Security**: Basic security configuration (extensible for production)
- **API Documentation**: Swagger/OpenAPI 3 documentation
- **Validation**: Input validation using Bean Validation
- **Testing**: JUnit 5 test framework

## Prerequisites

- Java 21 or higher
- Maven 3.6 or higher
- IDE (IntelliJ IDEA, Eclipse, VS Code, etc.)

## Getting Started

### 1. Clone the Repository

```bash
git clone <repository-url>
cd vibing/backend
```

### 2. Build the Project

```bash
mvn clean install
```

### 3. Run the Application

```bash
mvn spring-boot:run
```

The application will start on `http://localhost:8080`

## API Endpoints

### Base URL
- **API Base**: `http://localhost:8080/api`
- **Health Check**: `http://localhost:8080/api/health`
- **Swagger UI**: `http://localhost:8080/swagger-ui.html`
- **H2 Console**: `http://localhost:8080/h2-console`

### User Management Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/users` | Get all users |
| GET | `/api/users/{id}` | Get user by ID |
| GET | `/api/users/username/{username}` | Get user by username |
| POST | `/api/users` | Create new user |
| PUT | `/api/users/{id}` | Update user |
| DELETE | `/api/users/{id}` | Delete user |
| GET | `/api/users/check-username/{username}` | Check username availability |
| GET | `/api/users/check-email/{email}` | Check email availability |

### Health Check Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/health` | Application health status |
| GET | `/api/health/ping` | Simple ping endpoint |

## Database

The application uses H2 in-memory database for development:

- **URL**: `jdbc:h2:mem:testdb`
- **Username**: `sa`
- **Password**: `password`
- **Console**: `http://localhost:8080/h2-console`

## Project Structure

```
src/
├── main/
│   ├── java/com/vibing/backend/
│   │   ├── VibingBackendApplication.java    # Main application class
│   │   ├── controller/                      # REST controllers
│   │   │   ├── UserController.java
│   │   │   └── HealthController.java
│   │   ├── service/                         # Business logic
│   │   │   └── UserService.java
│   │   ├── repository/                      # Data access layer
│   │   │   └── UserRepository.java
│   │   ├── model/                           # Entity classes
│   │   │   └── User.java
│   │   ├── config/                          # Configuration classes
│   │   │   └── SecurityConfig.java
│   │   └── exception/                       # Custom exceptions
│   └── resources/
│       └── application.yml                  # Application configuration
└── test/
    └── java/com/vibing/backend/
        └── VibingBackendApplicationTests.java
```

## Configuration

The application configuration is in `src/main/resources/application.yml`:

- **Server Port**: 8080
- **Context Path**: `/api`
- **Database**: H2 in-memory
- **JPA**: Hibernate with create-drop DDL
- **Security**: Basic configuration (allows all user endpoints)

## Development

### Running Tests

```bash
mvn test
```

### Building JAR

```bash
mvn clean package
```

The JAR file will be created in the `target/` directory.

### Running JAR

```bash
java -jar target/vibing-backend-1.0.0.jar
```

## API Documentation

Once the application is running, you can access:

- **Swagger UI**: `http://localhost:8080/swagger-ui.html`
- **OpenAPI JSON**: `http://localhost:8080/api-docs`

## Example API Usage

### Create a User

```bash
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "john@example.com",
    "password": "password123",
    "firstName": "John",
    "lastName": "Doe"
  }'
```

### Get All Users

```bash
curl http://localhost:8080/api/users
```

### Get User by ID

```bash
curl http://localhost:8080/api/users/1
```

## Security

The current security configuration allows all requests to user endpoints for development purposes. For production:

1. Implement proper authentication (JWT, OAuth2, etc.)
2. Add role-based authorization
3. Configure CORS properly
4. Use HTTPS
5. Implement rate limiting

## Contributing

1. Create a feature branch
2. Make your changes
3. Add tests
4. Submit a pull request

## License

This project is licensed under the MIT License.