# dakshrjain737/ai-agent-observatory-backend architecture

> Architecture diagram of the GitHub repository dakshrjain737/ai-agent-observatory-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dakshrjain737/ai-agent-observatory-backend
- Repository: https://github.com/dakshrjain737/ai-agent-observatory-backend

## Overview

AI Agent Observatory is a secured Spring REST backend for collecting agent traces and spans, grouping them into sessions, and querying telemetry. The main workflow routes SDK ingestion through API-key security and controllers into trace/span services, which resolve session and parent/child relationships and persist through JPA repositories; human users register and access protected APIs with JWT authentication. The README also documents analytics, but its implementation was not sampled, so its wiring is left unspecified.

Main entry points: [`src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java`](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java) (Span service), [`src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java`](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java) (Trace service), [`src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java`](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java) (Trace repository), [`src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java`](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java) (Session repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_security["Security"]
  node_api_key_filter["API-key filter"]
  node_jwt_filters["JWT filters"]
  node_security_config["Security config"]
end

subgraph group_api["REST API"]
  node_trace_controller["Trace API"]
  node_span_controller["Span API"]
  node_user_controller["User API"]
  node_analytics_controller["Analytics API"]
end

subgraph group_telemetry["Telemetry Services"]
  node_trace_service["Trace service"]
  node_span_service["Span service"]
  node_user_service["User service"]
  node_analytics_service["Analytics service"]
  node_trace_mapper["Trace mapping"]
  node_span_mapper["Span mapping"]
  node_analytics_dto["Analytics DTOs"]
end

subgraph group_persistence["Persistence"]
  node_trace_repo["Trace repository"]
  node_span_repo["Span repository"]
  node_session_repo["Session repository"]
  node_user_repo["User repository"]
  node_telemetry_entities["Telemetry entities<br/>[Trace.java]"]
  node_user_entity["User and roles<br/>[User.java]"]
end

node_sdk(("Agent SDK"))
node_human(("Human user"))
node_database[("PostgreSQL / H2")]

node_sdk -->|"sends credentials"| node_api_key_filter
node_api_key_filter -->|"authenticates"| node_security_config
node_human -->|"sends credentials"| node_jwt_filters
node_jwt_filters -->|"validates tokens"| node_security_config
node_sdk -->|"submits traces"| node_trace_controller
node_sdk -->|"submits spans"| node_span_controller
node_human -->|"registers users"| node_user_controller
node_trace_controller -->|"delegates requests"| node_trace_service
node_span_controller -->|"delegates requests"| node_span_service
node_user_controller -->|"delegates requests"| node_user_service
node_analytics_controller -->|"requests metrics"| node_analytics_service
node_trace_service -->|"reads and writes"| node_trace_repo
node_trace_service -->|"resolves sessions"| node_session_repo
node_trace_service -->|"maps traces"| node_trace_mapper
node_span_service -->|"resolves traces"| node_trace_repo
node_span_service -->|"resolves sessions"| node_session_repo
node_span_service -->|"reads spans"| node_span_repo
node_span_service -->|"maps spans"| node_span_mapper
node_user_service -->|"reads and writes"| node_user_repo
node_trace_repo -->|"persists telemetry"| node_database
node_span_repo -->|"persists spans"| node_database
node_session_repo -->|"persists sessions"| node_database
node_user_repo -->|"persists accounts"| node_database
node_trace_repo -->|"stores"| node_telemetry_entities
node_span_repo -->|"stores"| node_telemetry_entities
node_session_repo -->|"stores"| node_telemetry_entities
node_user_repo -->|"stores"| node_user_entity
node_analytics_service -.->|"produces metrics"| node_analytics_dto

click node_api_key_filter "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/auth/filter/ApiKeyHashAuthenticationFilter.java"
click node_jwt_filters "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/auth/filter/JWTAuthenticationFilter.java"
click node_security_config "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/config/SecurityConfig.java"
click node_trace_controller "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/TraceController.java"
click node_span_controller "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/SpanController.java"
click node_user_controller "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/UserController.java"
click node_analytics_controller "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/AnalyticsController.java"
click node_trace_service "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java"
click node_span_service "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java"
click node_user_service "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/UserServiceImpl.java"
click node_analytics_service "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/AnalyticServiceImpl.java"
click node_trace_mapper "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/mappers/TraceMapperImpl.java"
click node_span_mapper "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/mappers/SpanMapperImpl.java"
click node_trace_repo "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java"
click node_span_repo "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/SpanRepository.java"
click node_session_repo "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java"
click node_user_repo "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/UserRepository.java"
click node_telemetry_entities "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/entities/entity/Trace.java"
click node_user_entity "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/entities/entity/User.java"
click node_analytics_dto "https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/dto/entityDto/TraceAnalyticsDto.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_api_key_filter,node_jwt_filters,node_security_config,node_human toneBlue
class node_trace_controller,node_span_controller,node_user_controller,node_analytics_controller,node_database toneAmber
class node_trace_service,node_span_service,node_user_service,node_analytics_service,node_trace_mapper,node_span_mapper,node_analytics_dto toneMint
class node_trace_repo,node_span_repo,node_session_repo,node_user_repo,node_telemetry_entities,node_user_entity toneRose
class node_sdk toneIndigo
```

## Components

### Security

- [API-key filter](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/auth/filter/ApiKeyHashAuthenticationFilter.java): `src/main/java/com/backend_agent_obs/agent/auth/filter/ApiKeyHashAuthenticationFilter.java`
- [JWT filters](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/auth/filter/JWTAuthenticationFilter.java): `src/main/java/com/backend_agent_obs/agent/auth/filter/JWTAuthenticationFilter.java`
- [Security config](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/config/SecurityConfig.java): `src/main/java/com/backend_agent_obs/agent/config/SecurityConfig.java`

### REST API

- [Trace API](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/TraceController.java): `src/main/java/com/backend_agent_obs/agent/controller/TraceController.java`
- [Span API](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/SpanController.java): `src/main/java/com/backend_agent_obs/agent/controller/SpanController.java`
- [User API](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/UserController.java): `src/main/java/com/backend_agent_obs/agent/controller/UserController.java`
- [Analytics API](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/controller/AnalyticsController.java): `src/main/java/com/backend_agent_obs/agent/controller/AnalyticsController.java`

### Telemetry Services

- [Trace service](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java): `src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java`
- [Span service](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java): `src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java`
- [User service](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/UserServiceImpl.java): `src/main/java/com/backend_agent_obs/agent/services/serviceImpl/UserServiceImpl.java`
- [Analytics service](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/services/serviceImpl/AnalyticServiceImpl.java): `src/main/java/com/backend_agent_obs/agent/services/serviceImpl/AnalyticServiceImpl.java`
- [Trace mapping](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/mappers/TraceMapperImpl.java): `src/main/java/com/backend_agent_obs/agent/mappers/TraceMapperImpl.java`
- [Span mapping](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/mappers/SpanMapperImpl.java): `src/main/java/com/backend_agent_obs/agent/mappers/SpanMapperImpl.java`
- [Analytics DTOs](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/dto/entityDto/TraceAnalyticsDto.java): `src/main/java/com/backend_agent_obs/agent/dto/entityDto/TraceAnalyticsDto.java`

### Persistence

- [Trace repository](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java): `src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java`
- [Span repository](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/SpanRepository.java): `src/main/java/com/backend_agent_obs/agent/repo/SpanRepository.java`
- [Session repository](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java): `src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java`
- [User repository](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/repo/UserRepository.java): `src/main/java/com/backend_agent_obs/agent/repo/UserRepository.java`
- [Telemetry entities](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/entities/entity/Trace.java): `src/main/java/com/backend_agent_obs/agent/entities/entity/Trace.java`
- [User and roles](https://github.com/dakshrjain737/ai-agent-observatory-backend/blob/main/src/main/java/com/backend_agent_obs/agent/entities/entity/User.java): `src/main/java/com/backend_agent_obs/agent/entities/entity/User.java`

### Other components

- **Agent SDK**
- **Human user**
- **PostgreSQL / H2**

## Connections

- Agent SDK → API-key filter: sends credentials
- API-key filter → Security config: authenticates
- Human user → JWT filters: sends credentials
- JWT filters → Security config: validates tokens
- Agent SDK → Trace API: submits traces
- Agent SDK → Span API: submits spans
- Human user → User API: registers users
- Trace API → Trace service: delegates requests
- Span API → Span service: delegates requests
- User API → User service: delegates requests
- Analytics API → Analytics service: requests metrics
- Trace service → Trace repository: reads and writes
- Trace service → Session repository: resolves sessions
- Trace service → Trace mapping: maps traces
- Span service → Trace repository: resolves traces
- Span service → Session repository: resolves sessions
- Span service → Span repository: reads spans
- Span service → Span mapping: maps spans
- User service → User repository: reads and writes
- Trace repository → PostgreSQL / H2: persists telemetry
- Span repository → PostgreSQL / H2: persists spans
- Session repository → PostgreSQL / H2: persists sessions
- User repository → PostgreSQL / H2: persists accounts
- Trace repository → Telemetry entities: stores
- Span repository → Telemetry entities: stores
- Session repository → Telemetry entities: stores
- User repository → User and roles: stores
- Analytics service → Analytics DTOs: produces metrics