Development Environment

This document provides a comprehensive guide for setting up and maintaining the local development environment for the IT Ticketing Service. It is intended for developers who will be contributing to and maintaining the application. For initial setup instructions, please refer to the Installation Guide.

Project Context

This application is a demonstration project for the Agentic AI Modernization workshop at Google Next 2026. It represents a legacy on-premises application that will be migrated to Google Cloud Platform using AI-assisted modernization techniques. The migration strategy emphasizes externalized configuration (via application.properties or application.yml) to enable cloud migration with minimal code changes.

IDE Setup

A properly configured Integrated Development Environment (IDE) is crucial for productivity and code consistency. While you are free to use any IDE that supports Maven and Java, we recommend one of the following for the best experience with the Spring Boot ecosystem.

Recommended IDEs

IntelliJ IDEA (Ultimate or Community): Offers excellent Spring Boot integration, Maven support, and a robust plugin ecosystem. The Ultimate edition provides the most comprehensive features out-of-the-box.
Visual Studio Code (VS Code): A lightweight but powerful editor with a rich extension marketplace. Recommended for developers who prefer a more customizable, code-editor-focused environment.
Eclipse IDE for Enterprise Java and Web Developers: A long-standing choice for Java development, with good support for Spring applications via the Spring Tools suite.

IDE Plugins and Extensions

Regardless of your chosen IDE, the following plugins are required to work with this codebase effectively:

Lombok Plugin: The project uses Project Lombok to reduce boilerplate code. Without the corresponding IDE plugin, your IDE will report syntax errors for missing methods (like getters, setters, and constructors) that Lombok generates at compile time. Ensure this plugin is installed and annotation processing is enabled in your IDE settings.
Spring Boot Support:
- IntelliJ: Spring Boot support is built into the Ultimate edition.
- VS Code: The Spring Boot Extension Pack is highly recommended.
- Eclipse: The Spring Tools 4 for Eclipse plugin provides similar functionality.

Code Formatting

To maintain a consistent coding style across the team, developers should configure their IDEs to adhere to standard Java formatting conventions. While a strict .editorconfig is not currently enforced, using the default Java formatter in your IDE is a good baseline. This helps minimize noise in pull requests and keeps the codebase readable.

Project Structure

The project follows the standard directory layout for Maven projects, which helps in locating files and understanding the organization of the code.

src/main/java: Contains the main application source code, organized by package.
src/main/resources: Contains non-code resources, most importantly application.properties or application.yml for externalized configuration. This is central to the project's migration strategy, as outlined in the project overview.
src/test/java: Contains all test source code, including unit and integration tests.
pom.xml: The Maven Project Object Model file, defining project dependencies, build plugins, and metadata.
mise.toml: A configuration file for the mise tool to manage consistent Java and Maven versions.
.gitignore: Specifies intentionally untracked files to be ignored by Git.

For a more detailed breakdown of the application's packages and architectural layers, please see the Code Structure documentation.

External Dependencies

The application requires the following external services to run locally. These must be installed and running before you can start the application:

MySQL Database

The application uses MySQL as its primary relational database for data persistence. The MySQL JDBC driver is included in the project dependencies (mysql-connector-j).

Database Configuration:

The application is configured to connect to a remote MySQL database at:

Host: legacydb.next26.slalomlab.com:3306

All database connection details (URL, username, password) must be configured in src/main/resources/application.properties or application.yml. This externalized configuration approach is central to the project's cloud migration strategy.

Alternative Local Setup (Optional):

If you need to run a local MySQL instance for development or testing:

Install MySQL 8.0 or later on your development machine.
Create a database for the application (e.g., it_ticketing).
Override the database connection details in your local configuration to point to localhost.

For detailed configuration instructions, see Running the Application Locally.

RabbitMQ Message Broker

The application uses RabbitMQ for asynchronous messaging and event-driven communication, integrated via Spring Boot AMQP (spring-boot-starter-amqp).

Local Setup:

