Biblioteca Maxipet

01 What it is

A Spring Boot 3 API on Java 17 for the Maxipet corporate platform. It is the migration of the original Flask application: same PostgreSQL, same users, new backend. It serves a React + Vite SPA hosted on Vercel and covers document management, KPIs and objectives, complaints, corrective actions, safety alerts, questionnaires, audit log and staff directory.

• Content by category (documents, manuals, courses, lessons, bulletin, warehouses): upload, list, delete and comments on bulletin and lessons.
• KPIs and objectives with create and delete; complaints with evidence, editing, attached solution and stats.
• Corrective actions with activities by reference number, global pending items and status changes.
• Safety: alerts, general material, podcast, video and questionnaires with a single answer per user.
• Audit log of every mutation, dashboard with a day counter and user directory.
• Account: 2FA via TOTP or email, login alerts, active sessions and own activity.

02 The migration

The platform was already in production and had to be modernized without stopping operations or touching the data. Flyway takes over the schema with versioned migrations and Hibernate only validates: it never modifies.

1. Flyway detects that the schema is not empty and that flyway_schema_history does not exist (baseline-on-migrate=true, baseline-version=1).
2. It creates the table with a baseline record marked V1 and does not re-run V1: the current schema already is V1.
3. It applies V2 onwards on the existing schema; all of them are idempotent (IF NOT EXISTS, WHERE NOT EXISTS).
4. Hibernate runs validate. If everything matches, the app starts.

03 Architecture

Chain: Cloudflare Tunnel → Nginx (127.0.0.1:80) → JVM (127.0.0.1:8080). The app needs no public port; cloudflared points its ingress at local Nginx and the tunnel provides the encrypted transport. Spring processes X-Forwarded-* with forward-headers-strategy=framework, so the real IP reaches the rate limiter and the Secure cookie knows the request came over HTTPS.

Two profiles: default for development (rate limiting off, secrets with fallback, verbose errors) and prod (rate limiting on, secrets required from the environment, minimal errors, JSON logs). In prod, ProdSecretsValidator refuses to start if JWT_SECRET or APP_ENCRYPTION_KEY are still the development values.

04 Getting started

Requirements: Java 17, PostgreSQL 12+ (tested on 18) and, optionally, Docker. With Docker the container runs as a non-root user and mounts the uploads volume.

> ./mvnw spring-boot:run              # dev; lee DATABASE_URL, DB_USERNAME y DB_PASSWORD del .env
> ./mvnw -DskipTests package && java -jar target/biblioteca-api-1.0.0.jar --spring.profiles.active=prod
> docker compose up -d --build        # api + db; usuario no root y volumen uploads
> docker compose logs -f api
> curl http://localhost:8080/actuator/health   # {"status":"UP"}

The application never creates a user on its own: on an empty database nobody can log in until the first one is inserted by hand, once per installation. From then on, the rest are created from Users → New user.

> python3 -c "import bcrypt,getpass; print(bcrypt.hashpw(getpass.getpass().encode(), bcrypt.gensalt(12)).decode())"
> psql -U bibliotecario -d biblioteca_maxipet -c "INSERT INTO users (username, password_hash, role, full_name) VALUES (…, …, 'super_admin', …);"

05 API reference

Everything under /api/* requires a JWT (Authorization: Bearer …) except login, verify-2fa, refresh, logout and /actuator/health. Errors come as JSON: 400 with fields on validation or malformed JSON, 401, 403 by role, 404 on unknown routes and 429 on rate limit.

06 Security

Every control exists for a concrete scenario: a stolen token, a leaked password, a malicious file or a read of the database. The idea is that none of them, on its own, is enough.

07 Production

Nginx is the critical piece: without X-Forwarded-Proto https the refresh cookie ships without Secure, and without real_ip_header CF-Connecting-IP (accepted only from Cloudflare ranges) the rate limiter would see the tunnel IP.

> upstream biblioteca_api { server 127.0.0.1:8080; }
> real_ip_header CF-Connecting-IP;                 # con set_real_ip_from para cada rango de Cloudflare
> client_max_body_size 50M;                        # subidas grandes
> proxy_set_header X-Forwarded-Proto https;        # la cookie Secure depende de esto
> location /_protected/ { internal; alias /srv/biblioteca-uploads/; }   # X-Accel-Redirect

• Files via X-Accel-Redirect: Spring validates session and role and replies with the header and an empty body; Nginx serves from disk. The uploads volume is a bind mount (/srv/biblioteca-uploads, UID 1000) readable by both.
• JSON logs on stdout with requestId; an X-Request-Id sent by the load balancer is honored or a UUID is generated, and it is returned in the response to correlate tickets.
• At the Cloudflare edge: rate limiting on /api/auth/login and /api/auth/refresh, WAF managed rules and Bot Fight Mode.
• For 2+ instances: RATE_LIMIT_BACKEND=redis; otherwise buckets are per process.

> curl https://app.<dominio>/actuator/health                       # {"status":"UP"}
> curl -i -X POST https://app.<dominio>/api/auth/login -H "Content-Type: application/json" -d '{"username":"…","password":"…"}'
> # → Set-Cookie: refreshToken=…; HttpOnly; Secure; SameSite=None; Path=/api/auth
> journalctl -u biblioteca-api -f --output=cat | jq .            # logs JSON con requestId
> ./mvnw test                                                    # 18 tests de cifrado y rotación, < 3 s

08 Database

The audit log is written in its own transaction (REQUIRES_NEW): if the insert fails it does not break the operation, but it is logged as ERROR so a gap in the audit trail does raise an alert.

> SELECT version, description, installed_on, success FROM flyway_schema_history ORDER BY installed_rank;