🛡️ FraudShield

What FraudShield Is

The Problem It Solves

When you swipe a card or tap "pay," a bank has a fraction of a second to decide: is this really you, or is this a stolen card? If they are too slow, fraud goes through and the bank loses money. If they are too aggressive, they block real customers and everyone gets annoyed. Doing this well, at the scale of thousands of payments per second, is one of the hardest problems in financial software.

FraudShield is a production-grade real-time fraud detection system. It is a backend platform that receives payment events, scores each one against a set of fraud rules in milliseconds, and raises an alert the moment something looks suspicious.

What It Actually Does — Step by Step

Imagine a customer named Priya. Here is what FraudShield does the instant a payment on her account comes in:

1. 1
   Receives the payment. A merchant's app sends a transaction — amount, currency, merchant, location — to FraudShield's secure API. The request must carry a valid login token, or it is rejected on the spot.
2. 2
   Checks for fraud patterns. Is Priya suddenly making 6 payments in a minute? Is this payment 50× bigger than her usual spend? Is it coming from a country she has never shopped from before? Each suspicious signal adds to a "fraud score."
3. 3
   Makes a decision. If the total score crosses a threshold, the payment is flagged. If not, it passes silently. This whole decision takes under a tenth of a second.
4. 4
   Alerts the user. If flagged, Priya instantly gets a notification: "We noticed an unusual payment on your account." A human fraud analyst can also review it and override the decision.
5. 5
   Records everything. Every payment, every decision, every analyst action is logged — so there is a complete, tamper-evident audit trail.

Who Uses It

Three kinds of people interact with FraudShield: end users (customers like Priya who receive alerts), payment clients (merchant apps that submit transactions), and fraud analysts (staff who review flagged payments and tune the detection rules).

Architecture Overview

FraudShield is built with production patterns and best practices: event-driven architecture, circuit breakers, stateless JWT authentication, audit logging, and service discovery. Every component is designed to scale horizontally and handle real-time payment fraud detection at enterprise scale.

At a Glance

Here is the same thing in one technical sentence, for the quick summary: FraudShield is a production-grade, event-driven fraud detection and alerting platform that ingests payment transaction events, runs them through a configurable multi-rule scoring engine, flags suspicious activity, and notifies users — all in near real-time.

The Big Picture

Six Spring Boot microservices communicate through Apache Kafka and REST. The Transaction Service is the only public entry point. Everything else is internal. Redis underpins two cross-cutting concerns: sliding-window fraud counters and JWT token revocation.

High-Level Design

The formal architectural decisions and trade-offs — the document an architect produces before deployment, following enterprise patterns for fraud detection systems.

3.1 Context & Scope

FraudShield sits between payment processors and end-users. It does not process payments — it observes them and reacts.

3.2 Architectural Style

Event-Driven Microservices with CQRS. Each service owns its data, communicates asynchronously via Kafka, scales independently.

3.3 Container View (C4-L2)

3.4 Data Flows

3.5 Non-Functional Requirements

3.6 Risks & Assumptions

Tech Stack & Why

Every technology was chosen for production use. These are the same tools running in real fraud detection systems at scale.

Service Catalog

Transaction Service

The sole public-facing entry point. Receives raw payment events, validates them, persists to PostgreSQL, and publishes to raw-transactions. The JWT filter rejects unauthenticated calls before the controller. It does not evaluate fraud — its single responsibility is reliable, at-least-once delivery to the message bus.

Port

8081

Base Path

/api/transactions

Auth

Bearer JWT (ROLE_USER+)

Publishes

raw-transactions

Depends on

Auth Svc, Kafka, PostgreSQL

Scaling

3 replicas, CPU HPA

Rules Engine Service

The analytical core. Consumes raw-transactions, evaluates each against active rules from PostgreSQL, computes a composite score, persists the verdict, and publishes to fraud-verdicts. Rules refresh every 60 seconds — no restart to change thresholds. The velocity check uses a Redis Sorted Set as a sliding-window counter.

