patbond-api/Readme.md

Patbond API

Patbond API is a Spring Boot multi-module backend.

Modules

• patbond-common: stable cross-module contracts (response wrapper, shared DTOs). No web/messaging dependencies.
• patbond-user: user service for user creation, profile lookup, and password verification.
• patbond-auth: authentication service for registration and login. Calls patbond-user over HTTP via OpenFeign with a configured static URL (no service discovery in the MVP, see ADR-002).

Technology Stack

• Java 17 (build baseline; use JDK 17 for release builds)
• Spring Boot 3.5.16
• Spring Cloud 2025.0.3 (OpenFeign only)
• PostgreSQL 16 + Flyway (patbond-user owns the identity/media schemas)
• Maven (use the committed Maven Wrapper ./mvnw)

Build and Test

./mvnw clean test

Integration tests start a disposable postgres:16 via Testcontainers, so a running Docker daemon is required (no local PostgreSQL installation or credentials are needed).

If your default JDK is not 17, point JAVA_HOME at a JDK 17 installation first, e.g.:

JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test

Run

Running patbond-user requires a reachable PostgreSQL 16 database; Flyway applies the versioned migrations in patbond-user/src/main/resources/db/migration automatically on startup. Development seed data (db/dev, regions reference rows) is opt-in via a dev profile — see application.yml.sample.

Each service ships a committed application.yml.sample; the real application.yml is git-ignored. First copy the samples (defaults work locally, overrides via environment variables):

cp patbond-user/src/main/resources/application.yml.sample \
  patbond-user/src/main/resources/application.yml
cp patbond-auth/src/main/resources/application.yml.sample \
  patbond-auth/src/main/resources/application.yml

Install the shared module once, then run each service in its own terminal:

./mvnw -pl patbond-common install
./mvnw -pl patbond-user spring-boot:run
./mvnw -pl patbond-auth spring-boot:run

Tests do not require this copy step — patbond-auth/src/test/resources/application.yml keeps ./mvnw clean test self-contained on a clean checkout.

Smoke check:

curl -X POST http://127.0.0.1:8081/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo_user","password":"secret123"}'

Configuration

Environment variable	Default	Used by
PATBOND_USER_PORT	8082	patbond-user
PATBOND_AUTH_PORT	8081	patbond-auth
PATBOND_USER_SERVICE_URL	http://127.0.0.1:8082	patbond-auth (Feign target for patbond-user)
PATBOND_DB_URL	jdbc:postgresql://127.0.0.1:5432/patbond	patbond-user
PATBOND_DB_USER	patbond	patbond-user
PATBOND_DB_PASSWORD	patbond	patbond-user

Machine-specific values live in the git-ignored application.yml (copied from the committed .sample); never commit secrets to the samples.

Services

Auth Service

• Application name: patbond-auth
• Default port: 8081
• Register: POST /auth/register
• Login: POST /auth/login

User Service

• Application name: patbond-user
• Default port: 8082
• Create user: POST /internal/users
• Verify password: POST /internal/users/verify-password
• Get user by id: GET /internal/users/{id}
• Get user by username: GET /internal/users/by-username/{username}

Note: user data is persisted in PostgreSQL (identity.users / identity.user_credentials, bcrypt password hashes, UUIDv7 ids generated in the application). Errors follow the {code, message, data} envelope with stable business codes and matching HTTP statuses. Verifiable JWT tokens, refresh sessions, and /internal access control are planned in iteration 1 follow-up tasks.