> ## 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 Report Generator

> Reporting API - Dynamic CSV/PDF Report Generator (Backend)

Welcome to the documentation of the second microservice of the project. My Portfolio's Dynamic Report Generator (CSV/PDF)!

This project acts as a high-precision *stateless* microservice. It is optimized to ingest data payloads (JSON) and dynamically transform them into financial reports (CSV and PDF), minimizing the I/O impact on the infrastructure.

## 🚀 Features and Backend Architecture

<CardGroup cols={2}>
  <Card title="Strategy Pattern" icon="chess-knight">
    Absolute decoupling in the main controller through PHP 8 `match` expressions. The rendering logic is delegated to standardized contracts (`ReportStrategy`).
  </Card>

  <Card title="Stateless Memory" icon="cpu">
    Use of raw memory streams (`php://temp`) to compile heavy binary files (CSVs) directly into RAM, avoiding physical disk writes.
  </Card>

  <Card title="Perimeter Security" icon="shield-check">
    Rate Limiting (Throttle) middlewares that block massive requests (DoS) by limiting consumption per IP on the `/api/v1/` routes.
  </Card>

  <Card title="Timezone Synchronization" icon="clock">
    The engine captures and dynamically adapts the client's timezone, ensuring temporal consistency in metadata and timestamps.
  </Card>

  <Card title="Defensive Sanitization" icon="eraser">
    Data interception and normalization. Unrecognized states are isolated under default classifiers to protect metrics (KPIs).
  </Card>

  <Card title="Automated Testing" icon="flask-conical">
    Coverage of mathematical integrity and validation of export flows using the **Pest** framework.
  </Card>
</CardGroup>

## 🛠️ Tech Stack

| Technology  | Version | Project Purpose                                       |
| :---------- | :------ | :---------------------------------------------------- |
| **Laravel** | `^13.0` | Base framework operating in REST API mode             |
| **PHP**     | `^8.3`  | Server language (strict typing and match expressions) |
| **Dompdf**  | `^3.0`  | Rendering engine to compile HTML/CSS templates to PDF |
| **Pest**    | `^3.0`  | Testing framework for artifact validation             |

## 💻 Development Commands

Instructions to set up the environment locally (assuming port `8000` is free).

```bash theme={null}
# Install dependencies
composer install

# Configure environment variables
cp .env.example .env

# Start local server
php artisan serve --port=8000

# Run test suite
php artisan test
```

## 📡 API Documentation (Endpoints)

The microservice exposes lightweight routes designed for inter-service communication or asynchronous calls from the frontend.

### 🩺 Health Check (`/api/v1`)

| Method | Endpoint | Description                          | Response        |
| :----- | :------- | :----------------------------------- | :-------------- |
| `GET`  | `/ping`  | Validates the engine's availability. | `200 OK` (JSON) |

### 🖨️ Artifact Rendering (`/api/v1/reportes`)

| Method | Endpoint   | Description                                                           | Required Payload                                 | Restrictions                   |
| :----- | :--------- | :-------------------------------------------------------------------- | :----------------------------------------------- | :----------------------------- |
| `POST` | `/generar` | Compiles the requested document and returns the binary file (`Blob`). | JSON with `formato`, `timezone` and `data.items` | Max. 10 requests/minute per IP |

***