Port

8082 (internal)

Consumes

raw-transactions

Publishes

fraud-verdicts

Idempotency

Redis processed:{txId} 24h TTL

Scaling

HPA on Kafka lag > 1000

Velocity Check — Redis Sliding Window

ZADD velocity:{userId} {epochMs} {txId}
ZREMRANGEBYSCORE velocity:{userId} 0 {epochMs - 60000}
count = ZCARD velocity:{userId}
EXPIRE velocity:{userId} 60
if (count > 5) score += 40;

Alert Service

Bridges the fraud pipeline and the end user. Consumes fraud-verdicts, persists an alert for every FLAGGED verdict, and publishes to alert-notifications. Users can fetch only their own alerts — the query is scoped to the JWT subject.

Port

8083

Consumes

fraud-verdicts

Publishes

alert-notifications

States

PENDING → SENT → ACKNOWLEDGED

Resilience

Circuit breaker on notify publish

Admin API

The control plane for analysts. View flagged transactions with dynamic filtering, override verdicts, manage rules without redeployment, inspect the audit log. Every write is captured as an immutable audit event. Uses JPA Specifications for dynamic query filtering.

Port

8084

Auth

ROLE_ANALYST / ROLE_ADMIN

Owns

fraud_rules, audit_logs

Rate Limit

100 req / 10s per user

Auth Service

The identity backbone — the only service that issues tokens. Manages users, roles, password hashing, JWT generation, refresh rotation, and logout via Redis blacklisting. Other services validate JWTs locally without calling back; only the blacklist check hits shared storage.

Port

8085

Access Token TTL

15 minutes

Refresh Token TTL

7 days (hashed in DB)

Password hashing

BCrypt cost 12

Token signing

HMAC-SHA256, 256-bit key

Roles

USER, ANALYST, ADMIN, SUPER_ADMIN

Notification Worker

Consumes alert-notifications and dispatches email/SMS through configured providers (SendGrid for email, Twilio for SMS in production). Idempotent: a notification ID is stored after successful dispatch. After 3 failed retries, messages go to alert-notifications.DLT.

Port

8086 (internal)

Consumes

alert-notifications

Dead Letter

alert-notifications.DLT

Retry

3 attempts, backoff 1s/2s/4s

Prod

SendGrid (email), Twilio (SMS)

🔧 Backend — Code Deep Dive

Shape

Single Spring Boot app (modular monolith)

Base package

com.fraudshield

Controllers

5 (Auth, Transaction, Admin, Rule, Config)

Service beans

7 (Auth, Jwt, CustomUserDetails, Transaction, RulesEngine, Rule, Audit)

Persistence

Spring Data JPA, H2 (dev) / PostgreSQL (prod)

Fraud scoring

Deterministic weighted rules (no ML)

Layered Architecture

Requests flow through a classic Spring layering: the JwtAuthenticationFilter authenticates, a controller maps the HTTP endpoint, a service holds the business logic, and a repository talks to the database. DTOs cross the controller boundary; entities stay inside the service/repository layers.

HTTP ─▶ JwtAuthenticationFilter ─▶ Controller ─▶ Service ─▶ Repository ─▶ DB
                                        │             │
                                     (DTOs)       (entities)

Controllers — the HTTP surface

Service Beans — the business logic

RulesEngineService the analytical core

Scores a transaction against the enabled fraud rules and decides a verdict. This is where "is this fraud?" is answered.

• score(Transaction) — loads enabled rules via findByEnabledTrue(), sums the weight of every rule that fires(), and returns a ScoreResult. Score ≥ 50 → FLAGGED (status PENDING); otherwise PASSED.
• fires(FraudRule, Transaction) — the per-rule evaluation logic: amount fires when amount > 2000; nightowl fires when amount > 1000 and the UTC hour is 2–5; velocity/geo/duplicate fire on a deterministic hash bucket of id + merchantId.
• bucket(Transaction, salt) — produces a stable 0–99 bucket so transaction scoring is deterministic and reproducible across restarts.
• ScoreResult (record) — carries score, verdict, status, and the list of fired rule IDs.

