Quick Start Guide

Prerequisites

Before starting, ensure you have the following installed:

Java Development Kit

Version: JDK 21 or higherVerify: java -version

Apache Maven

Version: Maven 3.9 or higherVerify: mvn -version

Node.js & npm

Version: Node.js 20+ and npm 10+Verify: node -v && npm -v

Python

Version: Python 3.8 or higherVerify: python3 --version

Optional: Docker and Docker Compose for containerized deployment (recommended for production)

Installation Steps

Clone the Repository

Get the Justina source code from the repository:

git clone <repository-url>
cd S02-26-Equipo-24-Web-App-Development

The repository structure:

S02-26-Equipo-24-Web-App-Development/
├── backend/        # Spring Boot backend
├── frontend/       # Next.js frontend
└── ia/            # Python AI service

Configure Environment Variables

Create environment configuration for the backend. The backend uses H2 in-memory database by default (perfect for development).Backend Configuration (optional - defaults work out of the box):

cd backend

Create a .env file or set environment variables:

# Server Configuration
PORT=8080

# JWT Secret (REQUIRED - use a strong secret in production)
JWT_SECRET_KEY=your-super-secret-jwt-key-change-in-production

# Database (H2 in-memory - default)
SPRING_DATASOURCE_URL=jdbc:h2:mem:justina
SPRING_DATASOURCE_USERNAME=sa
SPRING_DATASOURCE_PASSWORD=
SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.h2.Driver
SPRING_JPA_HIBERNATE_DDL_AUTO=create-drop
SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT=org.hibernate.dialect.H2Dialect

Production Note: Never use the H2 in-memory database in production. Switch to PostgreSQL and use a strong JWT secret key.

Frontend Configuration:

cd ../frontend

Create .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080

AI Service Configuration:

cd ../ia

Create .env:

BASE_URL=http://localhost:8080
IA_USERNAME=ia_justina
IA_PASSWORD=ia_secret_2024

Start the Backend

The backend must be started first as it provides the API for other services.

cd backend

# Build the project (skip tests for faster startup)
./mvnw clean install -DskipTests

# Run the application
./mvnw spring-boot:run

On Windows, use mvnw.cmd instead of ./mvnw

Alternative: Run the JAR directly

# Build JAR
./mvnw clean package -DskipTests

# Run JAR
java -jar target/Justina-0.0.1-SNAPSHOT.jar

Verify Backend is Running:The backend should start on port 8080. Check the console for:

Started JustinaApplication in X.XXX seconds

Access the API documentation at:

http://localhost:8080/swagger-ui/index.html

Default Users

The backend initializes with two default accounts:Surgeon Account:

Username: surgeon_master
Password: justina2024
Role: ROLE_SURGEON

AI Service Account:

Username: ia_justina
Password: ia_secret_2024
Role: ROLE_IA

Start the Frontend

Open a new terminal window for the frontend.

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Alternative package managers:

# Using Yarn
yarn install
yarn dev

# Using pnpm
pnpm install
pnpm dev

The frontend will start on http://localhost:3000.Verify Frontend is Running:Open your browser and navigate to:

http://localhost:3000

You should see the Justina login page.

Start the AI Service (Optional)

The AI service processes surgical data and provides analysis. It’s optional for basic testing but required for receiving AI feedback.Open a new terminal window:

cd ia

# Install Python dependencies
pip install -r requirements.txt

# Start the AI WebSocket client
python websocket_client.py

Verify AI Service is Running:You should see:

╔════════════════════════════════════════════════════════╗
║   JUSTINA - CLIENTE IA CON WEBSOCKET                  ║
║   Escuchando notificaciones en tiempo real...         ║
╚════════════════════════════════════════════════════════╝

🔌 WebSocket conectado exitosamente
👂 Esperando notificaciones del backend...

Alternative Mode: You can also run the AI service in manual mode using python main.py to process surgeries by ID instead of listening to WebSocket notifications.

First Simulation

Now that all services are running, let’s perform your first surgical simulation.

Navigate to http://localhost:3000 in your browser.Use the default surgeon credentials:

Username: surgeon_master
Password: justina2024

Click the Login button.

Access the Simulation Dashboard

After successful login, you’ll be redirected to the dashboard where you can:

Start a new simulation
View past surgeries
Check your performance statistics

Start a Simulation

Click on “Start New Simulation” or the simulation module card.You’ll be taken to the 3D surgical environment powered by Babylon.js.What you’ll see:

3D surgical scene with instruments
Interactive controls for manipulation
Real-time telemetry connection status

The WebSocket connection is established automatically when the simulation loads. Check the browser console for connection logs.

Perform the Simulation

Interact with the surgical instruments using your mouse:

Left Click + Drag: Move instruments in the XY plane
Right Click + Drag: Rotate camera view
Scroll: Zoom in/out

The system tracks every movement in real-time:

