# rjaycarl/torrestrace architecture

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

- Interactive diagram: https://gitdiagram.com/rjaycarl/torrestrace
- Repository: https://github.com/rjaycarl/torrestrace

## Overview

TorresTrace is a Spring Boot starter that captures HTTP request/response exchanges, persists them, and exposes APIs for listing, inspection, statistics, deletion, and replay. The intended workflow is a consumer request → capture → trace storage → developer/QA inspection or replay. The README documents all storage modes and management capabilities; sampled source confirms the service/controller/storage relationships, while capture wiring and some storage selection details are not shown, so those links are marked unverified.

Main entry points: [`torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/StorageService.java`](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/StorageService.java) (Storage contract), [`torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java`](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java) (Trace service), [`torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java`](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java) (Trace API), [`torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java`](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and policy"]
  node_capture_filter["Request wrapper"]
  node_capture_interceptor["Trace interceptor"]
  node_trace_aspect["Selective tracing<br/>[TraceAspect.java]"]
  node_redaction["Sensitive-data redactor"]
  node_properties["Trace settings"]
end

subgraph group_trace["Trace lifecycle"]
  node_trace_service["Trace service<br/>[TraceService.java]"]
  node_trace_record["Trace record<br/>[TraceEntity.java]"]
  node_trace_mapper["Response mapper<br/>[TraceMapper.java]"]
end

subgraph group_storage["Storage backends"]
  node_storage_contract["Storage contract"]
  node_jpa_storage[("JPA storage")]
  node_json_storage[("JSON file storage")]
  node_directory_storage[("Directory storage")]
  node_noop_storage["No-op storage"]
end

subgraph group_operations["Inspection and replay"]
  node_public_api["Trace API"]
  node_admin_api["Admin API"]
  node_inspection["Trace inspection"]
  node_replay["Request replay<br/>[ReplayService.java]"]
  node_errors["API error handling"]
end

node_consumer(("Consumer API"))
node_replay_target(("Replay destination"))

node_consumer -.->|"sends request"| node_capture_filter
node_capture_filter -.->|"captures exchange"| node_capture_interceptor
node_capture_interceptor -.->|"records trace"| node_trace_service
node_trace_aspect -.->|"selects handlers"| node_capture_interceptor
node_properties -.->|"controls selection"| node_trace_aspect
node_capture_interceptor -.->|"redacts data"| node_redaction
node_trace_service -->|"persists and queries"| node_storage_contract
node_storage_contract -.->|"implemented by"| node_jpa_storage
node_storage_contract -.->|"implemented by"| node_json_storage
node_storage_contract -.->|"implemented by"| node_directory_storage
node_storage_contract -.->|"implemented by"| node_noop_storage
node_trace_service -->|"serializes trace"| node_trace_record
node_public_api -->|"lists and finds"| node_trace_service
node_public_api -->|"maps responses"| node_trace_mapper
node_public_api -->|"requests replay"| node_replay
node_admin_api -->|"filters and manages"| node_trace_service
node_admin_api -->|"requests statistics"| node_inspection
node_admin_api -->|"requests replay"| node_replay
node_inspection -->|"queries traces"| node_storage_contract
node_inspection -->|"maps traces"| node_trace_mapper
node_replay -.->|"sends replay"| node_replay_target
node_public_api -->|"handled failures"| node_errors
node_admin_api -->|"handled failures"| node_errors

click node_capture_filter "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/filter/TorresTraceRequestResponseWrapperFilter.java"
click node_capture_interceptor "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java"
click node_trace_aspect "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/advice/TraceAspect.java"
click node_redaction "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/util/SensitiveDataRedactor.java"
click node_properties "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/config/TorresTraceProperties.java"
click node_trace_service "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java"
click node_trace_record "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/domain/TraceEntity.java"
click node_trace_mapper "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/mapper/TraceMapper.java"
click node_storage_contract "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/StorageService.java"
click node_jpa_storage "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JpaStorageService.java"
click node_json_storage "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JsonFileStorageService.java"
click node_directory_storage "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/FileDirectoryStorageService.java"
click node_noop_storage "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/NoOpStorageService.java"
click node_public_api "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java"
click node_admin_api "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java"
click node_inspection "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/InspectionService.java"
click node_replay "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/ReplayService.java"
click node_errors "https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/exception/GlobalExceptionHandler.java"

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_capture_filter,node_capture_interceptor,node_trace_aspect,node_redaction,node_properties toneBlue
class node_trace_service,node_trace_record,node_trace_mapper toneAmber
class node_storage_contract,node_jpa_storage,node_json_storage,node_directory_storage,node_noop_storage,node_consumer toneMint
class node_public_api,node_admin_api,node_inspection,node_replay,node_errors toneRose
class node_replay_target toneIndigo
```

## Components

### Capture and policy

- [Request wrapper](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/filter/TorresTraceRequestResponseWrapperFilter.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/filter/TorresTraceRequestResponseWrapperFilter.java`
- [Trace interceptor](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java`
- [Selective tracing](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/advice/TraceAspect.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/advice/TraceAspect.java`
- [Sensitive-data redactor](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/util/SensitiveDataRedactor.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/util/SensitiveDataRedactor.java`
- [Trace settings](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/config/TorresTraceProperties.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/config/TorresTraceProperties.java`

### Trace lifecycle

- [Trace service](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java`
- [Trace record](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/domain/TraceEntity.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/domain/TraceEntity.java`
- [Response mapper](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/mapper/TraceMapper.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/mapper/TraceMapper.java`

### Storage backends

- [Storage contract](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/StorageService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/StorageService.java`
- [JPA storage](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JpaStorageService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JpaStorageService.java`
- [JSON file storage](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JsonFileStorageService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/JsonFileStorageService.java`
- [Directory storage](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/FileDirectoryStorageService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/FileDirectoryStorageService.java`
- [No-op storage](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/NoOpStorageService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/NoOpStorageService.java`

### Inspection and replay

- [Trace API](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java`
- [Admin API](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java`
- [Trace inspection](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/InspectionService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/InspectionService.java`
- [Request replay](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/ReplayService.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/ReplayService.java`
- [API error handling](https://github.com/rjaycarl/torrestrace/blob/master/torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/exception/GlobalExceptionHandler.java): `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/exception/GlobalExceptionHandler.java`

### Other components

- **Consumer API**
- **Replay destination**

## Connections

- Consumer API → Request wrapper: sends request (evidence: `README.md`)
- Request wrapper → Trace interceptor: captures exchange (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java`)
- Trace interceptor → Trace service: records trace
- Selective tracing → Trace interceptor: selects handlers (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java`)
- Trace settings → Selective tracing: controls selection
- Trace interceptor → Sensitive-data redactor: redacts data (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/interceptor/TraceInterceptor.java`)
- Trace service → Storage contract: persists and queries (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java`)
- Storage contract → JPA storage: implemented by (evidence: `README.md`)
- Storage contract → JSON file storage: implemented by (evidence: `README.md`)
- Storage contract → Directory storage: implemented by (evidence: `README.md`)
- Storage contract → No-op storage: implemented by (evidence: `README.md`)
- Trace service → Trace record: serializes trace (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/TraceService.java`)
- Trace API → Trace service: lists and finds (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java`)
- Trace API → Response mapper: maps responses (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java`)
- Trace API → Request replay: requests replay (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceController.java`)
- Admin API → Trace service: filters and manages (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java`)
- Admin API → Trace inspection: requests statistics (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java`)
- Admin API → Request replay: requests replay (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/controller/TorresTraceAdminController.java`)
- Trace inspection → Storage contract: queries traces (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/InspectionService.java`)
- Trace inspection → Response mapper: maps traces (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/service/InspectionService.java`)
- Request replay → Replay destination: sends replay
- Trace API → API error handling: handled failures (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/exception/GlobalExceptionHandler.java`)
- Admin API → API error handling: handled failures (evidence: `torres-trace-core/src/main/java/dev/masanting/rjaycarl/torrestrace/exception/GlobalExceptionHandler.java`)