feat: Implement credit card application feature with validation and error handling

.github/instructions/java.instructions.md

@@ -0,0 +1,82 @@
+---
+description: 'Guidelines for building Java base applications'
+applyTo: '**/*.java'
+---
+
+# Java Development
+
+## General Instructions
+
+- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup.
+  - If yes, document a recommended static-analysis setup. 
+    - Prefer SonarQube/SonarCloud (SonarLint in IDE + `sonar-scanner` in CI).
+    - Create a Sonar project key.
+    - Store the scanner token in CI secrets.
+    - Provide a sample CI job that runs the scanner.
+    - If the team declines Sonar, note this in the project README and continue.
+  - If Sonar is bound to the project:
+    - Use Sonar as the primary source of actionable issues.
+    - Reference Sonar rule keys in remediation guidance.
+  - If Sonar is unavailable:
+    - Perform up to 3 troubleshooting checks:
+      1. Verify project binding and token.
+      2. Ensure SonarScanner runs in CI.
+      3. Confirm SonarLint is installed and configured.
+    - If still failing after 3 attempts:
+      - Enable SpotBugs, PMD, or Checkstyle as CI fallbacks.
+      - Open a short tracker issue documenting the blocker and next steps.
+- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
+- Address code smells proactively during development rather than accumulating technical debt.
+- Focus on readability, maintainability, and performance when refactoring identified issues.
+- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.
+
+## Best practices
+
+- **Imports**: **MUST never use Java wildcard imports** (e.g., `import java.util.*`). Always use explicit imports for each class (e.g., `import java.util.List`). This improves readability, avoids naming conflicts, and makes dependencies explicit.
+- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**.
+- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting.
+- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
+- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists.
+- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`).
+- **Null Handling**: Avoid returning or accepting `null`. Use `Optional<T>` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`.
+
+### Naming Conventions
+
+- Follow Google's Java style guide:
+  - `UpperCamelCase` for class and interface names.
+  - `lowerCamelCase` for method and variable names.
+  - `UPPER_SNAKE_CASE` for constants.
+  - `lowercase` for package names.
+- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
+- Avoid abbreviations and Hungarian notation.
+
+### Common Bug Patterns
+
+Below are concise, human-readable rules you can apply regardless of which static analysis tool you use. If you run Sonar/SonarLint, the IDE will show the matching rule and location — direct Sonar connections are preferred and should override this ruleset.
+
+- Resource management — Always close resources (files, sockets, streams). Use try-with-resources where possible so resources are closed automatically.
+- Equality checks — Compare object equality with `.equals()` or `Objects.equals(...)` rather than `==` for non-primitives; this avoids reference-equality bugs.
+- Redundant casts — Remove unnecessary casts; prefer correct generic typing and let the compiler infer types where possible.
+- Reachable conditions — Avoid conditional expressions that are always true or false; they indicate bugs or dead code and should be corrected.
+
+For contributors who *do* use Sonar or SonarLint: the IDE/scan will show the specific rule key (for example, S2095 for resource leaks) and the affected file/line. Use that information to navigate to the exact location, then apply the recommended remediation.
+
+### Common Code Smells
+
+These patterns are phrased for humans; they map cleanly to checks in Sonar, SpotBugs, PMD, or Checkstyle but do not require those tools to be useful.
+
+- Parameter count — Keep method parameter lists short. If a method needs many params, consider grouping into a value object or using the builder pattern.
+- Method size — Keep methods focused and small. Extract helper methods to improve readability and testability.
+- Cognitive complexity — Reduce nested conditionals and heavy branching by extracting methods, using polymorphism, or applying the Strategy pattern.
+- Duplicated literals — Extract repeated strings and numbers into named constants or enums to reduce errors and ease changes.
+- Dead code — Remove unused variables and assignments. They confuse readers and can hide bugs.
+- Magic numbers — Replace numeric literals with named constants that explain intent (e.g., MAX_RETRIES).
+
+If you run a static analyzer like Sonar or SonarLint — direct Sonar connections are preferred and should override this ruleset. Sonar rule keys are useful for automation and suppression, but they are not required in day-to-day developer guidance.
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.

