feature(simulator): Add simulator library to the project.

[arash-khajelou]

Problem Statement

What is the problem?

The delivery project needs simulator functionality to seed and clear test data during development and testing phases. Currently, similar simulator functionality exists in the scheduled-delivery project, but it is implemented as a project-specific solution that is tightly coupled to that project's infrastructure. The delivery project requires this functionality but lacks a reusable, standardized approach to implement it.

Why should we care?

Without simulator functionality in the delivery project, developers and QA engineers cannot easily:

• Seed test data for development and testing scenarios
• Clear test data to reset the environment to a clean state
• Automate test data management workflows

This leads to manual data management processes, slower development cycles, and potential inconsistencies in test environments. Additionally, without a reusable library, each project that needs simulator functionality would need to implement its own solution, leading to code duplication and maintenance overhead.

Root Causes

1. Lack of reusable simulator library: The simulator implementation in scheduled-delivery is project-specific and not designed as a reusable component
2. Tight coupling: The current implementation is tightly coupled to scheduled-delivery's infrastructure and gRPC endpoints
3. No standardized approach: There's no common library or pattern for simulator functionality across projects

---

Solution

Create a reusable simulator library in the utilities-starter project that provides:

• A DataSimulator interface with seedData() and clearData() methods
• Support for Seedable and Deletable interfaces that components can implement
• Spring Boot auto-configuration for easy integration
• Actuator endpoints (/actuator/simulator/seed and /actuator/simulator/clear) instead of gRPC endpoints
• Profile-based activation (e.g., only enabled in local/dev environments)

The library will be integrated into the delivery project's infrastructure layer, allowing components to implement Seedable and Deletable interfaces to participate in the simulator workflow. The actuator endpoints will provide a standard HTTP-based interface for triggering seed and clear operations.

---

Boundaries

Key Questions

1. Should the library support both reactive (Mono/Flux) and blocking operations?

Answer: The library should support reactive operations (using Reactor's Mono<Void>) to align with the existing codebase patterns in both scheduled-delivery and delivery projects. This ensures consistency and compatibility with Spring WebFlux and reactive MongoDB repositories.

2. What actuator endpoint paths should be used?

Answer: The endpoints should follow Spring Boot Actuator conventions:

• /actuator/simulator/seed - for seeding data
• /actuator/simulator/clear - for clearing data

These endpoints should be secured and only enabled in appropriate profiles (local/dev).

3. Should the library handle repository deletion automatically or require explicit Deletable implementations?

Answer: The library requires explicit Deletable implementations. Developers must implement the Deletable interface for any component that needs to participate in the clear workflow. This includes:

• Custom deletion logic for domain entities
• Repository deletion (if needed, developers should create a Deletable implementation that deletes from their repositories)
• Any other cleanup operations

The library is technology-agnostic and does not automatically discover or delete repositories. This gives developers full control over what gets deleted and how, regardless of the underlying data storage technology (MongoDB, PostgreSQL, etc.).

User Stories/Requirements

• As a developer working on the delivery project, I want to seed test data via an actuator endpoint so that I can quickly set up test scenarios
• As a developer, I want to clear test data via an actuator endpoint so that I can reset my local environment
• As a component developer, I want to implement Seedable or Deletable interfaces so that my component can participate in the simulator workflow
• As a developer, I want the simulator to only be available in local/dev environments so that production safety is maintained

Out of Scope

• Migrating scheduled-delivery project to use the new library
• Changing the existing gRPC-based simulator implementation in scheduled-delivery
• Adding simulator functionality to other projects beyond delivery
• Implementing custom seeders/deleters for specific domain entities (these will be implemented in the delivery project itself)
• Adding gRPC endpoints to the library (actuator endpoints only)

[arash-khajelou]

https://git.webdooz.com/delivery/project-management/-/issues/2210