AcctAtlas User Service

User identity and access management service for AccountabilityAtlas. Handles registration, authentication (email/password + OAuth), JWT token issuance, profile management, and trust tier progression.

Prerequisites

• Docker Desktop (for PostgreSQL and Redis)
• Git

JDK 21 is managed automatically by the Gradle wrapper via Foojay Toolchain -- no manual JDK installation required.

Clone and Build

git clone <repo-url>
cd AcctAtlas-user-service

Build the project (downloads JDK 21 automatically on first run):

# Linux/macOS
./gradlew build

# Windows
gradlew.bat build

Local Development

Start dependencies

docker-compose up -d

This starts PostgreSQL 17 and Redis 7. Flyway migrations run automatically when the service starts.

Run the service

# Linux/macOS
./gradlew bootRun

# Windows
gradlew.bat bootRun

The service starts on http://localhost:8081.

Quick API test

# Health check
curl http://localhost:8081/actuator/health

# Register a new user
curl -X POST http://localhost:8081/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"SecurePass123","displayName":"TestUser"}'

# Login (save the accessToken from the response)
curl -X POST http://localhost:8081/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"SecurePass123"}'

# Get current user profile (replace TOKEN with accessToken from login)
curl http://localhost:8081/users/me \
  -H "Authorization: Bearer TOKEN"

Run tests

./gradlew test

Integration tests use TestContainers to spin up PostgreSQL automatically -- Docker must be running.

Code formatting

Formatting is enforced by Spotless using Google Java Format.

# Check formatting
./gradlew spotlessCheck

# Auto-fix formatting
./gradlew spotlessApply

Full quality check

Runs Spotless, Error Prone, tests, and JaCoCo coverage verification (80% minimum):

./gradlew check

Docker Image

Build a Docker image locally using Jib (no Dockerfile needed):

./gradlew jibDockerBuild

Build and start the full stack (service + Postgres + Redis) in Docker:

./gradlew composeUp

Project Structure

src/main/java/com/accountabilityatlas/userservice/
  config/        Spring configuration (Security, JPA, JWT)
  domain/        JPA entities (User, Session, OAuthLink, etc.)
  repository/    Spring Data JPA repositories
  service/       Business logic
  web/           Controller implementations
  event/         Event publisher interface

src/main/resources/
  application.yml          Shared config
  application-local.yml    Local dev overrides
  db/migration/            Flyway SQL migrations

src/test/java/.../
  domain/        Entity unit tests
  service/       Service unit tests (Mockito)
  web/           Controller tests (@WebMvcTest)
  integration/   Integration tests (TestContainers)

API interfaces and DTOs are generated from docs/api-specification.yaml by the OpenAPI Generator plugin into build/generated/.

Key Gradle Tasks

Task	Description
bootRun	Run the service locally (uses local profile)
test	Run all tests
unitTest	Run unit tests only (no Docker required)
integrationTest	Run integration tests only (requires Docker)
check	Full quality gate (format + analysis + tests + coverage)
spotlessApply	Auto-fix code formatting
jibDockerBuild	Build Docker image
composeUp	Build image + docker-compose up
composeDown	Stop docker-compose services

Documentation

• Technical Overview
• API Specification (OpenAPI 3.1)
• Authentication Flows
• Database Schema
• Trust Tier Logic