.github/instructions/reactjs.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'ReactJS development standards and best practices'
+applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
+---
+
+# ReactJS Development Instructions
+
+Instructions for building high-quality ReactJS applications with modern patterns, hooks, and best practices following the official React documentation at https://react.dev.
+
+## Project Context
+- Latest React version (React 19+)
+- TypeScript for type safety (when applicable)
+- Functional components with hooks as default
+- Follow React's official style guide and best practices
+- Use modern build tools (Vite, Create React App, or custom Webpack setup)
+- Implement proper component composition and reusability patterns
+
+## Development Standards
+
+### Architecture
+- Use functional components with hooks as the primary pattern
+- Implement component composition over inheritance
+- Organize components by feature or domain for scalability
+- Separate presentational and container components clearly
+- Use custom hooks for reusable stateful logic
+- Implement proper component hierarchies with clear data flow
+
+### TypeScript Integration
+- Use TypeScript interfaces for props, state, and component definitions
+- Define proper types for event handlers and refs
+- Implement generic components where appropriate
+- Use strict mode in `tsconfig.json` for type safety
+- Leverage React's built-in types (`React.FC`, `React.ComponentProps`, etc.)
+- Create union types for component variants and states
+
+### Component Design
+- Follow the single responsibility principle for components
+- Use descriptive and consistent naming conventions
+- Implement proper prop validation with TypeScript or PropTypes
+- Design components to be testable and reusable
+- Keep components small and focused on a single concern
+- Use composition patterns (render props, children as functions)
+
+### State Management
+- Use `useState` for local component state
+- Implement `useReducer` for complex state logic
+- Leverage `useContext` for sharing state across component trees
+- Consider external state management (Redux Toolkit, Zustand) for complex applications
+- Implement proper state normalization and data structures
+- Use React Query or SWR for server state management
+
+### Hooks and Effects
+- Use `useEffect` with proper dependency arrays to avoid infinite loops
+- Implement cleanup functions in effects to prevent memory leaks
+- Use `useMemo` and `useCallback` for performance optimization when needed
+- Create custom hooks for reusable stateful logic
+- Follow the rules of hooks (only call at the top level)
+- Use `useRef` for accessing DOM elements and storing mutable values
+
+### Styling
+- Use CSS Modules, Styled Components, or modern CSS-in-JS solutions
+- Implement responsive design with mobile-first approach
+- Follow BEM methodology or similar naming conventions for CSS classes
+- Use CSS custom properties (variables) for theming
+- Implement consistent spacing, typography, and color systems
+- Ensure accessibility with proper ARIA attributes and semantic HTML
+
+### Performance Optimization
+- Use `React.memo` for component memoization when appropriate
+- Implement code splitting with `React.lazy` and `Suspense`
+- Optimize bundle size with tree shaking and dynamic imports
+- Use `useMemo` and `useCallback` judiciously to prevent unnecessary re-renders
+- Implement virtual scrolling for large lists
+- Profile components with React DevTools to identify performance bottlenecks
+
+### Data Fetching
+- Use modern data fetching libraries (React Query, SWR, Apollo Client)
+- Implement proper loading, error, and success states
+- Handle race conditions and request cancellation
+- Use optimistic updates for better user experience
+- Implement proper caching strategies
+- Handle offline scenarios and network errors gracefully
+
+### Error Handling
+- Implement Error Boundaries for component-level error handling
+- Use proper error states in data fetching
+- Implement fallback UI for error scenarios
+- Log errors appropriately for debugging
+- Handle async errors in effects and event handlers
+- Provide meaningful error messages to users
+
+### Forms and Validation
+- Use controlled components for form inputs
+- Implement proper form validation with libraries like Formik, React Hook Form
+- Handle form submission and error states appropriately
+- Implement accessibility features for forms (labels, ARIA attributes)
+- Use debounced validation for better user experience
+- Handle file uploads and complex form scenarios
+
+### Routing
+- Use React Router for client-side routing
+- Implement nested routes and route protection
+- Handle route parameters and query strings properly
+- Implement lazy loading for route-based code splitting
+- Use proper navigation patterns and back button handling
+- Implement breadcrumbs and navigation state management
+
+### Testing
+- Write unit tests for components using React Testing Library
+- Test component behavior, not implementation details
+- Use Jest for test runner and assertion library
+- Implement integration tests for complex component interactions
+- Mock external dependencies and API calls appropriately
+- Test accessibility features and keyboard navigation
+
+### Security
+- Sanitize user inputs to prevent XSS attacks
+- Validate and escape data before rendering
+- Use HTTPS for all external API calls
+- Implement proper authentication and authorization patterns
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use Content Security Policy (CSP) headers
+
+### Accessibility
+- Use semantic HTML elements appropriately
+- Implement proper ARIA attributes and roles
+- Ensure keyboard navigation works for all interactive elements
+- Provide alt text for images and descriptive text for icons
+- Implement proper color contrast ratios
+- Test with screen readers and accessibility tools
+
+## Implementation Process
+1. Plan component architecture and data flow
+2. Set up project structure with proper folder organization
+3. Define TypeScript interfaces and types
+4. Implement core components with proper styling
+5. Add state management and data fetching logic
+6. Implement routing and navigation
+7. Add form handling and validation
+8. Implement error handling and loading states
+9. Add testing coverage for components and functionality
+10. Optimize performance and bundle size
+11. Ensure accessibility compliance
+12. Add documentation and code comments
+
+## Additional Guidelines
+- Follow React's naming conventions (PascalCase for components, camelCase for functions)
+- Use meaningful commit messages and maintain clean git history
+- Implement proper code splitting and lazy loading strategies
+- Document complex components and custom hooks with JSDoc
+- Use ESLint and Prettier for consistent code formatting
+- Keep dependencies up to date and audit for security vulnerabilities
+- Implement proper environment configuration for different deployment stages
+- Use React Developer Tools for debugging and performance analysis
+
+## Common Patterns
+- Higher-Order Components (HOCs) for cross-cutting concerns
+- Render props pattern for component composition
+- Compound components for related functionality
+- Provider pattern for context-based state sharing
+- Container/Presentational component separation
+- Custom hooks for reusable logic extraction

