Trade Finance Application

A robust Spring Boot service designed for managing trade finance operations, including real-time currency conversion, transaction auditing, and automated notifications.

🚀 Getting Started

Prerequisites

• Java 21: Required for Record types and modern Spring Boot 3.2+ features.
• Maven 3.9+: For dependency management and building.

Setup and Installation

1. Package Alignment: Ensure TradeFinanceApplication.java is located in the com.db.assessment package to avoid component scanning issues.
2. Compile and Build:

   mvn clean install

3. Run the Application:

   mvn spring-boot:run

   The server will start on http://localhost:8080 by default.

---

🛠 Monitoring & Health (Actuator)

The application integrates Spring Boot Actuator to provide production-ready health checks. This allows you to verify that the application and its core services are initialized correctly.

Check Service Health

Visit the health endpoint to see the current status of the application.

• Endpoint: GET /actuator/health
• Command:

  curl http://localhost:8080/actuator/health

• Expected Response:

  {
    "status": "UP"
  }

---

🧪 Testing the API

1. Currency Conversion

Perform currency conversions between USD, EUR, SGD, and GBP. This service validates the input amount and checks for supported currency codes.

• Endpoint: POST /api/v1/trade-finance/convert
• Test Command:

  curl -X POST http://localhost:8080/api/v1/trade-finance/convert \
       -H "Content-Type: application/json" \
       -d '{"amount": 500, "from": "EUR", "to": "USD"}'

2. Test a Transaction Submission

This is the primary workflow test. It triggers a series of backend actions: Validation → Auto-Approval Logic → Auditing → Notification.

• Endpoint: POST /api/v1/trade-finance/transaction
• Test Command:

  curl -X POST http://localhost:8080/api/v1/trade-finance/transaction \
       -H "Content-Type: application/json" \
       -d '{
             "amount": 1250.0,
             "currency": "USD",
             "submittedBy": "user@db.com"
           }'

Verification Steps:

1. Response Status: Check if you receive a 200 OK (Approved) or 202 Accepted (Pending).
2. Application Logs: Check the console for an audit entry: AUDIT: TRANSACTION_SUBMITTED | user@db.com | 1250.0 USD STATUS=...
3. Notification: If approved, look for the log notification: [LOG-NOTIFY] to=user@db.com | Transaction Approved

3. Review Audit Logs

Verify that actions were recorded in the system audit trail.

• Endpoint: GET /api/v1/trade-finance/audit?limit=5
• Command:

  curl http://localhost:8080/api/v1/trade-finance/audit?limit=5

---

---

🏗 Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Trade Finance API                        │
│                    (Spring Boot 3.2.4)                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┐         ┌─────────────────────────┐   │
│  │  Controller    │────────▶│  GlobalExceptionHandler │   │
│  │                │         │  (@ControllerAdvice)    │   │
│  └────────┬───────┘         └─────────────────────────┘   │
│           │                                                 │
│           │ inject                                          │
│           ▼                                                 │
│  ┌────────────────┐         ┌─────────────────────────┐   │
│  │   Services     │────────▶│    AppProperties        │   │
│  │  - Converter   │         │ (@ConfigurationProps)   │   │
│  │  - Audit       │         └─────────────────────────┘   │
│  │  - Notification│                                        │
│  └────────┬───────┘                                        │
│           │                                                 │
│           │ wired by                                        │
│           ▼                                                 │
│  ┌────────────────┐                                        │
│  │   AppConfig    │  ← @Profile, @Conditional, @Bean       │
│  │  (Bean Factory)│                                        │
│  └────────────────┘                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Key Components

Component	Responsibility	Pattern
AppProperties	Binds application.yml to Java objects	@ConfigurationProperties + @Validated
AppConfig	Wires beans per environment	@Profile, @Conditional, @Bean
GlobalExceptionHandler	Centralizes error responses	@ControllerAdvice + @ExceptionHandler
TradeFinanceController	Exposes REST endpoints	@RestController + dependency injection
Service Implementations	Business logic	Interface segregation + strategy pattern

📂 Project Architecture

• com.db.assessment.controller: REST controllers for API exposure.
• com.db.assessment.service: Core interfaces (AuditService, CurrencyConverter, NotificationService) and models (AuditEntry).
• com.db.assessment.service.impl: Business logic implementations including:
  • MockCurrencyConverter (Dev) / LiveCurrencyConverter (Prod)
  • DatabaseAuditService (Active) / NoOpAuditService (Disabled)
  • LogNotificationService (Console) / EmailNotificationService (SMTP)
• com.db.assessment.exception: Unified error handling returning structured ErrorResponse objects.

---

⚙️ Configuration & Profiles

The application behavior is driven by the active Spring Profile:

• dev: Uses mock data and console logging.
• prod: Uses live FX rates and email notification services.

---

🌐 REST API Endpoints

Base URL

http://localhost:8080/api/v1/trade-finance

Endpoints

Method	Path	Description
GET	/config	Returns active configuration
POST	/convert	Currency conversion
GET	/rates	Current FX rates (cached)
GET	/audit?limit=10	Recent audit log
POST	/transaction	Submit transaction for approval

Examples

1. Currency Conversion

curl -X POST http://localhost:8080/api/v1/trade-finance/convert \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "from": "USD",
    "to": "EUR"
  }'

Response:

{
  "from": "USD",
  "to": "EUR",
  "original": 1000.0,
  "converted": 1087.0,
  "timestamp": "2026-04-19T14:30:00Z"
}

2. Submit Transaction

curl -X POST http://localhost:8080/api/v1/trade-finance/transaction \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "submittedBy": "trader1"
  }'

Response (dev — auto-approve):

{
  "status": "APPROVED",
  "amount": 5000.0,
  "currency": "USD",
  "submittedBy": "trader1",
  "timestamp": "2026-04-19T14:30:00Z"
}

3. Error Handling

curl -X POST http://localhost:8080/api/v1/trade-finance/convert \
  -H "Content-Type: application/json" \
  -d '{
    "amount": -100,
    "from": "USD",
    "to": "EUR"
  }'

Response (400 Bad Request):

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "Amount below minimum: 1.0",
  "timestamp": "2026-04-19T14:30:00Z"
}

---

🧪 Running Tests

Test Pyramid

               ┌─────────────────┐
               │  15 Integration │  @SpringBootTest + MockMvc
               │  (Controller)   │  Full Spring context
               └─────────────────┘
              ┌───────────────────┐
              │  20 Context Tests │  @SpringBootTest
              │  (Bean Wiring)    │  Profile verification
              └───────────────────┘
          ┌───────────────────────────┐
          │    35+ Unit Tests         │  No Spring — FAST
          │ (Business Logic)          │  Pure Java
          └───────────────────────────┘

Run All Tests

mvn test

Run Specific Test Classes

# Unit tests (fast, no Spring)
mvn test -Dtest="TradeFinanceTests\$AppPropertiesUnitTests"
mvn test -Dtest="TradeFinanceTests\$TransactionValidatorTests"

# Integration tests (Spring context)
mvn test -Dtest="TradeFinanceTests\$ControllerTests"
mvn test -Dtest=ExceptionHandlerTests

# Profile-specific
mvn test -Dtest="TradeFinanceTests\$DevProfileContextTests"
mvn test -Dtest="TradeFinanceTests\$TestProfileContextTests"

Test Coverage Summary

Test Class	Tests	Coverage
AppPropertiesUnitTests	9	Config binding, defaults
TransactionValidatorTests	10	Business rules, edge cases
FxRateCacheTests	7	Cache operations
DevProfileContextTests	6	Bean wiring (dev profile)
TestProfileContextTests	3	Bean wiring (test profile)
ControllerTests	12	REST endpoints
AppConfigBeanTests	9	Bean factory methods
ExceptionHandlerTests	9	Error handling
Total	65+	All layers

---

📁 Project Structure

src/
├── main/
│   ├── java/com/db/assessment/
│   │   ├── AssessmentApplication.java           # Main entry point
│   │   ├── config/
│   │   │   ├── AppProperties.java               # @ConfigurationProperties
│   │   │   └── AppConfig.java                   # Bean factory
│   │   ├── controller/
│   │   │   └── TradeFinanceController.java      # REST endpoints
│   │   ├── exception/
│   │   │   └── GlobalExceptionHandler.java      # @ControllerAdvice
│   │   └── service/
│   │       ├── CurrencyConverter.java           # Interface
│   │       ├── AuditService.java                # Interface
│   │       ├── NotificationService.java         # Interface
│   │       └── impl/
│   │           └── ServiceImplementations.java  # 6 implementations
│   └── resources/
│       └── application.yml                      # Multi-profile config
└── test/
    └── java/com/db/assessment/
        ├── TradeFinanceTests.java               # Main test suite
        └── ExceptionHandlerTests.java           # Error handling tests

---

🔧 Configuration Profiles

dev (Developer-Friendly)

app:
  trade-finance:
    auto-approve: true         # Auto-approve transactions
    max-transaction-amount: 99999999.00
  audit:
    enabled: true

Run: mvn spring-boot:run

test (Fast, Silent)

app:
  trade-finance:
    max-transaction-amount: 50000.00
  audit:
    enabled: false             # NoOp audit
  rate-limit:
    enabled: false             # No throttling

Run: mvn test

prod (Production-Grade)

app:
  trade-finance:
    auto-approve: false        # Manual approval
    settlement-mode: "T+1"
  security:
    require-https: true
  rate-limit:
    requests-per-second: 50    # Stricter limits

Run: mvn spring-boot:run -Dspring-boot.run.profiles=prod

---

⚠️ Exception Handling

Supported Exception Types

Exception	HTTP Status	Error Code	Example
IllegalArgumentException	400	INVALID_INPUT	"Amount below minimum"
MethodArgumentNotValidException	400	VALIDATION_FAILED	@Valid failures
HttpMessageNotReadableException	400	MALFORMED_JSON	Invalid JSON
MethodArgumentTypeMismatchException	400	TYPE_MISMATCH	?limit=abc
NoSuchElementException	404	RESOURCE_NOT_FOUND	Not found
UnsupportedCurrencyException	400	UNSUPPORTED_CURRENCY	Custom exception
InsufficientFundsException	422	INSUFFICIENT_FUNDS	Custom exception
Exception (catch-all)	500	INTERNAL_ERROR	Unexpected errors

Error Response Format

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "Amount below minimum: 1.0",
  "timestamp": "2026-04-19T14:30:00Z",
  "details": {}
}