Architecture Overview

This document provides a detailed technical overview of the IT Ticketing Service application. It is intended for developers responsible for the maintenance, extension, and modernization of the service.

Project Context

This is a demonstration application for the Agentic AI Modernization workshop at Google Next 2026. The application represents a "legacy" on-premises Spring Boot service running in a VMware environment that demonstrates AI-assisted migration to Google Cloud Platform.

The primary goal is to showcase how AI can facilitate cloud migration with minimal code changes, relying instead on externalized configuration through Spring application properties. This approach allows the same codebase to run in different environments (on-premises and GCP) by simply changing configuration, not code.

System Architecture

The application is built upon a classic, robust layered architecture pattern. This design promotes separation of concerns, making the codebase easier to maintain, test, and evolve. The architecture is composed of a primary synchronous request-response flow for handling API calls and a secondary asynchronous, event-driven flow for communicating state changes.

Synchronous Data Flow (API Requests)

The primary data flow follows a well-defined path through three distinct layers for every incoming HTTP request:

1. Controller Layer: The entry point for all client interactions. It receives HTTP requests, deserializes JSON payloads into Data Transfer Objects (DTOs), performs initial validation, and delegates the request to the appropriate service.
2. Service Layer: This is the core of the application, containing all business logic. It orchestrates the operations, coordinates with the data access layer, and triggers asynchronous events. It is completely decoupled from the web layer.
3. Repository Layer: The final layer in the synchronous flow, responsible for all database interactions. It abstracts the underlying data persistence mechanism (JPA/MySQL) and provides a simple, object-oriented interface for data manipulation.

This strict Controller → Service → Repository flow ensures a clear and predictable path for data and control, which is fundamental to the application's design.

Asynchronous Data Flow (Event Publishing)

To support decoupling and extensibility, the application integrates event-driven principles. After a core business operation is successfully completed (e.g., a ticket is created or updated), the Service Layer publishes an event to a message broker.

• Trigger: A successful state change in the Service Layer.
• Action: The AmqpTemplate is used to send a message to a RabbitMQ exchange.
• Outcome: Downstream systems can consume these events to perform their own work (e.g., sending notifications, updating a data warehouse) without creating a tight coupling with the ticketing service.

For more details on the messaging implementation, see the Event-Driven Architecture documentation.

Key Components

The application is composed of several key components, each corresponding to a layer in the architecture and implemented using specific Spring Boot starters and libraries.

REST API Layer (Controllers)

This layer handles all HTTP-based communication and is built using spring-boot-starter-web.

• Implementation: Standard Spring MVC components annotated with @RestController.
• Data Format: Endpoints consume and produce application/json.
• Validation: Server-side validation is enforced at this layer using Jakarta Bean Validation annotations (e.g., @NotNull, @Size) on request DTOs, enabled by the spring-boot-starter-validation dependency. This prevents invalid data from reaching the business logic layer.
• Health & Metrics: The spring-boot-starter-actuator provides production-ready endpoints like /actuator/health and /actuator/metrics, which are essential for monitoring and operating the service in any environment.

Business Logic Layer (Services)

This layer encapsulates all business rules and is the heart of the application.

• Implementation: Components are defined as Spring beans annotated with @Service.
• Dependency Injection: Services are stateless and rely on dependency injection to receive references to repositories, other services, or messaging templates.
• Transactional Integrity: Business methods that modify data should be annotated with @Transactional to ensure atomicity and data consistency. Spring's transaction management will handle the underlying database transaction lifecycle.

Data Access Layer (Repositories)

Data persistence is managed by Spring Data JPA, which significantly simplifies database interactions.

• Implementation: The layer consists of Java interfaces that extend org.springframework.data.jpa.repository.JpaRepository. Spring Data automatically provides implementations for standard CRUD operations at runtime.
• ORM: JPA is used as the Object-Relational Mapping (ORM) provider, mapping Java objects (entities) to database tables. For details on the primary entity, see the Ticket Data Model documentation.
• Database Driver: The application is configured to connect to a MySQL database, as specified by the mysql-connector-j dependency in the pom.xml.

