🛡️ Fraud Risk Microservice

Fraud Risk Microservice is a scalable microservice designed to ingest financial transaction data, perform real-time risk analysis, and store audit logs for forensic retrieval.

This project demonstrates a production-grade FinTech architecture using Java 21, Spring Boot 3, and DynamoDB (via LocalStack), implementing the Enhanced Client pattern for persistence.

---

🚀 Features & Functionality

1. Real-Time Risk Simulation

The service includes a specialized Strategy layer (RiskEvaluationService) that automatically assesses the risk of every incoming transaction based on the transaction amount. The system calculates a risk score (0-100) to determine the level:

• LOW Risk (Score < 30): Transaction amount < 500.
• MEDIUM Risk (Score 30-59): Transaction amount between 500 and 3,000.
• HIGH Risk (Score 60-79): Transaction amount between 3,000 and 10,000. Tagged with #AmountHigh.
• CRITICAL Risk (Score >= 80): Transaction amount >= 10,000. Tagged with #AmountCritical.

2. Scalable Data Model (Multi-Index Design)

Optimized for three distinct access patterns using DynamoDB Global Secondary Indexes (GSIs):

• By Sender: Retrieve history for a specific user (Primary Key).
• By Receiver: Track funds going to a specific account (Receiver Index).
• By Risk Level: Filter logs for "HIGH", "CRITICAL", etc. events (Risk Level Index).

3. High-Throughput Ingestion

• Stateless REST API designed for horizontal scaling.
• Asynchronous-ready architecture (persists to DynamoDB).

---

🛠️ Tech Stack

Component	Technology
Language	Java 21 (LTS)
Framework	Spring Boot 3.2.x
Database	AWS DynamoDB (NoSQL)
AWS SDK	AWS SDK v2 (Enhanced Client + Service Client)
Security	Spring Security (Stateless, CSRF disabled for API)
Environment	Docker & LocalStack (for local AWS emulation)
Build Tool	Maven

---

📂 Project Structure

src
└── main
    ├── java/com/seis/fraud/fraud_alert_log
    │   ├── api
    │   │   └── AlertController.java          # REST Endpoints
    │   ├── config
    │   │   ├── AwsConfig.java                # DynamoDB Client Config
    │   │   └── SecurityConfig.java           # Spring Security Rules
    │   ├── dto
    │   │   ├── AlertIngestionRequest.java    # Input DTO
    │   │   ├── AlertResponse.java            # Output DTO
    │   │   └── RiskEvaluationResult.java     # Internal Risk Result
    │   ├── enums
    │   │   └── RiskLevel.java                # Risk Enum Constants
    │   ├── exception
    │   │   └── BadRequestException.java      # Custom Exceptions
    │   ├── model
    │   │   └── SecurityEventLog.java         # DynamoDB Entity
    │   ├── repository
    │   │   └── SecurityEventLogRepository.java # Database Access
    │   ├── service
    │   │   ├── AlertIngestionService.java    # Main Business Logic
    │   │   └── RiskEvaluationService.java    # Risk Strategy Logic
    │   └── FraudAlertLogMicroserviceApplication.java
    └── resources
        ├── application.properties
        └── application.yml                   # Main Configuration

🔗 API Endpoints

1. Ingest Transaction

POST /api/alerts/ingest Accepts raw transaction details, calculates risk, and saves to the database.

Payload:

{
  "transactionId": "TXN-1001",
  "timestamp": "2025-11-22T10:00:00Z",
  "senderId": "USER_A",
  "receiverId": "USER_B",
  "amount": 15000.0,
  "ip": "192.168.1.1"
}

2. Fetch All Logs

GET /api/alerts
Retrieves a full list of all recorded transactions (Scan operation).

3. Fetch by Sender

GET /api/alerts/sender/{senderId}
Retrieves transaction history for a specific sender (Primary Key Query).

4. Fetch by Receiver

GET /api/alerts/receiver/{receiverId}
Retrieves all transactions received by a specific user (GSI Query).

5. Fetch by Risk Level

GET /api/alerts/riskLevel/{riskLevel}
Retrieves all transactions matching a specific risk level (e.g., HIGH, MEDIUM, CRITICAL).

💾 DynamoDB Data Model

The service automatically creates the table transaction-risk-log on startup if it does not exist.

Key / Index	Partition Key (PK)	Sort Key (SK)	Access Pattern
Primary Key		TIMESTAMP#	Get history for a Sender.
RiskLevelIndex (GSI)	riskLevel (e.g., "HIGH")	TIMESTAMP#	Filter logs by Risk Level.
ReceiverIndex (GSI)	receiverId	TIMESTAMP#	Get history for a Receiver.

⚡ Getting Started

1. Prerequisites

• Docker Desktop
• Java 21 SDK
• Maven

2. Start Local Infrastructure

Run the provided Docker Compose file to start LocalStack (DynamoDB).

docker compose up -d

3. (Optional) Reset Database

If you change the schema, use the helper script to wipe the local database.

chmod +x reset_localstack_db.sh
./reset_localstack_db.sh

4. Run the Application

Start the Spring Boot service.

mvn spring-boot:run -DskipTests

The API will be available at: http://localhost:8080

🔮 Future To-Do

1. Advanced Fraud Detection: Add more complex logic such as:
   • Unusual IP Detection: Flag transactions originating from IPs that deviate from a user's history.
   • Blacklist: Maintain a blacklist of suspicious sender and receiver IDs to automatically flag or block transactions.
2. High Traffic Simulation: Implement a batch processing feature or a load generation script to simulate high-volume transaction ingestion and test system scalability.