From 1cebc9f2013423a2b0cbc80791a828e23d549982 Mon Sep 17 00:00:00 2001
From: Daniel <daniel.guo@vivalabs.com.au>
Date: Mon, 1 Dec 2025 14:29:26 +1100
Subject: [PATCH 1/3] Add ci config, and commit/push hooks

---
 .githooks/pre-commit     |  24 +++++
 .githooks/pre-push       |  25 ++++++
 .github/workflows/ci.yml | 114 ++++++++++++++++++++++++
 auto/setup-hooks         |  16 ++++
 roadmap.md               | 185 ++++++++++++++++++++++++++++++---------
 5 files changed, 324 insertions(+), 40 deletions(-)
 create mode 100755 .githooks/pre-commit
 create mode 100755 .githooks/pre-push
 create mode 100644 .github/workflows/ci.yml
 create mode 100755 auto/setup-hooks

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..680bcbb
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+
+set -e
+
+echo "🔍 Running pre-commit checks..."
+
+# Check for staged Java files
+STAGED_JAVA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.java$' ||
+true)
+
+if [ -n "$STAGED_JAVA_FILES" ]; then
+    echo "📝 Checking code format..."
+    ./gradlew spotlessCheck --quiet
+
+    if [ $? -ne 0 ]; then
+        echo ""
+        echo "❌ Code formatting issues found!"
+        echo "Run './gradlew spotlessApply' to fix them."
+        exit 1
+    fi
+    echo "✅ Code format OK"
+fi
+
+echo "✅ Pre-commit checks passed!"
\ No newline at end of file
diff --git a/.githooks/pre-push b/.githooks/pre-push
new file mode 100755
index 0000000..586f243
--- /dev/null
+++ b/.githooks/pre-push
@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+
+set -e
+
+echo "🚀 Running pre-push checks..."
+
+# Run tests
+echo "🧪 Running tests..."
+./gradlew test --quiet
+
+if [ $? -ne 0 ]; then
+    echo "❌ Tests failed! Push aborted."
+    exit 1
+fi
+
+# Check coverage
+echo "📊 Checking test coverage..."
+./gradlew jacocoTestCoverageVerification --quiet
+
+if [ $? -ne 0 ]; then
+    echo "❌ Coverage below threshold! Push aborted."
+    exit 1
+fi
+
+echo "✅ All pre-push checks passed!"
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..dcf86d0
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,114 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [ ready_for_review, opened, reopened, synchronize ]
+  push:
+    branches: [ main ]
+# Cancel in-progress runs for the same PR/branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    # Skip draft PRs
+    if: github.event.pull_request.draft == false
+
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test-db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --heath-interval 10s
+          --health-timeout 5s
+          --health-retries 3
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Cache Gradle packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: ${{ runner.os }}-gradle-
+
+      - name: Grant execute permissions for gradlew
+        run: chmod +x gradlew
+
+      - name: Check code formatting
+        run: ./gradlew spotlessCheck
+
+      - name: Build
+        run: ./gradlew build -x test
+
+      - name: Run tests
+        run: ./gradlew test
+        env:
+          SPRING_DATASOURCE_URL: jdbc:postgresql://localhost:5432/test-db
+          SPRING_DATASOURCE_USERNAME: test
+          SPRING_DATASOURCE_PASSWORD: test
+
+      - name: Generate test coverage report
+        run: ./gradlew jacocoTestReport
+
+      - name: Check test coverage
+        run: ./gradlew jacocoTestCoverageVerification
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: coverage-report
+          path: build/reports/jacoco/test/html/
+          retention-days: 7
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: test-results
+          path: build/reports/tests/test/
+          retention-days: 7
+
+  # Add coverage comment to PR
+  coverage-comment:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Download coverage report
+        uses: actions/download-artifact@v6
+        with:
+          name: coverage-report
+          path: coverage
+
+      - name: Add coverage to PR
+        uses: madrapps/jacoco-report@v1.7.2
+        with:
+          paths: build/reports/jacoco/test/jacocoTestReport.xml
+          token: ${{ secrets.GITHUB_TOKEN }}
+          min-coverage-overall: 80
+          min-coverage-changed-files: 80
+
+
diff --git a/auto/setup-hooks b/auto/setup-hooks
new file mode 100755
index 0000000..a8a5cb0
--- /dev/null
+++ b/auto/setup-hooks
@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -e
+
+echo "🔧 Setting up git hooks..."
+
+# Configure git to use .githooks directory
+git config core.hooksPath .githooks
+
+# Make hooks executable
+chmod +x .githooks/*
+
+echo "✅ Git hooks configured!"
+echo ""
+echo "Hooks installed:"
+echo "  - pre-commit: Format check"
+echo "  - pre-push: Tests + coverage"
\ No newline at end of file
diff --git a/roadmap.md b/roadmap.md
index e740804..51e6891 100644
--- a/roadmap.md
+++ b/roadmap.md
@@ -1,10 +1,12 @@
 # User Service Feature Extension Roadmap
 
-This document provides a comprehensive roadmap for extending the current user authentication and management service into an enterprise-grade SaaS user module.
+This document provides a comprehensive roadmap for extending the current user authentication and
+management service into an enterprise-grade SaaS user module.
 
 ## Current State Analysis
 
 ### Strengths
+
 - ✅ Solid JWT authentication with token rotation and breach detection
 - ✅ Role-based access control foundation (ADMIN/MEMBER)
 - ✅ PostgreSQL with Flyway migrations
@@ -15,6 +17,7 @@ This document provides a comprehensive roadmap for extending the current user au
 - ✅ Basic audit timestamps (createdAt, updatedAt)
 
 ### Extension Points
+
 - User entity has `isEmailVerified` field (ready for email verification)
 - Security configuration extensible for OAuth2
 - Repository pattern ready for advanced features
@@ -28,9 +31,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 1: Email Infrastructure & Basic Security (Priority: HIGH)
 
 #### 1.1 Email Service Foundation
+
 **Goal**: Establish email sending infrastructure for all email-based features
 
 **Features**:
+
 - Email service abstraction (SMTP, SendGrid, AWS SES)
 - HTML email templates with Thymeleaf/FreeMarker
 - Email queuing and retry logic
@@ -43,9 +48,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 1.2 Email Verification
+
 **Goal**: Verify user email addresses during registration
 
 **Features**:
+
 - Generate secure verification tokens
 - Send verification email on registration
 - Verify email endpoint with token validation
@@ -55,6 +62,7 @@ This document provides a comprehensive roadmap for extending the current user au
 **Database**: `email_verification_tokens` table (id, userId, token, expiresAt, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/users/auth/verify-email` - verify with token
 - `POST /api/users/auth/resend-verification` - resend email
 
@@ -63,9 +71,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 1.3 Password Reset via Email
+
 **Goal**: Allow users to reset forgotten passwords securely
 
 **Features**:
+
 - Request password reset (rate-limited)
 - Send reset link via email
 - Validate reset token
@@ -75,6 +85,7 @@ This document provides a comprehensive roadmap for extending the current user au
 **Database**: `password_reset_tokens` table (id, userId, token, expiresAt, used, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/users/auth/forgot-password` - request reset
 - `POST /api/users/auth/reset-password` - reset with token
 - `GET /api/users/auth/validate-reset-token` - validate token
@@ -86,9 +97,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 1.4 Passwordless Login (Email OTP)
+
 **Goal**: Allow users to log in using one-time codes sent via email
 
 **Features**:
+
 - Request login code via email
 - Generate 6-digit numeric OTP (5-minute expiration)
 - Verify OTP and issue JWT tokens
@@ -98,15 +111,18 @@ This document provides a comprehensive roadmap for extending the current user au
 **Database**: `login_codes` table (id, email, code, expiresAt, attempts, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/users/auth/request-login-code` - send OTP to email
 - `POST /api/users/auth/verify-login-code` - verify OTP and login
 
 **Use Cases**:
+
 - Passwordless authentication option
 - Alternative to password for verified users
 - Temporary access method
 
 **Security Considerations**:
+
 - 6-digit code with 5-minute expiration
 - Maximum 3 verification attempts per code
 - Rate limit: 3 code requests per 15 minutes per email
@@ -117,15 +133,18 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 1.5 Rate Limiting & Brute Force Protection
+
 **Goal**: Protect against abuse and automated attacks
 
 **Features**:
+
 - Rate limiting with Redis + Bucket4j
 - Per-endpoint rate limits (login, registration, password reset)
 - IP-based and user-based limiting
 - 429 Too Many Requests responses
 
 **Rate Limits**:
+
 - Login: 5 attempts per 15 minutes (per IP + email)
 - Registration: 3 accounts per hour (per IP)
 - Password reset: 3 requests per hour (per email)
@@ -138,16 +157,19 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 1.6 Account Lockout & Security Monitoring
+
 **Goal**: Automatic lockout after suspicious activity
 
 **Features**:
+
 - Lock account after 5 failed login attempts
 - Automatic unlock after 30 minutes
 - Manual admin unlock
 - Email notification on lockout
 - Track failed attempts and last failure time
 
-**Database**: Add columns to `users` table (isLocked, lockedAt, lockedReason, failedLoginAttempts, lastFailedLoginAt)
+**Database**: Add columns to `users` table (isLocked, lockedAt, lockedReason, failedLoginAttempts,
+lastFailedLoginAt)
 
 **Estimated Effort**: 2 days
 
@@ -156,18 +178,22 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 2: Session Management & Device Tracking (Priority: HIGH)
 
 #### 2.1 Session Management
+
 **Goal**: Track and manage user sessions across devices
 
 **Features**:
+
 - Track active sessions with device info
 - "Where you're logged in" feature
 - Revoke specific sessions
 - "Logout from all devices" (already exists, enhance with session details)
 - Session activity monitoring
 
-**Database**: `user_sessions` table (id, userId, refreshTokenId, deviceName, browser, os, ipAddress, location, lastActivityAt, createdAt)
+**Database**: `user_sessions` table (id, userId, refreshTokenId, deviceName, browser, os, ipAddress,
+location, lastActivityAt, createdAt)
 
 **API Endpoints**:
+
 - `GET /api/users/me/sessions` - list active sessions
 - `DELETE /api/users/me/sessions/{sessionId}` - revoke specific session
 - `DELETE /api/users/me/sessions` - revoke all sessions
@@ -179,9 +205,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 2.2 Security Alerts & Suspicious Activity Detection
+
 **Goal**: Detect and alert users of unusual login patterns
 
 **Features**:
+
 - Detect logins from new locations
 - Detect logins from new devices
 - Alert via email for suspicious activity
@@ -189,6 +217,7 @@ This document provides a comprehensive roadmap for extending the current user au
 - Login history with timestamps and locations
 
 **API Endpoints**:
+
 - `GET /api/users/me/login-history` - view login history
 - `POST /api/users/me/confirm-login/{loginId}` - confirm suspicious login
 
@@ -199,9 +228,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 3: Social Authentication (Priority: HIGH)
 
 #### 3.1 OAuth2 Social Login
+
 **Goal**: Enable login via Google, GitHub, Facebook
 
 **Features**:
+
 - OAuth2 integration with Spring Security
 - Account creation via social login
 - Link/unlink social accounts to existing users
@@ -210,15 +241,18 @@ This document provides a comprehensive roadmap for extending the current user au
 
 **Providers**: Google, GitHub, Facebook (extensible to Twitter, LinkedIn, etc.)
 
-**Database**: `social_accounts` table (id, userId, provider, providerId, email, profilePicture, accessToken, refreshToken, createdAt, updatedAt)
+**Database**: `social_accounts` table (id, userId, provider, providerId, email, profilePicture,
+accessToken, refreshToken, createdAt, updatedAt)
 
 **API Endpoints**:
+
 - `GET /oauth2/authorization/{provider}` - initiate OAuth2 flow
 - `POST /api/users/me/social-accounts/{provider}` - link account
 - `DELETE /api/users/me/social-accounts/{provider}` - unlink account
 - `GET /api/users/me/social-accounts` - list linked accounts
 
-**Security**: Handle email matching, require verification for account linking, make User.password nullable
+**Security**: Handle email matching, require verification for account linking, make User.password
+nullable
 
 **Dependencies**: spring-boot-starter-oauth2-client
 
@@ -229,9 +263,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 4: Advanced Authorization (RBAC) (Priority: MEDIUM-HIGH)
 
 #### 4.1 Enhanced Role-Based Access Control (RBAC)
+
 **Goal**: Fine-grained permissions beyond simple roles
 
 **Features**:
+
 - Hierarchical roles with permissions
 - Custom role creation per tenant
 - Permission-based access control (`resource:action` format)
@@ -240,17 +276,20 @@ This document provides a comprehensive roadmap for extending the current user au
 - Role assignment and management
 
 **Database**:
+
 - `roles` table (id, tenantId, name, description, isSystem, createdAt, updatedAt)
 - `permissions` table (id, resource, action, description)
 - `role_permissions` table (roleId, permissionId)
 - `user_roles` table (userId, roleId, tenantId, grantedBy, grantedAt)
 
 **Permission Examples**:
+
 - `users:create`, `users:read`, `users:update`, `users:delete`
 - `settings:read`, `settings:write`
 - `billing:read`, `billing:write`
 
 **API Endpoints**:
+
 - `GET /api/roles` - list available roles
 - `POST /api/roles` - create custom role (admin only)
 - `PATCH /api/roles/{roleId}` - update role permissions
@@ -268,18 +307,22 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 5: API Keys & Service Accounts (Priority: MEDIUM-HIGH)
 
 #### 5.1 API Key Management
+
 **Goal**: Enable programmatic access with API keys
 
 **Features**:
+
 - Generate API keys for users/tenants
 - Scoped permissions for API keys
 - Key rotation and expiration
 - Multiple keys per user
 - Usage tracking and analytics
 
-**Database**: `api_keys` table (id, userId, tenantId, name, keyHash, prefix, permissions, expiresAt, lastUsedAt, createdAt)
+**Database**: `api_keys` table (id, userId, tenantId, name, keyHash, prefix, permissions, expiresAt,
+lastUsedAt, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/users/me/api-keys` - create API key
 - `GET /api/users/me/api-keys` - list API keys
 - `DELETE /api/users/me/api-keys/{keyId}` - revoke key
@@ -287,16 +330,19 @@ This document provides a comprehensive roadmap for extending the current user au
 
 **Format**: `sk_live_1234567890abcdef` (prefix + random string)
 
-**Security**: Store hashed keys, show full key only on creation, support key prefixes for identification
+**Security**: Store hashed keys, show full key only on creation, support key prefixes for
+identification
 
 **Estimated Effort**: 3-4 days
 
 ---
 
 #### 5.2 Service Accounts
+
 **Goal**: Machine-to-machine authentication
 
 **Features**:
+
 - Create service accounts (non-human users)
 - Service account authentication via API keys
 - Dedicated permissions for service accounts
@@ -311,9 +357,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 6: Audit Logging (Priority: MEDIUM)
 
 #### 6.1 Comprehensive Audit Trail
+
 **Goal**: Track all significant user and system actions
 
 **Features**:
+
 - Automatic auditing via AOP annotations
 - Track authentication events (login, logout, password changes)
 - Track authorization events (permission denied, role changes)
@@ -322,15 +370,18 @@ This document provides a comprehensive roadmap for extending the current user au
 - Async logging for performance
 - Query and export audit logs
 
-**Database**: `audit_logs` table (id, tenantId, userId, action, resource, resourceId, status, ipAddress, userAgent, details JSONB, createdAt)
+**Database**: `audit_logs` table (id, tenantId, userId, action, resource, resourceId, status,
+ipAddress, userAgent, details JSONB, createdAt)
 
 **Events**:
+
 - Authentication: LOGIN, LOGOUT, REGISTER, PASSWORD_CHANGED, PASSWORD_RESET
 - User management: USER_CREATED, USER_UPDATED, USER_DELETED
 - Authorization: PERMISSION_DENIED, ROLE_CHANGED
 - API: API_KEY_CREATED, API_KEY_REVOKED
 
 **API Endpoints**:
+
 - `GET /api/audit-logs` - query logs (admin only)
 - `GET /api/users/me/audit-logs` - user's own audit trail
 - `GET /api/audit-logs/export` - CSV export for compliance
@@ -344,9 +395,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 7: Event-Driven Architecture (Priority: MEDIUM)
 
 #### 7.1 Kafka Event Bus
+
 **Goal**: Publish domain events for decoupling and scalability
 
 **Features**:
+
 - Apache Kafka 4 (KRaft mode - no Zookeeper)
 - Publish domain events (user.registered, user.updated, user.login, etc.)
 - Event schema with JSON
@@ -354,11 +407,13 @@ This document provides a comprehensive roadmap for extending the current user au
 - Kafka listeners for internal consumption
 
 **Topics**:
+
 - `user.registered`, `user.updated`, `user.deleted`
 - `user.login`, `user.logout`, `user.password-changed`
 - `user.email-verified`, `session.created`, `session.revoked`
 
 **Event Schema**:
+
 ```json
 {
   "eventId": "uuid",
@@ -379,9 +434,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 7.2 Notification Service
+
 **Goal**: Send notifications via multiple channels
 
 **Features**:
+
 - Consume Kafka events for notifications
 - Email notifications (welcome, verification, alerts)
 - SMS notifications (future: 2FA, critical alerts)
@@ -390,6 +447,7 @@ This document provides a comprehensive roadmap for extending the current user au
 - Notification preferences per user
 
 **Notification Types**:
+
 - Welcome email on registration
 - Email verification reminders
 - Password reset confirmation
@@ -405,9 +463,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 8: User Preferences & Settings (Priority: MEDIUM)
 
 #### 8.1 User Preferences
+
 **Goal**: Allow users to customize their experience
 
 **Features**:
+
 - Language/locale preferences
 - Timezone settings
 - Date/time format preferences
@@ -415,9 +475,11 @@ This document provides a comprehensive roadmap for extending the current user au
 - In-app notification preferences
 - Theme preferences (light/dark mode)
 
-**Database**: `user_preferences` table (userId, language, timezone, dateFormat, emailNotifications JSONB, themeMode, updatedAt)
+**Database**: `user_preferences` table (userId, language, timezone, dateFormat, emailNotifications
+JSONB, themeMode, updatedAt)
 
 **API Endpoints**:
+
 - `GET /api/users/me/preferences` - get preferences
 - `PATCH /api/users/me/preferences` - update preferences
 
@@ -428,25 +490,30 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 9: Advanced Security Features (Priority: MEDIUM)
 
 #### 9.1 Two-Factor Authentication (2FA/MFA)
+
 **Goal**: Add TOTP-based 2FA for enhanced security
 
 **Features**:
+
 - TOTP-based 2FA (Google Authenticator compatible)
 - Setup flow with QR code generation
 - Backup codes (10 single-use codes)
 - 2FA enforcement options (optional, required for admins)
 - Remember device option
 
-**Database**: Add to `users` table (isMfaEnabled, mfaSecret encrypted, mfaBackupCodes encrypted, mfaEnabledAt)
+**Database**: Add to `users` table (isMfaEnabled, mfaSecret encrypted, mfaBackupCodes encrypted,
+mfaEnabledAt)
 
 **API Endpoints**:
+
 - `POST /api/users/me/mfa/setup` - initialize 2FA
 - `POST /api/users/me/mfa/enable` - enable with verification
 - `POST /api/users/me/mfa/disable` - disable 2FA
 - `GET /api/users/me/mfa/backup-codes` - get backup codes
 - `POST /api/users/me/mfa/regenerate-backup-codes` - regenerate
 
-**Authentication Flow**: Login returns `mfaRequired: true`, then verify with `POST /api/users/auth/mfa-verify`
+**Authentication Flow**: Login returns `mfaRequired: true`, then verify with
+`POST /api/users/auth/mfa-verify`
 
 **Dependencies**: google-authenticator, zxing (QR codes)
 
@@ -455,9 +522,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 #### 9.2 IP Whitelisting & Access Control
+
 **Goal**: Restrict access to specific IP ranges (enterprise feature)
 
 **Features**:
+
 - Tenant-level IP whitelisting
 - User-level IP restrictions
 - IP range validation (CIDR notation)
@@ -466,6 +535,7 @@ This document provides a comprehensive roadmap for extending the current user au
 **Database**: `ip_whitelist` table (id, tenantId, userId, ipRange CIDR, description, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/tenants/{tenantId}/ip-whitelist` - add IP range
 - `GET /api/tenants/{tenantId}/ip-whitelist` - list ranges
 - `DELETE /api/tenants/{tenantId}/ip-whitelist/{id}` - remove range
@@ -477,9 +547,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 10: Webhooks (Priority: MEDIUM)
 
 #### 10.1 Webhook Management
+
 **Goal**: Allow tenants to subscribe to events via webhooks
 
 **Features**:
+
 - Register webhook endpoints per tenant
 - Subscribe to specific events
 - Webhook signature verification (HMAC)
@@ -488,10 +560,12 @@ This document provides a comprehensive roadmap for extending the current user au
 - Test webhook endpoints
 
 **Database**:
+
 - `webhooks` table (id, tenantId, url, secret, events[], isActive, createdAt)
 - `webhook_deliveries` table (id, webhookId, eventId, status, attempts, response, createdAt)
 
 **API Endpoints**:
+
 - `POST /api/tenants/{tenantId}/webhooks` - create webhook
 - `GET /api/tenants/{tenantId}/webhooks` - list webhooks
 - `PATCH /api/tenants/{tenantId}/webhooks/{id}` - update webhook
@@ -507,9 +581,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 11: Data Management & Compliance (Priority: LOW-MEDIUM)
 
 #### 11.1 Soft Delete & Data Retention
+
 **Goal**: GDPR-compliant data deletion and retention
 
 **Features**:
+
 - Soft delete for users and tenants
 - Configurable retention periods
 - Hard delete after retention period
@@ -519,6 +595,7 @@ This document provides a comprehensive roadmap for extending the current user au
 **Database**: Add `deletedAt` column to `users`, `tenants` tables
 
 **API Endpoints**:
+
 - `DELETE /api/users/me` - soft delete account
 - `POST /api/users/me/export-data` - export user data (JSON)
 - `POST /api/users/me/delete-permanently` - confirm permanent deletion
@@ -532,9 +609,11 @@ This document provides a comprehensive roadmap for extending the current user au
 ### Phase 12: Multi-Tenancy Support (Priority: LOW)
 
 #### 12.1 Multi-Tenancy Implementation
+
 **Goal**: Support multiple organizations with data isolation
 
 **Features**:
+
 - Tenant creation and management
 - Tenant member invitations
 - Tenant roles (OWNER, ADMIN, MEMBER, GUEST)
@@ -543,11 +622,13 @@ This document provides a comprehensive roadmap for extending the current user au
 - Tenant switching for users in multiple tenants
 
 **Database**:
+
 - `tenants` table (id, name, slug, status, subscriptionPlan, createdAt, updatedAt)
 - `tenant_members` table (tenantId, userId, role, invitedBy, joinedAt)
 - Add `tenantId` column to relevant tables
 
 **API Endpoints**:
+
 - `POST /api/tenants` - create tenant
 - `GET /api/tenants/{tenantId}` - get tenant
 - `PATCH /api/tenants/{tenantId}` - update tenant
@@ -566,36 +647,37 @@ This document provides a comprehensive roadmap for extending the current user au
 
 ## Feature Priority Matrix
 
-| Feature | Priority | Complexity | Effort (days) | Business Value |
-|---------|----------|------------|---------------|----------------|
-| **Email Service Foundation** | HIGH | Low | 2-3 | High - Enables all email features |
-| **Email Verification** | HIGH | Medium | 3-4 | High - Security, trust |
-| **Password Reset** | HIGH | Medium | 2-3 | High - User experience |
-| **Passwordless Login (OTP)** | HIGH | Medium | 2-3 | High - Modern UX, convenience |
-| **Rate Limiting** | HIGH | Low | 2-3 | High - Security, abuse prevention |
-| **Account Lockout** | HIGH | Low | 2 | Medium - Security |
-| **Session Management** | HIGH | Medium | 3-4 | High - Security, transparency |
-| **Security Alerts** | HIGH | Medium | 2-3 | High - Security awareness |
-| **OAuth2 Social Login** | HIGH | High | 5-7 | High - Conversion, UX |
-| **Enhanced RBAC** | MEDIUM-HIGH | High | 5-7 | High - Enterprise readiness |
-| **API Key Management** | MEDIUM-HIGH | Medium | 3-4 | High - Developer experience |
-| **Service Accounts** | MEDIUM-HIGH | Low | 2 | Medium - Automation |
-| **Audit Logging** | MEDIUM | Medium | 4-6 | High - Compliance, debugging |
-| **Kafka Event Bus** | MEDIUM | High | 5-7 | Medium - Scalability, decoupling |
-| **Notification Service** | MEDIUM | Medium | 3-5 | Medium - User engagement |
-| **User Preferences** | MEDIUM | Low | 2-3 | Medium - Personalization |
-| **Two-Factor Auth (2FA)** | MEDIUM | Medium | 4-5 | Medium - Security |
-| **IP Whitelisting** | MEDIUM | Low | 2-3 | Medium - Enterprise security |
-| **Webhooks** | MEDIUM | Medium | 4-5 | Medium - Integration, extensibility |
-| **Soft Delete & Retention** | LOW-MEDIUM | Low | 2-3 | Medium - Compliance (GDPR) |
-| **Multi-Tenancy** | LOW | Very High | 7-10 | High - SaaS foundation (long-term) |
-| **ABAC (Optional)** | LOW | Very High | 5-7 | Low - Complex use cases |
+| Feature                      | Priority    | Complexity | Effort (days) | Business Value                      |
+|------------------------------|-------------|------------|---------------|-------------------------------------|
+| **Email Service Foundation** | HIGH        | Low        | 2-3           | High - Enables all email features   |
+| **Email Verification**       | HIGH        | Medium     | 3-4           | High - Security, trust              |
+| **Password Reset**           | HIGH        | Medium     | 2-3           | High - User experience              |
+| **Passwordless Login (OTP)** | HIGH        | Medium     | 2-3           | High - Modern UX, convenience       |
+| **Rate Limiting**            | HIGH        | Low        | 2-3           | High - Security, abuse prevention   |
+| **Account Lockout**          | HIGH        | Low        | 2             | Medium - Security                   |
+| **Session Management**       | HIGH        | Medium     | 3-4           | High - Security, transparency       |
+| **Security Alerts**          | HIGH        | Medium     | 2-3           | High - Security awareness           |
+| **OAuth2 Social Login**      | HIGH        | High       | 5-7           | High - Conversion, UX               |
+| **Enhanced RBAC**            | MEDIUM-HIGH | High       | 5-7           | High - Enterprise readiness         |
+| **API Key Management**       | MEDIUM-HIGH | Medium     | 3-4           | High - Developer experience         |
+| **Service Accounts**         | MEDIUM-HIGH | Low        | 2             | Medium - Automation                 |
+| **Audit Logging**            | MEDIUM      | Medium     | 4-6           | High - Compliance, debugging        |
+| **Kafka Event Bus**          | MEDIUM      | High       | 5-7           | Medium - Scalability, decoupling    |
+| **Notification Service**     | MEDIUM      | Medium     | 3-5           | Medium - User engagement            |
+| **User Preferences**         | MEDIUM      | Low        | 2-3           | Medium - Personalization            |
+| **Two-Factor Auth (2FA)**    | MEDIUM      | Medium     | 4-5           | Medium - Security                   |
+| **IP Whitelisting**          | MEDIUM      | Low        | 2-3           | Medium - Enterprise security        |
+| **Webhooks**                 | MEDIUM      | Medium     | 4-5           | Medium - Integration, extensibility |
+| **Soft Delete & Retention**  | LOW-MEDIUM  | Low        | 2-3           | Medium - Compliance (GDPR)          |
+| **Multi-Tenancy**            | LOW         | Very High  | 7-10          | High - SaaS foundation (long-term)  |
+| **ABAC (Optional)**          | LOW         | Very High  | 5-7           | Low - Complex use cases             |
 
 ---
 
 ## Recommended Implementation Sequence
 
 ### Sprint 1: Email Foundation & Passwordless (8-12 days)
+
 1. Email Service Foundation (2-3 days)
 2. Email Verification (3-4 days)
 3. Password Reset (2-3 days)
@@ -606,6 +688,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 2: Security Hardening (4-5 days)
+
 1. Rate Limiting (2-3 days)
 2. Account Lockout (2 days)
 
@@ -614,6 +697,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 3: Session Management (5-7 days)
+
 1. Session Management & Device Tracking (3-4 days)
 2. Security Alerts (2-3 days)
 
@@ -622,6 +706,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 4: Social Authentication (5-7 days)
+
 1. OAuth2 Social Login - Google, GitHub, Facebook (5-7 days)
 
 **Outcome**: Modern social login experience
@@ -629,6 +714,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 5: Advanced Authorization (5-7 days)
+
 1. Enhanced RBAC with Permissions (5-7 days)
 
 **Outcome**: Enterprise-grade permission system
@@ -636,6 +722,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 6: API Access (5-6 days)
+
 1. API Key Management (3-4 days)
 2. Service Accounts (2 days)
 
@@ -644,6 +731,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 7: Observability (8-13 days)
+
 1. Audit Logging (4-6 days)
 2. Kafka Event Bus (5-7 days)
 
@@ -652,6 +740,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 8: Notifications & Preferences (5-8 days)
+
 1. Notification Service (3-5 days)
 2. User Preferences (2-3 days)
 
@@ -660,6 +749,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 9: Enhanced Security (6-8 days)
+
 1. Two-Factor Authentication (4-5 days)
 2. IP Whitelisting (2-3 days)
 
@@ -668,6 +758,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 10: Integration & Compliance (6-8 days)
+
 1. Webhooks (4-5 days)
 2. Soft Delete & Data Retention (2-3 days)
 
@@ -676,6 +767,7 @@ This document provides a comprehensive roadmap for extending the current user au
 ---
 
 ### Sprint 11: Multi-Tenancy (Optional - 7-10 days)
+
 1. Multi-Tenancy Implementation (7-10 days)
 
 **Outcome**: Full multi-tenant SaaS capabilities
@@ -780,6 +872,7 @@ networks:
 ## Success Metrics
 
 ### Technical Metrics
+
 - API response time: p95 < 200ms
 - Email delivery rate: > 99%
 - Event publishing latency: < 100ms
@@ -787,6 +880,7 @@ networks:
 - Session management overhead: < 10ms per request
 
 ### Business Metrics
+
 - Email verification completion rate: > 70%
 - Social login adoption rate: > 40%
 - Passwordless login usage: > 20%
@@ -794,6 +888,7 @@ networks:
 - API key usage vs traditional auth: track ratio
 
 ### Security Metrics
+
 - Failed login attempts blocked: track count
 - Account lockouts: monitor frequency
 - Suspicious logins detected: track and alert
@@ -804,6 +899,7 @@ networks:
 ## Migration Strategy
 
 ### For Existing Deployments
+
 1. **Feature Flags**: Use Spring Boot profiles or feature flag library to enable features gradually
 2. **Backward Compatibility**: All schema changes nullable initially
 3. **Data Migration**: Provide scripts for existing user data
@@ -815,6 +911,7 @@ networks:
 ## Testing Strategy
 
 ### Test Coverage
+
 - Unit tests: 80%+ coverage for services
 - Integration tests: Critical authentication flows
 - Security tests: OWASP Top 10, penetration testing
@@ -822,6 +919,7 @@ networks:
 - E2E tests: Complete user journeys (registration → verification → login)
 
 ### Test Environments
+
 - Local: Docker Compose with all services
 - CI/CD: TestContainers (PostgreSQL, Redis, Kafka)
 - Staging: Full production replica
@@ -832,26 +930,28 @@ networks:
 ## Risk Mitigation
 
 ### High-Risk Areas
+
 1. **OAuth2 Account Linking**: Risk of account takeover
-   - Mitigation: Require email verification, additional confirmation for account linking
+    - Mitigation: Require email verification, additional confirmation for account linking
 
 2. **Kafka Message Loss**: Events lost during failures
-   - Mitigation: Transactional outbox pattern, at-least-once delivery, idempotent consumers
+    - Mitigation: Transactional outbox pattern, at-least-once delivery, idempotent consumers
 
 3. **Rate Limiting Failures**: Redis unavailable
-   - Mitigation: Fail-open with logging, circuit breaker pattern
+    - Mitigation: Fail-open with logging, circuit breaker pattern
 
 4. **Performance Degradation**: Audit logging overhead
-   - Mitigation: Async logging, database partitioning, archival strategy
+    - Mitigation: Async logging, database partitioning, archival strategy
 
 5. **Session Hijacking**: Session tokens compromised
-   - Mitigation: Short-lived tokens, IP validation, device fingerprinting
+    - Mitigation: Short-lived tokens, IP validation, device fingerprinting
 
 ---
 
 ## Documentation Requirements
 
 ### For Each Feature
+
 1. Architecture decision record (ADR)
 2. API documentation (OpenAPI/Swagger)
 3. Database schema diagrams
@@ -859,6 +959,7 @@ networks:
 5. Migration guide
 
 ### Update CLAUDE.md
+
 - New build commands
 - New environment variables
 - Architecture changes
@@ -879,3 +980,7 @@ networks:
 **Document Version**: 2.0
 **Last Updated**: 2025-11-28
 **Status**: Ready for Implementation
+
+## Other TODO
+
+- Revisit spring-grpc when it's 1.0, then add grpc tests

From b49c3f2649ef08fc1e98003a9fb2e93a7d15747f Mon Sep 17 00:00:00 2001
From: Daniel <daniel.guo@vivalabs.com.au>
Date: Mon, 1 Dec 2025 14:32:56 +1100
Subject: [PATCH 2/3] Fix typo in ci config

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dcf86d0..8e6e2df 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -29,7 +29,7 @@ jobs:
           - 5432:5432
         options: >-
           --health-cmd pg_isready
-          --heath-interval 10s
+          --health-interval 10s
           --health-timeout 5s
           --health-retries 3
     steps:

From d158df5ec38ddba9f05febfe70e94dd6d08757a1 Mon Sep 17 00:00:00 2001
From: Daniel <daniel.guo@vivalabs.com.au>
Date: Mon, 1 Dec 2025 14:46:18 +1100
Subject: [PATCH 3/3] Fix failed test due to timestamp precision

---
 auto/test                                                 | 5 -----
 .../java/org/nkcoder/repository/UserRepositoryTest.java   | 8 +++++++-
 2 files changed, 7 insertions(+), 6 deletions(-)
 delete mode 100755 auto/test

diff --git a/auto/test b/auto/test
deleted file mode 100755
index 5eee014..0000000
--- a/auto/test
+++ /dev/null
@@ -1,5 +0,0 @@
-#!/usr/bin/env sh
-
-export SPRING_PROFILES_ACTIVE=test
-./gradlew --no-daemon --quiet spotlessApply
-./gradlew --no-daemon clean build test
\ No newline at end of file
diff --git a/src/test/java/org/nkcoder/repository/UserRepositoryTest.java b/src/test/java/org/nkcoder/repository/UserRepositoryTest.java
index 67c83ad..3ddd3e1 100644
--- a/src/test/java/org/nkcoder/repository/UserRepositoryTest.java
+++ b/src/test/java/org/nkcoder/repository/UserRepositoryTest.java
@@ -3,6 +3,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.time.LocalDateTime;
+import java.time.temporal.ChronoUnit;
 import java.util.Optional;
 import java.util.UUID;
 import org.junit.jupiter.api.BeforeEach;
@@ -135,7 +136,12 @@ class UpdateLastLoginAt {
     @Test
     @DisplayName("updates last login timestamp")
     void updatesTimestamp() {
-      LocalDateTime loginTime = LocalDateTime.now();
+
+      // There is a timestamp precision issue in Java/PostgreSQL tests
+      // PostgreSQL's timestamp type stores microsecond precision, but Java's LocalDateTime.now()
+      // has nanosecond precision. The nanoseconds get truncated when stored, causing isEqualTo()
+      // to fail.
+      LocalDateTime loginTime = LocalDateTime.now().truncatedTo(ChronoUnit.MICROS);
 
       int updated = userRepository.updateLastLoginAt(testUser.getId(), loginTime);