🏦 Introduction to the Transactional Engine

Transactional Engine API - Investment Core (Backend)

Welcome to the documentation of the first microservice of the project. My Portfolio’s Transactional Investment Engine!

This project acts as a high-precision and performance-optimized RESTful API to simulate operational processes of Fintech platforms. It is designed to manage capital injection, portfolio queries, and atomic conversion of assets from Mexican Pesos (MXN) to digital dollars (USDC), ensuring data consistency under high-concurrency scenarios.

🚀 Features and Backend Architecture

ACID Concurrency

Strict implementation of transactional isolation at the persistence level through pessimistic locking, completely nullifying Race Conditions.

Precision Arithmetic

Absolute use of the BigDecimal class complemented by strict banking rounding policies (RoundingMode.HALF_UP), mitigating floating-point failures.

Perimeter Validation

Centralization and sanitization of Payloads through Jakarta Validation at the HTTP layer (@Valid), catching failures with a global interceptor (@ControllerAdvice).

Secure Infrastructure

Multi-stage packaging pipeline based on Alpine Linux (JRE), with native injection of JVM tuning flags and privilege isolation.

🛠️ Tech Stack

Technology	Version	Project Purpose
Spring Boot	^3.5.14	Base framework, Inversion of Control (IoC) and RESTful controllers
Java	21	Main language with strict typing and records
Spring Data JPA	^3.5.11	Data abstraction, ORM with Hibernate 6 and locking control
PostgreSQL	16	Relational database engine
Jakarta Validation	^3.0	Validation of data contracts and monetary restrictions

💻 Development Commands

The backend requires port 8080 to be available and the local database to operate on port 5433.

# Initializes the isolated PostgreSQL container with a persistent volume
docker-compose up -d

# Compiles the code, downloads dependencies and generates the executable (.jar)
mvn clean package

# Starts the embedded web application in the local Tomcat server
mvn spring-boot:run

📡 API Documentation

All responses with business error codes or HTTP 400 validation return the standardized structure: {"error": "Failure detail"}.

💼 Accounts and Queries (/api/v1/portafolios)

Method	Endpoint	Description	Access / Payload
POST	/inicializar/{usuarioId}	Registers and initializes a new zero-balance financial portfolio (for demo).	Public / None
GET	/{usuarioId}	Obtains the detailed current balances of the account in MXN and USDC.	Public / Read-Only

💱 Financial Mutations (/api/v1/portafolios/{usuarioId})

Method	Endpoint	Description	Required Payload	Restrictions / Validations
PUT	/inyeccion	Executes the safe addition and funding of capital in pesos to the balance.	JSON with monto	@NotNull, @Positive (Amount > 0)
PUT	/comprar-usdc	Performs the atomic Swap of MXN balance to acquire crypto dollars.	JSON with montoMxn and tipoCambio	Sufficient Funds, @Positive
PUT	/reiniciar	Idempotent operation that resets balances to zero (Demo Mode).	None	Resets the complete balance