backend/src/main/java/com/threeriversbank/config/GlobalExceptionHandler.java

@@ -0,0 +1,40 @@
+package com.threeriversbank.config;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.util.HashMap;
+import java.util.Map;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<Map<String, Object>> handleValidationErrors(MethodArgumentNotValidException ex) {
+        Map<String, String> fieldErrors = new HashMap<>();
+        ex.getBindingResult().getFieldErrors().forEach(error ->
+                fieldErrors.put(error.getField(), error.getDefaultMessage()));
+
+        Map<String, Object> response = new HashMap<>();
+        response.put("error", "Validation failed");
+        response.put("fieldErrors", fieldErrors);
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
+    }
+
+    @ExceptionHandler(IllegalArgumentException.class)
+    public ResponseEntity<Map<String, Object>> handleIllegalArgumentException(IllegalArgumentException ex) {
+        Map<String, Object> response = new HashMap<>();
+        response.put("error", ex.getMessage());
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
+    }
+
+    @ExceptionHandler(RuntimeException.class)
+    public ResponseEntity<Map<String, Object>> handleRuntimeException(RuntimeException ex) {
+        Map<String, Object> response = new HashMap<>();
+        response.put("error", ex.getMessage());
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
+    }
+}

backend/src/main/java/com/threeriversbank/controller/CreditCardApplicationController.java

@@ -0,0 +1,55 @@
+package com.threeriversbank.controller;
+
+import com.threeriversbank.model.dto.CreditCardApplicationRequest;
+import com.threeriversbank.model.dto.CreditCardApplicationResponse;
+import com.threeriversbank.service.CreditCardApplicationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/applications")
+@RequiredArgsConstructor
+@Slf4j
+@Tag(name = "Credit Card Applications", description = "Apply for Three Rivers Bank Business Credit Cards")
+public class CreditCardApplicationController {
+
+    private final CreditCardApplicationService applicationService;
+
+    @PostMapping
+    @Operation(summary = "Submit a credit card application",
+            description = "Submit a new business credit card application")
+    public ResponseEntity<CreditCardApplicationResponse> submitApplication(
+            @Valid @RequestBody CreditCardApplicationRequest request) {
+        log.info("POST /api/applications - Submitting application for card id: {}", request.getCardId());
+        CreditCardApplicationResponse response = applicationService.submitApplication(request);
+        return ResponseEntity.status(HttpStatus.CREATED).body(response);
+    }
+
+    @GetMapping("/reference/{referenceNumber}")
+    @Operation(summary = "Get application by reference number",
+            description = "Look up an application status by its reference number")
+    public ResponseEntity<CreditCardApplicationResponse> getApplicationByReference(
+            @PathVariable String referenceNumber) {
+        log.info("GET /api/applications/reference/{}", referenceNumber);
+        CreditCardApplicationResponse response = applicationService.getApplicationByReference(referenceNumber);
+        return ResponseEntity.ok(response);
+    }
+
+    @GetMapping
+    @Operation(summary = "Get applications by email",
+            description = "Look up all applications for a given email address")
+    public ResponseEntity<List<CreditCardApplicationResponse>> getApplicationsByEmail(
+            @RequestParam String email) {
+        log.info("GET /api/applications?email={}", email);
+        List<CreditCardApplicationResponse> responses = applicationService.getApplicationsByEmail(email);
+        return ResponseEntity.ok(responses);
+    }
+}