---
# System prepended metadata

title: Backend Development Guide

---

# Backend Development Guide

## Table of Contents
- [Initial Setup](#initial-setup)
- [Environment Setup](#environment-setup)
- [Database Configuration](#database-configuration)
- [OpenAPI Integration](#openapi-integration)
- [Application Structure](#application-structure)
- [Development Workflow](#development-workflow)
- [Code Standards](#code-standards)
- [Testing](#testing)
- [Deployment](#deployment)

## Initial Setup

### Prerequisites
1. Install Java 17:
   ```bash
   java -version
   ```
   If not installed, download from [Oracle JDK](https://www.oracle.com/java/technologies/javase-jdk17-downloads.html) or [OpenJDK](https://openjdk.java.net/).

2. Install Gradle:
   ```bash
   gradle -v   # For Gradle
   ```
   If not installed, download from [Gradle](https://gradle.org/).

3. Install PostgreSQL:
   - Download and install from [PostgreSQL](https://www.postgresql.org/).
   - Run SQL Script.

4. Install an IDE:
   - Use IntelliJ IDEA or Eclipse for Java development.

5. Install keycloak:
   - Download and install from [Keycloak](https://www.keycloak.org/archive/downloads-26.0.6.html).

### Project Setup

1. Clone the repository:
   ```bash
   git clone <your-repository-url>
   cd <project-directory>
   ```

## Environment Setup

### Configure Application Properties
1. Set up application-{env}.properties`:
   ```yaml
   spring:
     datasource:
       url: jdbc:postgresql://localhost:5432/ms-bo
       username: your_db_username
       password: your_db_password
       driver-class-name: org.postgresql.Driver
     jpa:
       hibernate:
         ddl-auto: update
       show-sql: true
   ```

### Database Initialization
- Currently, project is database first. Use PostgreSQL database management application connect to local PostgreSQL database and run schema script
  ```bash
  ms_bo.sql
  ```

## OpenAPI Integration

### Generate API Stubs
1. Define an OpenAPI specification (`openapi.yaml`).
2. Generate server stubs:
   ```bash
   openapi-generator-cli generate        -i openapi.yaml        -g spring        -o ./generated
   ```
3. Include the generated files in your project.

### API Documentation
- Include Swagger UI:
  ```yaml
  springdoc:
    api-docs:
      path: /v3/api-docs
    swagger-ui:
      path: /swagger-ui.html
  ```

## Application Structure
- Suggested folder structure:
  ```
  src/main/java/com/tpi/ms-bo
  ├── controller
  ├── service
  ├── dao
  ├── model
  └── config
  ```

## Development Workflow

### 1. Branch Management
1. Create feature branch:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Merge into `develop` after review.

### 2. Feature Development
1. Modify openapi.yaml file 
```
  /api/path:
    parameters: []
    post:
      summary: 
      operationId: 
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDTO'
      tags:
        - 
      description: 
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDTO'
      security:
        - Bearer: []
```
2. Run command to generate file 
``` openapi-generator-cli generate -i openapi.yaml ```
1. Copy config DTO Class and interface api from target to project and create controller implements api interface
   ```java
   @RestController
   public class ResourceController implements APIInterface {
       public ResponseEntity<Resource> getResource(@PathVariable Long id) {
           // Implementation
       }
   }
   ```

2. Create Services:
   ```java
   @Service
   public class ResourceService {
       public Resource getResourceById(Long id) {
           // Implementation
       }
   }
   ```

3. Create Repositories:
   ```java
   @Repository
   public interface ResourceRepository extends JpaRepository<Resource, Long> {
   }
   ```

## Deployment
1. Build the project:
   ```bash
   gradle clean build
   ```

2. Run the application:
   ```bash
   java -jar target/your-application.jar
   ```

3. Configure CI/CD pipelines for automated deployment.

---

## Common Issues and Solutions

### Database Connection Error
- Verify database credentials in `application-{env}.properties`.
- Ensure the PostgreSQL server is running.

### API Documentation Not Loading
- Verify `springdoc` configuration in `application-{env}.properties`.
- Ensure the Swagger dependency is included.

---

Happy coding!
