int-layer/README.md

Key Versions & Management:

• Java Version: 21
• Spring Boot Version: 3.2.5 (defined in the parent POM)
• Spring Cloud GCP Version: 5.3.0 (managed via spring-cloud-gcp-dependencies)
• Spring Cloud Version: 2023.0.0 (managed via spring-cloud-dependencies)

This project is a Spring Boot Service Orchestrator running on Java 21.

Here is step-by-step guide to getting this deployed locally in your IDE.

---

Step 1: Ensure Prerequisites

Before we touch the code, we need to make sure your local machine matches the project requirements found in the pom.xml and Dockerfile.

1. Install Java 21 JDK: The project explicitly requires Java 21.
   • Check: Run java -version in your terminal. If it doesn't say "21", you need to install it.
2. Install Maven: This is used to build the project dependencies.
3. Install the "Extension Pack for Java" in VS Code: This includes tools for Maven, debugging, and IntelliSense.
4. Install Docker (Desktop or Engine): We will need this to run a local Redis instance.

---

Step 2: The "Redis Gotcha" (Local Infrastructure)

If you look at src/main/resources/application-dev.properties, you will see this line: spring.data.redis.host=localhost.

1. Start Redis in Docker: Open your terminal and run:

   docker run --name local-redis -p 6379:6379 -d redis
   

2. Verify it's running: Run docker ps. You should see redis running on port 6379.

---

Step 3: Google Cloud Authentication

This application connects to Firestore, Dialogflow CX, and Vertex AI (Gemini). It uses the "Application Default Credentials" strategy.

1. Install the Google Cloud CLI (gcloud) if you haven't already.
2. Login: In your terminal, run:

   gcloud auth application-default login
   

   This will open a browser window. Log in with your Google account that has access to the app-jovenes project.

---

Step 4: Configure Local Properties

We need to tell the application to look at your local Redis instead of the cloud one.

1. Open src/main/resources/application.properties.

2. Ensure the active profile is set to dev:

   spring.profiles.active=dev
   

3. Modify Google Memorystore(Redis) Configuration in the file src/main/resources/application.properties:

   spring.data.redis.host=localhost
   spring.data.redis.port=6379
   spring.data.redis.password=23cb4c76-9d96-4c74-b8c0-778fb364877a
   spring.data.redis.username=default
   

---

Step 5: Build the Project

Now let's download all the dependencies defined in the pom.xml.

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
2. Type "Maven: Execute Commands" -> select the project -> "install".
   • Alternative: Open the built-in terminal and run:

     mvn clean install -DskipTests
     

   • Why skip tests? The tests might try to connect to real cloud services or check specific configs that might fail on the first local run. Let's just get it compiling first.
3. If you get an error with the dependencies, open the built-in terminal and run:

   mvn dependency:purge-local-repository
   

---

Step 6: Run the Application

Step 6.1: Run the Application using an Maven

1. Open the built-in terminal and run:

   mvn spring-boot:run
   

Step 6.2: Run the Application using an IDE

1. Navigate to src/main/java/com/example/Orchestrator.java.
2. You should see a small "Run | Debug" button appear just above the public static void main line.
3. Click Run.

What to watch for in the Console:

• You want to see the Spring Boot logo.
• Look for Started Orchestrator in X seconds.
• Look for Netty started on port 8080 (since this is a WebFlux app).

---

Step 7: Verify it's working

Since this is an API, let's test the health or a simple endpoint.

1. The app runs on port 8080 (defined in Dockerfile).
2. The API has Swagger documentation configured.
3. Open your browser and go to: http://localhost:8080/webjars/swagger-ui/index.html .
   • Note: If Swagger isn't loading, check the console logs for the exact context path.

Summary Checklist for you:

• Java 21 Installed?
• Docker running Redis on localhost:6379?
• gcloud auth application-default login run?
• application-dev.properties updated to use localhost for Redis?

Examples of endpoint call

1. The Standard Conversation (Dialogflow)

This is the most common flow. It simulates a user sending a message like "Hola" to the bot. The orchestrator will route this to Dialogflow CX. f Request:

curl -X POST http://localhost:8080/api/v1/dialogflow/detect-intent \
-H "Content-Type: application/json" \
-d '{
  "mensaje": "Hola, ¿quien eres?",
  "usuario": {
    "telefono": "5550001234",
    "nickname": "DiegoLocal"
  },
  "canal": "whatsapp",
  "tipo": "INICIO"
}'

What to expect:

• Status: 200 OK
• Response: A JSON object containing responseText (the answer from Dialogflow) and responseId.
• Logs: Check your VS Code terminal. You should see logs like Initiating detectIntent for session....

---

2. The "Smart" Notification Flow (Gemini Router)

This is the cool part. We will first "push" a notification to the user, and then simulate the user asking a question about it.

Step A: Push the Notification This tells the system: "Hey, user 5550001234 just received this alert."

curl -X POST http://localhost:8080/api/v1/dialogflow/notification \
-H "Content-Type: application/json" \
-d '{
  "texto": "Tu tarjeta *1234 ha sido bloqueada por seguridad.",
  "telefono": "5550001234",
  "parametrosOcultos": {
    "motivo": "intento_fraude_detectado",
    "ubicacion": "CDMX",
    "fecha": "Hoy"
  }
}'

• Check Logs: You should see Notification for phone 5550001234 cached.

Step B: User asks a follow-up (The Test) Now, ask a question that requires context from that notification.

curl -X POST http://localhost:8080/api/v1/dialogflow/detect-intent \
-H "Content-Type: application/json" \
-d '{
  "mensaje": "¿Por qué fue bloqueada?",
  "usuario": {
    "telefono": "5550001234"
  },
  "canal": "whatsapp",
  "tipo": "CONVERSACION"
}'

• What happens internally: The MessageEntryFilter (Gemini) will see the previous notification in the history and classify this as a NOTIFICATION follow-up, routing it to the LLM instead of standard Dialogflow.

---

3. Quick Replies (Static Content)

This tests the QuickRepliesManagerService. It fetches a JSON screen definition from your local files (e.g., home.json).

Request:

curl -X POST http://localhost:8080/api/v1/quick-replies/screen \
-H "Content-Type: application/json" \
-d '{
  "usuario": {
    "telefono": "5550001234"
  },
  "canal": "app",
  "tipo": "INICIO",
  "pantallaContexto": "pagos"
}'

What to expect:

• Response: A JSON object with a quick_replies field containing the title "Home" (loaded from home.json).

---

4. Reset Everything (Purge)

If you want to start fresh (clear the cache and history for "Local"), run this:

curl -X DELETE http://localhost:8080/api/v1/data-purge/all

• Logs: You'll see Starting Redis data purge and Starting Firestore data purge.

5. Optional testing the llm response with uuid

/api/v1/llm/tune-response
{
  "sessionInfo": {
    "parameters": {
      "uuid": "21270589-184e-4a1a-922d-fb48464211e8"
    }
  }
}

Extras

gcloud config configurations list

gcloud config list --all

gcloud config configurations activate banorte

lsof -ti:8080 | xargs kill -9