Install RabbitMQ on your development machine or use a Docker container.
Ensure RabbitMQ is running on the default port (5672) or configure the connection details in your application properties.
The RabbitMQ management UI (typically on port 15672) is useful for monitoring queues and exchanges during development.

For detailed configuration instructions, see Running the Application Locally.

Development Tools

The project relies on a specific set of tools for building, dependency management, and ensuring a consistent development environment.

Java Version Management (mise)

To prevent "works on my machine" issues, the project uses mise (a polyglot version manager) to enforce a consistent Java and Maven version for all developers. The configuration is defined in mise.toml:

toml

# mise.toml
[tools]
java = "17"
maven = "latest"

To use this:

Install mise by following its official installation guide.
Run mise use in the project's root directory.
This command will automatically download and configure your shell session to use Java 17 and the latest version of Maven, as specified in mise.toml. This matches the Java version configured in pom.xml (<java.version>17</java.version>).

Maven Integration

The project is built and managed by Apache Maven. The pom.xml is the central configuration file.

Key aspects of the Maven configuration include:

Parent POM: The project inherits from spring-boot-starter-parent, which manages versions for a wide range of common dependencies, ensuring compatibility.

xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.4</version>
    <relativePath/>
</parent>

Build Plugin: The spring-boot-maven-plugin is configured to package the application into a single executable JAR file, which is ideal for deployment.

xml

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <excludes>
            <exclude>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </exclude>
        </excludes>
    </configuration>
</plugin>

For instructions on building and running the application, see Running the Application Locally.

Lombok Integration

Lombok is integrated not just as an IDE plugin but also as part of the Maven build process. The maven-compiler-plugin is configured to use Lombok's annotation processor, which generates the required bytecode during compilation.

xml

<!-- pom.xml -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.34</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Gotcha: If you attempt to build the project from the command line (mvn clean install) without a properly configured IDE, the build will succeed. However, your IDE will show errors if the Lombok plugin is not installed, as it won't be able to find the generated methods.

Git Workflow

A disciplined Git workflow is essential for team collaboration.

.gitignore Configuration

The repository includes a comprehensive .gitignore file to prevent common issues like committing build artifacts, IDE-specific files, or sensitive information. Key ignored patterns include:

Build Output: target/, build/
IDE Files: .idea/ (IntelliJ), .vscode/ (VS Code), .project (Eclipse), etc.
OS Files: .DS_Store (macOS)
Sensitive Information: The configuration explicitly ignores environment files (.env, .env.local, *.local.properties) and Terraform-related files in the terraform/ directory (state files, variable files). This is a critical security measure to prevent secrets from being committed to the repository.

gitignore

# .gitignore (snippet)

### IntelliJ IDEA ###
.idea
*.iws
*.iml
*.ipr

### VS Code ###
.vscode/

### Environment files
.env
.env.local
*.local.properties

Branch Strategy

While no specific branching model (e.g., GitFlow) is enforced by repository rules, the team should adhere to a feature-branching workflow:

Create a Feature Branch: For any new feature or bugfix, create a new branch from the main branch (e.g., feature/TICKET-123-add-user-endpoint or bugfix/TICKET-456-fix-validation).
Commit Changes: Make your changes and commit them with clear, descriptive messages.
Push and Create Pull Request (PR): Push your branch to the remote repository and open a Pull Request targeting the main branch.
Code Review: At least one other team member must review the PR for correctness, style, and adherence to project guidelines.
Merge: Once approved, the PR can be merged into the main branch. This process ensures code quality and shared ownership.

Development Environment ​

Project Context ​

IDE Setup ​

Recommended IDEs ​

IDE Plugins and Extensions ​

Code Formatting ​

Project Structure ​

External Dependencies ​

MySQL Database ​

RabbitMQ Message Broker ​

Development Tools ​

Java Version Management (mise) ​

Maven Integration ​

Lombok Integration ​

Git Workflow ​

.gitignore Configuration ​

Branch Strategy ​