TransactionService

• create(request, userId, ip) — builds a Transaction (generates a tx- id, derives country from lat/long), calls RulesEngineService.score(), persists it, writes an audit entry, returns a CreateTransactionResponse.
• list(q, verdict, status) — builds a JPA Specification from the filters, returns newest-first; filters data rows appropriately based on access level.
• get(id) — fetches one transaction or throws NotFoundException.
• applyVerdict(id, decision, actor, ip) — analyst override: FALSE_POSITIVE → status OVERRIDDEN; CONFIRMED_FRAUD → flags confirmedFraud; logs the action.
• primeSequence() — initializes the transaction id counter, ensuring no collisions across restarts.
• helpers: buildSpec(), ruleIndex(), toResponse(), deriveCountry().

AuthService & JwtService authentication

• AuthService.login() — verifies the BCrypt password, audits, issues tokens. refresh() — one-time-use rotation: marks the old refresh token used, issues a new pair. logout() — marks all active refresh tokens used. me() — returns the current UserDto. issueTokens() stores a SHA-256 hash of the refresh token (never the raw value).
• JwtService.generateAccessToken() — signs an HS256 JWT with subject, role, name claims (15-min TTL). generateRawRefreshToken() — 256-bit random, URL-safe. parseAndValidate() — verifies signature + expiry. sha256Hex() — hashes refresh tokens for storage.
• CustomUserDetailsService.loadUserByUsername(email) — Spring Security hook; loads the user and maps their role to a granted authority.

RuleService

• list() — returns all rules sorted by weight (highest first).
• update(id, request, actor, ip) — toggles enabled and/or changes weight, builds a human-readable audit message describing exactly what changed, and persists it.

AuditService cross-cutting

• log(actor, action, ip, icon) — appends an immutable AuditLog row (called by nearly every write path).
• recent() — returns the audit trail newest-first, filtered by access level.
• resolveClientIp(request) — prefers the first X-Forwarded-For hop, else the remote address.

Request lifecycle — a POST /api/transactions

1. 1
   JwtAuthenticationFilter validates the Bearer token and sets the security context.
2. 2
   TransactionController.create() reads the JWT subject as the user id and delegates to the service.
3. 3
   TransactionService.create() builds the entity and calls RulesEngineService.score().
4. 4
   RulesEngineService sums enabled-rule weights → score ≥ 50 is FLAGGED.
5. 5
   The verdict is persisted, AuditService.log() records it, and a 202 Accepted returns.

🧭 Eureka Service Discovery

The backend registers itself with a Netflix Eureka server at startup so that other services can find it by logical name instead of a hardcoded host and port. Eureka is the service registry — the phone book of the system: every instance checks in, sends a periodic heartbeat, and is removed automatically if it stops responding.

Role

Eureka client (registers & discovers)

Starter

spring-cloud-starter-netflix-eureka-client

Spring Cloud

2025.1.4 (Northfields)

Registry server

http://localhost:8761/eureka/

Registers as

fraudshield-backend:8080

Toggle

EUREKA_ENABLED (default true)

Configuration (application.yml)

Discovery is on by default and can be disabled with a single environment variable — handy for running the backend standalone in local dev or tests.

spring:
  application:
    name: fraudshield-backend     # the name peers look up in Eureka
  cloud:
    discovery:
      enabled: ${EUREKA_ENABLED:true}