// Telemetry data structure sent to backend
{
  "coordinates": { "x": 10.5, "y": 20.3, "z": 15.7 },
  "event": "MOVE",
  "timestamp": "2024-01-15T10:30:00Z"
}

Events tracked:

START: Simulation begins
MOVE: Instrument movement
TUMOR_TOUCH: Contact with tumor (critical event)
HEMORRHAGE: Hemorrhage occurrence (critical event)
FINISH: Simulation completes

Complete the Simulation

Click the “Finish Surgery” button when done.The system will:

Send a FINISH event via WebSocket
Close the WebSocket connection
Save the surgery session to the database
Return a surgery UUID

Backend response:

{
  "status": "SAVED",
  "surgeryId": "550e8400-e29b-41d4-a716-446655440000"
}

This ID is stored in cookies and localStorage for later retrieval.

View AI Analysis

If the AI service is running, it will automatically:

Receive a WebSocket notification about the new surgery
Fetch the trajectory data via REST API
Process through the 5-step analysis pipeline
Send the results back to the backend

Console output from AI service:

📡 MENSAJE RAW DEL SERVIDOR WEBSOCKET:
{"event":"NEW_SURGERY","surgeryId":"550e8400-e29b-41d4-a716-446655440000"}

🏥 INICIANDO ANÁLISIS: 550e8400-e29b-41d4-a716-446655440000
📊 Paso 1: Obteniendo trayectoria...
🧠 Paso 2: Analizando con pipeline de 5 pasos...
✅ Análisis completado - Score: 87.5/100
📤 Paso 3: Enviando análisis al backend...
🎉 ¡Cirugía procesada exitosamente!

Access the analysis report through the dashboard or via API:

curl http://localhost:8080/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Testing the API

Justina provides a complete REST API documented with OpenAPI/Swagger.

Access Swagger UI

Navigate to:

http://localhost:8080/swagger-ui/index.html

Authentication Flow

# Login to get JWT token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "surgeon_master",
    "password": "justina2024"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "surgeon_master",
  "role": "ROLE_SURGEON"
}

Fetch Surgery Data

# Get surgery trajectory
curl http://localhost:8080/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/trajectory \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "surgeryId": "550e8400-e29b-41d4-a716-446655440000",
  "surgeon": "surgeon_master",
  "startTime": "2024-01-15T10:25:00Z",
  "endTime": "2024-01-15T10:35:00Z",
  "movements": [
    {
      "coordinates": [10.5, 20.3, 15.7],
      "event": "MOVE",
      "timestamp": 1705315500000
    }
  ]
}

Troubleshooting

Backend Won’t Start

Issue: Port 8080 already in use

# Check what's using port 8080
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Kill the process or change the port
export PORT=8081
./mvnw spring-boot:run

Issue: JWT_SECRET_KEY not set

# Set the environment variable
export JWT_SECRET_KEY="your-secret-key-here"
./mvnw spring-boot:run

Frontend Connection Issues

Issue: Cannot connect to backend API Verify your .env.local configuration:

# frontend/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080

Restart the dev server after changing environment variables. Issue: WebSocket connection fails Check the browser console for errors. Common causes:

Backend not running
JWT token not found in cookies
CORS issues (backend should allow frontend origin)

AI Service Issues

Issue: AI service can’t authenticate Verify credentials in ia/.env:

IA_USERNAME=ia_justina
IA_PASSWORD=ia_secret_2024

These must match the default AI user created by the backend. Issue: Python dependencies missing

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Next Steps

Architecture Overview

Learn about the technical architecture and design patterns

API Reference

Explore all available endpoints and WebSocket protocols

Deployment Guide

Deploy Justina to production with Docker and PostgreSQL

Environment Variables

Configuration options for all components

Getting Started

Features

User Guide

Quick Start Guide

Prerequisites

Java Development Kit

Apache Maven

Node.js & npm

Python

Installation Steps

Default Users

First Simulation

Testing the API

Access Swagger UI

Authentication Flow

Fetch Surgery Data

Troubleshooting

Backend Won’t Start

Frontend Connection Issues

AI Service Issues

Next Steps

Architecture Overview

API Reference

Deployment Guide

Environment Variables

Build docs developers (and LLMs) love

Getting Started

Features

User Guide

​Prerequisites

Java Development Kit

Apache Maven

Node.js & npm

Python

​Installation Steps

Default Users

​First Simulation

​Testing the API

​Access Swagger UI

​Authentication Flow

​Fetch Surgery Data

​Troubleshooting

​Backend Won’t Start

​Frontend Connection Issues

​AI Service Issues

​Next Steps

Architecture Overview

API Reference

Deployment Guide

Environment Variables

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

First Simulation

Testing the API

Access Swagger UI

Authentication Flow

Fetch Surgery Data

Troubleshooting

Backend Won’t Start

Frontend Connection Issues

AI Service Issues

Next Steps