> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 🏦 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

<CardGroup cols={2}>
  <Card title="ACID Concurrency" icon="lock">
    Strict implementation of transactional isolation at the persistence level through pessimistic locking, completely nullifying Race Conditions.
  </Card>

  <Card title="Precision Arithmetic" icon="calculator">
    Absolute use of the `BigDecimal` class complemented by strict banking rounding policies (`RoundingMode.HALF_UP`), mitigating floating-point failures.
  </Card>

  <Card title="Perimeter Validation" icon="shield-check">
    Centralization and sanitization of Payloads through Jakarta Validation at the HTTP layer (`@Valid`), catching failures with a global interceptor (`@ControllerAdvice`).
  </Card>

  <Card title="Secure Infrastructure" icon="docker">
    *Multi-stage* packaging pipeline based on Alpine Linux (JRE), with native injection of JVM tuning flags and privilege isolation.
  </Card>
</CardGroup>

## 🛠️ 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`.

```bash theme={null}
# 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          |