eureka:
  client:
    enabled: ${EUREKA_ENABLED:true}
    register-with-eureka: true     # publish this instance to the registry
    fetch-registry: true           # pull the list of other services
    service-url:
      defaultZone: ${EUREKA_URL:http://localhost:8761/eureka/}
  instance:
    prefer-ip-address: true        # register by IP, not hostname
    instance-id: ${spring.application.name}:${server.port}

Environment overrides

How registration works

1. 1
   Start Eureka first. The registry server must be up on :8761 before the backend boots (or the client will retry until it is).
2. 2
   Register. On startup the backend POSTs its instance info (fraudshield-backend, IP, port 8080) to the Eureka server.
3. 3
   Heartbeat. The client renews its lease every ~30s. Miss enough heartbeats and Eureka evicts the instance.
4. 4
   Discover. With fetch-registry: true, the backend caches the registry and can resolve other services by their logical name.
5. 5
   Shut down. On graceful stop the client de-registers so no caller is routed to a dead instance.

📮 Postman — Modify the Collection

The repo ships an importable collection at Postman/FraudShield.postman_collection.json. It is a v2.1.0 collection that already wires up authentication, variables, and token auto-capture — so extending it is mostly a matter of knowing where each piece lives. This section is a guide to changing and growing the collection, not just running it.

How this collection is wired

1. Add a new request to a folder

Append a request object inside the target folder's item[] array. The minimum shape:

{
  "name": "Create Transaction — custom",
  "request": {
    "method": "POST",
    "header": [{ "key": "Content-Type", "value": "application/json" }],
    "body": {
      "mode": "raw",
      "raw": "{\n  \"amount\": 999.00,\n  \"currency\": \"EUR\",\n  \"merchantId\": \"MERCH-TEST-01\"\n}"
    },
    "url": {
      "raw": "{{baseUrl}}/api/transactions",
      "host": ["{{baseUrl}}"],
      "path": ["api", "transactions"]
    }
  }
}

2. Change the body or query params

The request body lives in request.body.raw as an escaped JSON string (note the \n and \"). Edit it in Postman's body editor to avoid escaping by hand. For query params, add a query array and mirror it in url.raw:

"url": {
  "raw": "{{baseUrl}}/api/transactions?verdict=FLAGGED&status=PENDING",
  "host": ["{{baseUrl}}"],
  "path": ["api", "transactions"],
  "query": [
    { "key": "verdict", "value": "FLAGGED" },
    { "key": "status",  "value": "PENDING" }
  ]
}

3. Add or reuse a variable

Add a new entry to the top-level variable[] array, then reference it anywhere as {{yourVar}}:

{ "key": "merchantId", "value": "MERCH-TEST-01", "type": "string" }

Read it in a script with pm.collectionVariables.get('merchantId') and write it with pm.collectionVariables.set('merchantId', value). Prefer collection variables for values shared by many requests; use an environment when the same collection must run against dev / staging / prod.

4. Capture a value from a response (chaining)

Add a test script to the request's event[]. This is exactly how the login request feeds the token into every later call:

"event": [{
  "listen": "test",
  "script": {
    "type": "text/javascript",
    "exec": [
      "const json = pm.response.json();",
      "pm.test('status 200', () => pm.response.to.have.status(200));",
      "pm.collectionVariables.set('accessToken', json.accessToken);",
      "pm.collectionVariables.set('refreshToken', json.refreshToken);"
    ]
  }
}]

Use the same pattern to grab a new id — e.g. pm.collectionVariables.set('lastTxId', json.transactionId) — then reference {{lastTxId}} in the next request's URL.

5. Override auth for one request

Every request inherits the collection's Bearer auth. For a public endpoint (login, refresh, mock-status) opt out per request so no stale token is sent:

"request": {
  "auth": { "type": "noauth" },
  "method": "POST",
  "...": "..."
}

6. Switch user / role

Role-gated endpoints (rule writes need ADMIN) depend on which login you ran last, because each login overwrites accessToken. To test a 403, run Login (HK Analyst), then call a rule PUT. To duplicate a login for another account, copy the login request and change only the email/password in the body.

7. Add the mock-mode header

To force seeded data on a list request, add the optional override header; omit it to use the server config:

"header": [
  { "key": "X-Mock-Response", "value": "true" }
]

Re-import & verify

1. 1
   Edit the JSON (or edit in Postman and Export → overwrite the file to keep the repo in sync).
2. 2
   In Postman, Import the file again — choose Replace so you don't end up with duplicates.
3. 3
   Run Auth → 1. Login (HK Admin) first to refresh {{accessToken}}, then your new request.
4. 4
   Watch the created data appear live in the UI at http://localhost:5173.

End-to-End Request Flow

Traces a single flagged transaction from the client's HTTP call to the user's email alert. This is what an interviewer expects when they ask "walk me through your system."

1. 1
   Client Authentication: POST with Bearer JWT. Filter validates signature, expiry, Redis blacklist. 401 on failure.
2. 2
   Payload Validation: Bean Validation checks fields. 400 with field errors on failure.
3. 3
   Persist + Publish: Saved to PostgreSQL, published to Kafka. 202 returned after Kafka ACK.
4. 4
   Rules Evaluation: Redis sliding window finds 6 txns/60s. Score = 70 → FLAGGED.
5. 5
   Alert Creation: Alert Service creates alert, publishes to alert-notifications.
6. 6
   User Notification: Worker checks idempotency key, sends mock email.

Configuration Model

Follows 12-Factor App principles: every environment-specific value is externalized. No secrets in code — only Spring profiles and environment variables.

Resilience & Fault Tolerance

FraudShield treats failures as normal. Every integration point is wrapped with a Resilience4j pattern. The goal is graceful degradation.

Security

Five layers. Bypassing one alone is not enough — defence in depth.

Handling an Unauthenticated Request

1. 1
   Request arrives. JwtAuthenticationFilter runs before the controller.
2. 2
   Filter checks for Bearer token. Absent → SecurityContext anonymous.
3. 3
   Token validation: signature, expiry, Redis blacklist. Any failure → anonymous.
4. 4
   Spring Security evaluates the route. Public routes pass; protected require auth.
5. 5
   401 Unauthorized returned as structured JSON — no stack trace. Source IP logged.

Auth & Token Flow (Three Layers)

Token Refresh Flow

POST /api/auth/refresh { "refreshToken": "UUID" }
Server:
  1. Hash incoming token (SHA-256)
  2. Look up hash in PostgreSQL
  3. Check: not expired, not already used
  4. DELETE old refresh token (rotation — single use)
  5. Issue new JWT (15 min) + new refresh token (7 days)
  6. Invalid → 401, client must re-login

Observability

The three pillars — logs, metrics, traces — are all implemented. In dev everything goes to the console as structured JSON.

Failure Scenarios

UI Overview — The Analyst Dashboard

So far this guide has covered the backend — the services, Kafka pipeline, and security that decide whether a payment is fraud. This part covers the frontend: the screen a human fraud analyst actually looks at. The backend makes the decision; the frontend lets a person review and act on it.

The dashboard lives in the UI/ folder and runs completely on mock data — no backend connection needed. It is the visual counterpart to the Admin API service documented earlier.

Frontend Stack & Why

Folder Structure

UI/
  index.html            Vite entry, loads fonts + favicon
  vite.config.js        dev server on port 5173
  package.json          react, react-dom, react-router-dom
  src/
    main.jsx            React root + Router
    App.jsx             routes + auth guard
    auth.jsx            mock login, session in localStorage
    mockData.js         users, transactions, rules, audit log
    styles.css          design system (brand tokens, dark mode)
    components/
      Layout.jsx        sidebar + topbar shell
    pages/
      Login.jsx         sign-in screen
      Dashboard.jsx     KPI cards + recent flags
      Transactions.jsx  table + detail drawer + override
      Rules.jsx         rule toggles (RBAC)
      Audit.jsx         action timeline

Login Screen

The entry point. It validates credentials against the mock user list, stores a session in localStorage, and redirects to the dashboard. Clicking a demo account auto-fills the form — handy for a quick demo.

How It Works (example)

When you type HKanalyst@fraudshield.io / Analyst@123 and hit Sign In, the login() function in auth.jsx searches the mock user list. On a match it saves {name, email, role} to React state and localStorage, then React Router redirects to /. On a mismatch it shows a red "Invalid email or password" banner. In the real system this exact step would instead call POST /api/auth/login and store the returned JWT.

Dashboard

The landing page after login. Four KPI stat cards give an at-a-glance health check, followed by a table of the most recent flagged transactions.

Example: the "Flagged" card

The flagged count is computed live from the data: TRANSACTIONS.filter(t => t.verdict === 'FLAGGED'). The card also shows the fraud rate as a percentage. Because it is derived in React, if a new flagged transaction arrived (in the real system, via a Kafka-driven update), the number would re-render automatically.

Transactions + Detail Drawer

The core working screen. A searchable, filterable table of all transactions. Clicking any row slides open a detail drawer from the right showing the full transaction, which fraud rules fired and their scores, and — for analysts — buttons to override the verdict.

Example: overriding a verdict

Suppose analyst Priya opens tx-10024. The drawer shows it scored 70 because the Velocity Check (+40) and Amount Anomaly (+30) rules both fired. Priya recognises it as a legitimate large purchase and clicks ✓ Mark False Positive. The row's status instantly updates to OVERRIDDEN, and in the real system this would fire PUT /api/admin/verdicts/tx-10024 and write an entry to the audit log. The override buttons only appear for analysts and admins — a plain user never sees them (RBAC).

Fraud Rules

Lists every detection rule with its score weight and an on/off toggle. This screen demonstrates role-based access control in the UI: only admins can flip the toggles. Analysts see the rules but the switches are locked, with a notice explaining the restriction — the frontend mirror of a backend 403.

Example: the RBAC difference

Log in as HKadmin@fraudshield.io and the toggles are live — click one and the rule flips on/off instantly. Log in as HKanalyst@fraudshield.io and the same toggles are greyed out with a banner: "Only Admins can enable or disable rules." This is the same authorization boundary the backend enforces, surfaced in the UI so analysts aren't shown controls they can't use.

Audit Log

A chronological timeline of every action analysts and admins have taken — verdict overrides, rule changes, logins, report exports. Each entry records who did it, from which IP, and when. In a real system this is critical for compliance and for investigating disputes.

Component Reference

Every reusable piece of the UI, what it does, and where it lives. This is the "parts list" an engineer would read before changing the frontend.

Shared UI Patterns (CSS classes)

Build & Deployment

Prerequisites

• Java 21+ (java -version)
• Maven 3.9+ (mvn -version)
• Docker Desktop (for full-stack mode)

Option 1 — Mock Mode (Zero Infrastructure)

cd auth-service
mvn spring-boot:run -Dspring-boot.run.profiles=default
# Swagger UI: http://localhost:8085/swagger-ui.html
# H2 Console: http://localhost:8085/h2-console (jdbc:h2:mem:fraudshielddb, sa, blank)

Option 2 — Full Stack (Docker Compose)

docker-compose up --build
# All 9 containers: Kafka, Zookeeper, Redis, PostgreSQL + 6 services
# Auth: http://localhost:8085/swagger-ui.html

Pre-seeded Accounts (Mock Data)

Quick API Test

# 1. Login
curl -X POST http://localhost:8085/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"HKuser@fraudshield.io","password":"User@123"}'

# 2. Submit a transaction (use token from step 1)
curl -X POST http://localhost:8081/api/transactions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":9999.99,"currency":"USD","merchantId":"MERCH-001"}'

# 3. Check alerts
curl http://localhost:8083/api/alerts -H "Authorization: Bearer $TOKEN"

🚀 Setup Guide — Clone & Run It Yourself

What You Need

Step 1 — Clone It

git clone https://github.com/hanyak10/FraudShield.git
cd FraudShield

Real layout you'll see on disk:

fraudshield/
├── backend/                 Spring Boot 3.2 monolith (Java 17, H2, JWT, Eureka client)
├── UI/                      React 18 + Vite analyst dashboard
├── Postman/                 Importable Postman collection (auto-manages tokens)
├── api-request-bodies.json  Postman-ready request-body reference
└── README.md                You are here

Step 2 — Run the Backend

cd backend
mvn spring-boot:run
# Fresh, seeded H2 database every restart — no setup needed.
# Swagger UI : http://localhost:8080/swagger-ui.html
# H2 console : http://localhost:8080/h2-console (jdbc:h2:mem:fraudshield, user sa, blank password)
# Health     : http://localhost:8080/actuator/health

Running standalone without a Eureka registry handy? Skip discovery so it doesn't retry connections forever:

# PowerShell
$env:EUREKA_ENABLED="false"; mvn spring-boot:run
# bash
EUREKA_ENABLED=false mvn spring-boot:run

Step 3 — Run the UI

cd UI
npm install
npm run dev
# Opens http://localhost:5173 — backend already allows CORS for this origin.

Step 4 — Eureka Server (Optional)

The backend is a Eureka client; it expects a registry at http://localhost:8761/eureka/. Start any standard Eureka server on :8761 first if you want to see live service-discovery registration (the same check this guide's v1.1.0 upgrade verified) — or just set EUREKA_ENABLED=false and skip it entirely.

Step 5 — Log In

Prefer Postman?

Import Postman/FraudShield.postman_collection.json and start the backend. Running Auth → 1. Login (HK Admin) auto-saves accessToken/refreshToken as collection variables, and every other request attaches Authorization: Bearer {{accessToken}} for you — no copy-pasting tokens by hand.

Mock vs. Real Data

The backend serves either seeded demo rows (mock) or only what you create at runtime (real). Force seeded data on any list call with a header:

curl -H "X-Mock-Response: true" http://localhost:8080/api/transactions

Glossary

FAQ

Why JWT and not server-side sessions?

Sessions require a shared store and a DB lookup per request. JWT is stateless — the server only needs the secret key. You can scale to 100 instances with no shared auth state. The only shared state we add back is the Redis blacklist, a conscious tradeoff for logout support.

Why Kafka over RabbitMQ or REST calls?

Retention and replay. Kafka keeps messages 7 days regardless of consumption. If Rules Engine is down for an hour, every transaction is waiting when it recovers — in order. RabbitMQ deletes on ACK. REST creates synchronous coupling.

How does the Rules Engine scale without double-processing?

Kafka consumer groups assign one partition to exactly one consumer, so instances partition the work without overlap. For rare redeliveries, the Redis idempotency key ensures double-processing is silently skipped.

What happens when an unauthenticated user hits a protected endpoint?

The JWT filter runs before any controller. With no valid token the SecurityContext stays anonymous and Spring Security returns 401 with structured JSON — no stack trace. The request is logged with source IP.

Why BCrypt cost factor 12?

Cost is exponential. Cost 10 ≈ 75ms (too fast, GPU-brute-forceable). Cost 14 ≈ 1000ms (too slow under load). Cost 12 ≈ 250ms — the sweet spot.

Why hash refresh tokens before storing?

If the DB is breached, plaintext refresh tokens let an attacker issue JWT pairs for every user. Hashing (SHA-256) gives the attacker only useless hashes. The raw token travels only over HTTPS.

How do you change fraud rules without redeploying?

Rules live in the fraud_rules table, not code. The Rules Engine re-queries every 60 seconds via a scheduled job. An analyst updates a threshold via the Admin API — it takes effect within 60 seconds, no restart.

Can I replace H2 with PostgreSQL in dev?

Yes. Set the profile to dev, run docker-compose up postgres, update the DB env vars. JPA DDL auto-create handles schema generation in both — the same entity classes work unchanged.

Version Control & Upgrade History

Release Timeline

Why Upgrade to v1.1.0? (Security Patches & Rationale)

FraudShield moved from v1.0.0 to v1.1.0 purely to adopt the latest LTS (Long-Term Support) versions of its core stack. This is a Y-level (tech stack) upgrade — no new fraud-detection features were added, but every dependency now sits on a newer, better-patched foundation.

Security Patches & Upgrades Applied

• Java 17 → Java 21 LTS: Picks up 2+ years of JDK security patches and enables virtual threads for lighter-weight concurrency.
• Spring Boot 3.2 → 4.1 (Spring Framework 7): Brings the latest CVE fixes bundled in Spring's 7.x security releases and moves fully to the Jakarta EE 11 baseline.
• Spring Security 6 → 7: Ships hardened defaults for the security filter chain and drops legacy, exploit-prone configuration patterns (like .and() chaining).
• Spring Cloud 2023.0.1 → 2025.1.4: Updates the Eureka client library to a release with patched service-discovery dependencies.
• Jackson 2 → Jackson 3: Closes known deserialization-related vulnerabilities present in older Jackson 2.x minor releases.

v1.0.0 → v1.1.0 Migration Guide

Breaking Changes

• Java 21 minimum requirement (was Java 17). Older JDKs are not supported.
• Spring Framework 7 (from 6): Jakarta EE 11 baseline — no more javax.* imports, all packages use jakarta.*.
• Spring Security 7 (from 6): Lambda DSL required for security configuration; the .and() method chaining pattern is removed.
• Spring Boot starter rename: spring-boot-starter-web is now spring-boot-starter-webmvc.
• Jackson 3 default (from 2): Package namespace changed to tools.jackson.*.
• Spring Cloud 2025.1.4 (from 2023.0.1): Ensure Eureka client version compatibility; the new release uses Spring Boot 4.1 as baseline.

Upgrade Checklist

1. 1
   Update pom.xml dependencies: Change parent version from 3.2.5 to 4.1.2, java.version from 17 to 21, spring-cloud.version from 2023.0.1 to 2025.1.4, springdoc.version from 2.3.0 to 3.1.1. Rename spring-boot-starter-web to spring-boot-starter-webmvc.
2. 2
   Compile and check errors: Run mvn clean compile. Compilation errors are usually minimal if code avoids deprecated APIs. Watch for import errors (javax → jakarta).
3. 3
   Identify renamed config properties: Add spring-boot-properties-migrator temporarily to pom.xml, run mvn spring-boot:run, check logs for property warnings, then remove the dependency.
4. 4
   Run full test suite: Execute mvn test. If tests exist, they validate the upgrade. If none exist, add smoke tests (e.g., context-load tests to verify all 50+ beans initialize).
5. 5
   Boot and verify Eureka registration: Start both Eureka server and backend service. Check http://localhost:8761/eureka/apps to confirm the client instance shows status UP with the correct port and hostname.
6. 6
   Verify all APIs: Test login (JWT token generation), token refresh, fraud rules engine scoring on seeded transactions, Swagger UI, and audit log endpoints.

What Was Tested in v1.1.0

• ✅ Full application context loads — all 50+ Spring beans, security filter chain, JPA repository auto-configuration, JWT filter, Eureka auto-config
• ✅ Unit tests for rules engine — 5 tests covering scoring logic, rule firing, velocity detection, amount anomaly, and edge cases
• ✅ Live Eureka registration — backend registers as FRAUDSHIELD-BACKEND:8080 with status UP and remains discoverable
• ✅ JWT authentication flows — login endpoint, token generation with correct expiry (15 min access, 7d refresh), token refresh with rotation, logout with blacklist
• ✅ Fraud scoring on seeded data — rules engine correctly identifies violations (velocity, amount anomaly, duplicates)
• ✅ Database compatibility — H2 in-memory database (no migration required, schema auto-created via JPA DDL)
• ✅ Spring Security RBAC — role enforcement on protected endpoints, 401/403 distinction