# oneteme/inspect-server architecture

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

- Interactive diagram: https://gitdiagram.com/oneteme/inspect-server
- Repository: https://github.com/oneteme/inspect-server
- Video tour (about a minute): https://gitdiagram.com/oneteme/inspect-server/video

## Overview

INSPECT Server accepts collected traces and session/request data, buffers and dispatches trace batches for persistence, then exposes stored telemetry through request, comparison, cache, and administration APIs. It also supports scheduled partitioning and retention purging. The graph reflects documented capabilities and source-index references; several service and controller implementations were not excerpted, so uncertain links are omitted.

Main entry points: [`src/main/java/org/usf/inspect/server/service/RequestService.java`](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/RequestService.java) (Request service), [`src/main/java/org/usf/inspect/server/service/TraceService.java`](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TraceService.java) (Trace service), [`src/main/java/org/usf/inspect/server/erm/InspectStore.java`](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/erm/InspectStore.java) (Store catalogs), [`src/main/java/org/usf/inspect/server/service/CompareService.java`](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/CompareService.java) (Compare service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Trace ingestion"]
  node_traceapi["Trace endpoints"]
  node_tracev4["Trace v4"]
  node_tracesvc["Trace service<br/>[TraceService.java]"]
  node_dispatch["Batch dispatcher"]
  node_persister["Trace persister"]
  node_tracebatch["Trace batches<br/>[TraceBatch.java]"]
end

subgraph group_query["Telemetry queries"]
  node_requestapi["Request endpoints"]
  node_requestsvc["Request service"]
  node_compareapi["Compare endpoint"]
  node_comparesvc["Compare service"]
  node_cacheapi["Cache controls"]
end

subgraph group_store["Persistence model"]
  node_restrequest["REST requests<br/>[RestRequest.java]"]
  node_restsession["REST sessions<br/>[RestSession.java]"]
  node_mainsession["Main sessions<br/>[MainSession.java]"]
  node_ftpmodel["FTP requests<br/>[FtpRequest.java]"]
  node_localmodel["Local requests<br/>[LocalRequest.java]"]
  node_wrappers["Session wrappers"]
  node_mapper["Row mappers<br/>[Mappers.java]"]
  node_storecatalog[("Store catalogs<br/>[InspectStore.java]")]
end

subgraph group_ops["Operations"]
  node_admin["Admin service<br/>[AdminService.java]"]
  node_admindao["Admin DAO<br/>[AdminDao.java]"]
  node_purge["Purge service<br/>[PurgeService.java]"]
  node_purgedao["Purge DAO<br/>[PurgeDao.java]"]
  node_partition["Partition scheduler"]
  node_scriptsvc["Script service<br/>[ScriptService.java]"]
end

node_collector(("Collectors"))

node_collector -->|"submits traces"| node_traceapi
node_traceapi -->|"dispatches traces"| node_tracesvc
node_tracev4 -->|"delegates to"| node_traceapi
node_tracesvc -->|"enqueues batches"| node_dispatch
node_tracesvc -->|"creates batches"| node_tracebatch
node_requestapi -->|"queries through"| node_requestsvc
node_compareapi -->|"compares via"| node_comparesvc
node_comparesvc -->|"queries catalogs"| node_storecatalog
node_requestsvc -->|"queries catalogs"| node_storecatalog
node_requestsvc -->|"maps results"| node_mapper
node_comparesvc -->|"uses mappings"| node_mapper
node_requestsvc -->|"assembles sessions"| node_wrappers
node_wrappers -->|"wraps session"| node_restsession
node_requestsvc -->|"loads requests"| node_restrequest
node_requestsvc -->|"loads sessions"| node_mainsession
node_requestsvc -->|"loads requests"| node_ftpmodel
node_requestsvc -->|"loads requests"| node_localmodel
node_cacheapi -->|"controls cache"| node_persister
node_admin -->|"uses DAO"| node_admindao
node_purge -->|"purges through"| node_purgedao
node_scriptsvc -->|"uses trace service"| node_tracesvc
node_partition -.->|"partitions store"| node_storecatalog
node_purge -.->|"deletes expired data"| node_storecatalog

click node_traceapi "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/TraceController.java"
click node_tracev4 "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/TraceV4Controller.java"
click node_tracesvc "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TraceService.java"
click node_dispatch "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TraceBatchDispatcherHub.java"
click node_persister "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TracePersister.java"
click node_tracebatch "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/TraceBatch.java"
click node_requestapi "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/RequestController.java"
click node_requestsvc "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/RequestService.java"
click node_compareapi "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/CompareController.java"
click node_comparesvc "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/CompareService.java"
click node_cacheapi "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/CacheController.java"
click node_restrequest "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/RestRequest.java"
click node_restsession "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/RestSession.java"
click node_mainsession "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/MainSession.java"
click node_ftpmodel "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/FtpRequest.java"
click node_localmodel "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/LocalRequest.java"
click node_wrappers "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/wrapper/RestSessionWrapper.java"
click node_mapper "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/mapper/Mappers.java"
click node_storecatalog "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/erm/InspectStore.java"
click node_admin "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/AdminService.java"
click node_admindao "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/dao/AdminDao.java"
click node_purge "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/PurgeService.java"
click node_purgedao "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/dao/PurgeDao.java"
click node_partition "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/PartitionScheduler.java"
click node_scriptsvc "https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/ScriptService.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_traceapi,node_tracev4,node_tracesvc,node_dispatch,node_persister,node_tracebatch toneBlue
class node_requestapi,node_requestsvc,node_compareapi,node_comparesvc,node_cacheapi toneAmber
class node_restrequest,node_restsession,node_mainsession,node_ftpmodel,node_localmodel,node_wrappers,node_mapper,node_storecatalog toneMint
class node_admin,node_admindao,node_purge,node_purgedao,node_partition,node_scriptsvc toneRose
class node_collector toneIndigo
```

## Components

### Trace ingestion

- [Trace endpoints](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/TraceController.java): `src/main/java/org/usf/inspect/server/controller/TraceController.java`
- [Trace v4](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/TraceV4Controller.java): `src/main/java/org/usf/inspect/server/controller/TraceV4Controller.java`
- [Trace service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TraceService.java): `src/main/java/org/usf/inspect/server/service/TraceService.java`
- [Batch dispatcher](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TraceBatchDispatcherHub.java): `src/main/java/org/usf/inspect/server/service/TraceBatchDispatcherHub.java`
- [Trace persister](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/TracePersister.java): `src/main/java/org/usf/inspect/server/service/TracePersister.java`
- [Trace batches](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/TraceBatch.java): `src/main/java/org/usf/inspect/server/model/TraceBatch.java`

### Telemetry queries

- [Request endpoints](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/RequestController.java): `src/main/java/org/usf/inspect/server/controller/RequestController.java`
- [Request service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/RequestService.java): `src/main/java/org/usf/inspect/server/service/RequestService.java`
- [Compare endpoint](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/CompareController.java): `src/main/java/org/usf/inspect/server/controller/CompareController.java`
- [Compare service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/CompareService.java): `src/main/java/org/usf/inspect/server/service/CompareService.java`
- [Cache controls](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/controller/CacheController.java): `src/main/java/org/usf/inspect/server/controller/CacheController.java`

### Persistence model

- [REST requests](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/RestRequest.java): `src/main/java/org/usf/inspect/server/model/RestRequest.java`
- [REST sessions](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/RestSession.java): `src/main/java/org/usf/inspect/server/model/RestSession.java`
- [Main sessions](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/MainSession.java): `src/main/java/org/usf/inspect/server/model/MainSession.java`
- [FTP requests](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/FtpRequest.java): `src/main/java/org/usf/inspect/server/model/FtpRequest.java`
- [Local requests](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/LocalRequest.java): `src/main/java/org/usf/inspect/server/model/LocalRequest.java`
- [Session wrappers](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/model/wrapper/RestSessionWrapper.java): `src/main/java/org/usf/inspect/server/model/wrapper/RestSessionWrapper.java`
- [Row mappers](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/mapper/Mappers.java): `src/main/java/org/usf/inspect/server/mapper/Mappers.java`
- [Store catalogs](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/erm/InspectStore.java): `src/main/java/org/usf/inspect/server/erm/InspectStore.java`

### Operations

- [Admin service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/AdminService.java): `src/main/java/org/usf/inspect/server/service/AdminService.java`
- [Admin DAO](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/dao/AdminDao.java): `src/main/java/org/usf/inspect/server/dao/AdminDao.java`
- [Purge service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/PurgeService.java): `src/main/java/org/usf/inspect/server/service/PurgeService.java`
- [Purge DAO](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/dao/PurgeDao.java): `src/main/java/org/usf/inspect/server/dao/PurgeDao.java`
- [Partition scheduler](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/PartitionScheduler.java): `src/main/java/org/usf/inspect/server/PartitionScheduler.java`
- [Script service](https://github.com/oneteme/inspect-server/blob/main/src/main/java/org/usf/inspect/server/service/ScriptService.java): `src/main/java/org/usf/inspect/server/service/ScriptService.java`

### Other components

- **Collectors**

## Connections

- Collectors → Trace endpoints: submits traces
- Trace endpoints → Trace service: dispatches traces (evidence: `src/main/java/org/usf/inspect/server/controller/TraceController.java`)
- Trace v4 → Trace endpoints: delegates to (evidence: `src/main/java/org/usf/inspect/server/controller/TraceV4Controller.java`)
- Trace service → Batch dispatcher: enqueues batches (evidence: `src/main/java/org/usf/inspect/server/service/TraceService.java`)
- Trace service → Trace batches: creates batches (evidence: `src/main/java/org/usf/inspect/server/service/TraceService.java`)
- Request endpoints → Request service: queries through (evidence: `src/main/java/org/usf/inspect/server/controller/RequestController.java`)
- Compare endpoint → Compare service: compares via (evidence: `src/main/java/org/usf/inspect/server/controller/CompareController.java`)
- Compare service → Store catalogs: queries catalogs (evidence: `src/main/java/org/usf/inspect/server/service/CompareService.java`)
- Request service → Store catalogs: queries catalogs (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Request service → Row mappers: maps results (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Compare service → Row mappers: uses mappings (evidence: `src/main/java/org/usf/inspect/server/service/CompareService.java`)
- Request service → Session wrappers: assembles sessions (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Session wrappers → REST sessions: wraps session (evidence: `src/main/java/org/usf/inspect/server/model/wrapper/RestSessionWrapper.java`)
- Request service → REST requests: loads requests (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Request service → Main sessions: loads sessions (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Request service → FTP requests: loads requests (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Request service → Local requests: loads requests (evidence: `src/main/java/org/usf/inspect/server/service/RequestService.java`)
- Cache controls → Trace persister: controls cache (evidence: `src/main/java/org/usf/inspect/server/controller/CacheController.java`)
- Admin service → Admin DAO: uses DAO (evidence: `src/main/java/org/usf/inspect/server/service/AdminService.java`)
- Purge service → Purge DAO: purges through (evidence: `src/main/java/org/usf/inspect/server/service/PurgeService.java`)
- Script service → Trace service: uses trace service (evidence: `src/main/java/org/usf/inspect/server/service/ScriptService.java`)
- Partition scheduler → Store catalogs: partitions store
- Purge service → Store catalogs: deletes expired data
