# elizabetheldhose/fraud-forensic-service architecture

> Architecture diagram of the GitHub repository elizabetheldhose/fraud-forensic-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elizabetheldhose/fraud-forensic-service
- Repository: https://github.com/elizabetheldhose/fraud-forensic-service

## Overview

This is a Spring Boot forensic API with two client workflows: submit case-scoped search criteria and receive ranked OpenSearch hits, or request a short-lived S3 upload URL and upload the file directly to S3. Search queries an index described as populated by an upstream Lambda pipeline. The graph shows the controller-owned service calls and the external calls visible in the excerpts; AWS configuration and Lambda internals were not excerpted, so their wiring is not inferred.

Main entry points: [`src/main/java/com/ibm/forensic/service/ForensicSearchService.java`](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/ForensicSearchService.java) (Forensic Search), [`src/main/java/com/ibm/forensic/service/S3PresignService.java`](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/S3PresignService.java) (S3 URL Signing), [`src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java`](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java) (Error Mapping), [`src/main/java/com/ibm/forensic/controller/ReportController.java`](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/controller/ReportController.java) (Report Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_report["Report Endpoint"]
  node_upload["Upload Endpoint"]
  node_errors["Error Mapping"]
  node_apierror["Error Payload"]
  node_searchrequest["Search Criteria"]
  node_searchresponse["Search Results"]
  node_uploadrequest["Upload Metadata"]
  node_uploadresponse["Signed URL"]
end

subgraph group_domain["Forensic Services"]
  node_searchservice["Forensic Search"]
  node_searcherror["Search Exception"]
  node_presignservice["S3 URL Signing"]
  node_presignerror["Signing Exception"]
end

subgraph group_aws["AWS Integrations"]
  node_awsconfig["AWS Configuration<br/>[AwsConfig.java]"]
  node_opensearch[("OpenSearch")]
  node_s3[("S3 Bucket")]
  node_lambda["Ingest Lambda<br/>[lambda_function.py]"]
end

node_client(("API Client"))

node_client -->|"submits search"| node_report
node_report -->|"accepts criteria"| node_searchrequest
node_report -->|"delegates search"| node_searchservice
node_searchservice -->|"queries index"| node_opensearch
node_searchservice -->|"maps hits"| node_searchresponse
node_searchservice -->|"throws on failure"| node_searcherror
node_searchservice -->|"reads criteria"| node_searchrequest
node_client -->|"requests URL"| node_upload
node_upload -->|"accepts metadata"| node_uploadrequest
node_upload -->|"delegates signing"| node_presignservice
node_presignservice -->|"presigns PUT"| node_s3
node_presignservice -->|"returns URL"| node_uploadresponse
node_presignservice -->|"reads metadata"| node_uploadrequest
node_presignservice -->|"throws on failure"| node_presignerror
node_client -->|"uploads directly"| node_s3
node_lambda -->|"populates index"| node_opensearch
node_errors -->|"creates payload"| node_apierror
node_errors -->|"maps failure"| node_searcherror
node_errors -->|"maps failure"| node_presignerror

click node_report "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/controller/ReportController.java"
click node_upload "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/controller/UploadController.java"
click node_errors "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java"
click node_apierror "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ApiErrorResponse.java"
click node_searchrequest "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ForensicSearchRequest.java"
click node_searchresponse "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ForensicSearchResponse.java"
click node_uploadrequest "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/PresignedUrlRequest.java"
click node_uploadresponse "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/PresignedUrlResponse.java"
click node_searchservice "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/ForensicSearchService.java"
click node_searcherror "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/ForensicSearchException.java"
click node_presignservice "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/S3PresignService.java"
click node_presignerror "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/PresignedUrlGenerationException.java"
click node_awsconfig "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/config/AwsConfig.java"
click node_lambda "https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/infrastructure/lambda/lambda_function.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_report,node_upload,node_errors,node_apierror,node_searchrequest,node_searchresponse,node_uploadrequest,node_uploadresponse,node_client toneBlue
class node_searchservice,node_searcherror,node_presignservice,node_presignerror toneAmber
class node_awsconfig,node_opensearch,node_s3,node_lambda toneMint
```

## Components

### HTTP API

- [Report Endpoint](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/controller/ReportController.java): `src/main/java/com/ibm/forensic/controller/ReportController.java`
- [Upload Endpoint](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/controller/UploadController.java): `src/main/java/com/ibm/forensic/controller/UploadController.java`
- [Error Mapping](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java): `src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java`
- [Error Payload](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ApiErrorResponse.java): `src/main/java/com/ibm/forensic/dto/ApiErrorResponse.java`
- [Search Criteria](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ForensicSearchRequest.java): `src/main/java/com/ibm/forensic/dto/ForensicSearchRequest.java`
- [Search Results](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/ForensicSearchResponse.java): `src/main/java/com/ibm/forensic/dto/ForensicSearchResponse.java`
- [Upload Metadata](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/PresignedUrlRequest.java): `src/main/java/com/ibm/forensic/dto/PresignedUrlRequest.java`
- [Signed URL](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/dto/PresignedUrlResponse.java): `src/main/java/com/ibm/forensic/dto/PresignedUrlResponse.java`

### Forensic Services

- [Forensic Search](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/ForensicSearchService.java): `src/main/java/com/ibm/forensic/service/ForensicSearchService.java`
- [Search Exception](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/ForensicSearchException.java): `src/main/java/com/ibm/forensic/exception/ForensicSearchException.java`
- [S3 URL Signing](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/service/S3PresignService.java): `src/main/java/com/ibm/forensic/service/S3PresignService.java`
- [Signing Exception](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/exception/PresignedUrlGenerationException.java): `src/main/java/com/ibm/forensic/exception/PresignedUrlGenerationException.java`

### AWS Integrations

- [AWS Configuration](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/src/main/java/com/ibm/forensic/config/AwsConfig.java): `src/main/java/com/ibm/forensic/config/AwsConfig.java`
- **OpenSearch**
- **S3 Bucket**
- [Ingest Lambda](https://github.com/elizabetheldhose/fraud-forensic-service/blob/main/infrastructure/lambda/lambda_function.py): `infrastructure/lambda/lambda_function.py`

### Other components

- **API Client**

## Connections

- API Client → Report Endpoint: submits search (evidence: `src/main/java/com/ibm/forensic/controller/ReportController.java`)
- Report Endpoint → Search Criteria: accepts criteria (evidence: `src/main/java/com/ibm/forensic/controller/ReportController.java`)
- Report Endpoint → Forensic Search: delegates search (evidence: `src/main/java/com/ibm/forensic/controller/ReportController.java`)
- Forensic Search → OpenSearch: queries index (evidence: `src/main/java/com/ibm/forensic/service/ForensicSearchService.java`)
- Forensic Search → Search Results: maps hits (evidence: `src/main/java/com/ibm/forensic/service/ForensicSearchService.java`)
- Forensic Search → Search Exception: throws on failure (evidence: `src/main/java/com/ibm/forensic/service/ForensicSearchService.java`)
- Forensic Search → Search Criteria: reads criteria (evidence: `src/main/java/com/ibm/forensic/service/ForensicSearchService.java`)
- API Client → Upload Endpoint: requests URL (evidence: `src/main/java/com/ibm/forensic/controller/UploadController.java`)
- Upload Endpoint → Upload Metadata: accepts metadata (evidence: `src/main/java/com/ibm/forensic/controller/UploadController.java`)
- Upload Endpoint → S3 URL Signing: delegates signing (evidence: `src/main/java/com/ibm/forensic/controller/UploadController.java`)
- S3 URL Signing → S3 Bucket: presigns PUT (evidence: `src/main/java/com/ibm/forensic/service/S3PresignService.java`)
- S3 URL Signing → Signed URL: returns URL (evidence: `src/main/java/com/ibm/forensic/service/S3PresignService.java`)
- S3 URL Signing → Upload Metadata: reads metadata (evidence: `src/main/java/com/ibm/forensic/service/S3PresignService.java`)
- S3 URL Signing → Signing Exception: throws on failure (evidence: `src/main/java/com/ibm/forensic/service/S3PresignService.java`)
- API Client → S3 Bucket: uploads directly
- Ingest Lambda → OpenSearch: populates index
- Error Mapping → Error Payload: creates payload (evidence: `src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java`)
- Error Mapping → Search Exception: maps failure (evidence: `src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java`)
- Error Mapping → Signing Exception: maps failure (evidence: `src/main/java/com/ibm/forensic/exception/GlobalExceptionHandler.java`)