<!-- pom.xml: Key dependencies for the core layers -->
<dependencies>
    <!-- Controller Layer -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Data Access Layer -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- Messaging Layer -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-amqp</artifactId>
    </dependency>
</dependencies>

Messaging Layer (RabbitMQ)

Asynchronous messaging is handled via the Advanced Message Queuing Protocol (AMQP), with RabbitMQ being the target broker.

• Implementation: The spring-boot-starter-amqp dependency provides auto-configuration for RabbitTemplate and other core AMQP components.
• Usage: The RabbitTemplate bean is injected into services to publish messages to specific exchanges and routing keys.
• Configuration: All broker connection details (host, port, credentials) are externalized to configuration files, which is critical for environment portability.

Technology Stack

The application is built on a modern, robust, and widely adopted technology stack centered around the Java and Spring ecosystems. The pom.xml manifest serves as the definitive source for all project dependencies.

Technology	Version	Description
Java	17	The core programming language and runtime environment.
Spring Boot	3.2.4	The primary application framework, providing dependency injection, web, and data access capabilities.
Spring Data JPA	3.2.4	The persistence framework used for ORM and simplifying data access.
Spring AMQP	3.2.4	The framework for integrating with AMQP message brokers like RabbitMQ.
MySQL	N/A	The relational database system. The mysql-connector-j driver is used for connectivity.
RabbitMQ	N/A	The message broker used for asynchronous event publishing.
Maven	latest	The build automation tool and dependency manager.
Lombok	1.18.34	A compile-time annotation processor used to reduce boilerplate code (getters, setters, etc.).

The application is initialized via a standard Spring Boot main class.

// src/main/java/com/slalom/demo/ticketing/ItTicketingApplication.java

package com.slalom.demo.ticketing;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Main entry point for the IT Ticketing Service application.
 * The @SpringBootApplication annotation enables auto-configuration,
 * component scanning, and other core Spring Boot features.
 */
@SpringBootApplication
public class ItTicketingApplication {

    public static void main(String[] args) {
        SpringApplication.run(ItTicketingApplication.class, args);
    }
}

Design Principles

The application was designed with a specific goal in mind: to demonstrate how a well-architected "legacy" application can be migrated to Google Cloud Platform with minimal code changes. This migration-first philosophy is reflected in several key design principles.

12-Factor App Methodology

The application adheres closely to the principles of a 12-Factor App, which are best practices for building modern, cloud-native applications. The most critical principle for this project is Factor III: Config.

• Strict Separation of Config from Code: All configuration that varies between environments (on-prem, staging, production, developer machines) is stored in the environment. This includes database credentials, message broker URLs, and external service endpoints.
• Implementation: Spring Boot's robust externalized configuration mechanism is used to achieve this. The application consumes properties from application.properties or environment variables without any code changes. For a detailed guide on configurable properties, refer to the Application Properties documentation.

Externalized Configuration for Migration

This is the cornerstone of the project's AI-assisted migration strategy. By externalizing all environment-specific settings, the application can be migrated from the on-premises VMware environment to Google Cloud Platform by simply providing a new configuration set—no code changes required.

This approach demonstrates how AI can identify and externalize configuration during modernization, enabling the same application binary to run seamlessly across different environments.

Critical Constraint: Developers must avoid hardcoding any environment-specific values, such as hostnames, ports, or credentials, directly in the code. All such values must be externalized to configuration files or environment variables.

Cloud Migration Strategy

The combination of the layered architecture, adherence to 12-factor principles, and the use of Spring Boot Actuator enables the application's migration from VMware to Google Cloud Platform through configuration changes alone.

• Stateless Services: The web/service tier is designed to be stateless, allowing for horizontal scaling in a cloud environment.
• Portable Dependencies: The use of standard technologies like MySQL and RabbitMQ ensures that managed cloud equivalents (e.g., Google Cloud SQL, Cloud Pub/Sub) can be swapped in via configuration changes alone, without modifying application code.
• Observability: Actuator endpoints provide the necessary hooks for cloud platforms to manage the application's lifecycle, perform health checks, and scrape metrics for autoscaling and monitoring.
• Environment-Agnostic Code: The application code contains no environment-specific logic or hardcoded values, making it portable across any deployment target.