# shashi999kant/ai-rca-platform architecture

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

- Interactive diagram: https://gitdiagram.com/shashi999kant/ai-rca-platform
- Repository: https://github.com/shashi999kant/ai-rca-platform

## Overview

This is a Spring Boot incident RCA engine. Telemetry is parsed, deduplicated and grouped before new incidents are queued for asynchronous analysis; workers combine service-call paths and verified incident history, ask Gemini for structured findings, and persist reports. Engineers can retrieve reports, verify them to seed future retrieval, and inspect grouping statistics. The graph and vector integrations are explicit in the README and orchestrator excerpt; the REST, DLT, and startup capabilities are documented, though some implementation details were not sampled.

Main entry points: [`src/main/java/com/shashi/rca/service/IncidentAnalysisService.java`](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/IncidentAnalysisService.java) (Analysis worker), [`src/main/java/com/shashi/rca/repository`](https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/repository) (Incident and report repositories), [`src/main/java/com/shashi/rca/service/TelemetryIngestionService.java`](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/TelemetryIngestionService.java) (Telemetry ingestion), [`src/main/java/com/shashi/rca/service/RcaOrchestratorService.java`](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/RcaOrchestratorService.java) (RCA orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_raw_topic["Raw Kafka topic"]
  node_ingestion["Telemetry ingestion"]
  node_signature["Error signature"]
end

subgraph group_analysis["RCA analysis"]
  node_analysis_topic["Analysis topic"]
  node_worker["Analysis worker"]
  node_orchestrator["RCA orchestrator"]
  node_llm_client["Gemini client<br/>[LlmClient.java]"]
  node_dto["RCA and API DTOs"]
  node_dlt_topic["Analysis dead-letter topic"]
  node_dlt_listener["Dead-letter listener"]
end

subgraph group_knowledge["Knowledge context"]
  node_graph[("Service dependency graph")]
  node_vector[("Verified incident vectors")]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL incident and report data")]
  node_repositories["Incident and report repositories"]
  node_domain_models["Incident and report models"]
end

subgraph group_api["Reports and API"]
  node_api["Incident and report REST API"]
  node_report_service["Report service<br/>[ReportService.java]"]
  node_stats["Grouping statistics<br/>[StatsResponse.java]"]
end

node_producer(("Telemetry producer"))
node_gemini["Google Gemini"]
node_human(("On-call engineer"))

node_producer -->|"publishes telemetry"| node_raw_topic
node_raw_topic -->|"delivers events"| node_ingestion
node_ingestion -->|"normalizes errors"| node_signature
node_ingestion -->|"deduplicates and stores"| node_repositories
node_ingestion -->|"queues incident ID"| node_analysis_topic
node_analysis_topic -->|"delivers requests"| node_worker
node_worker -->|"claims and saves incident"| node_repositories
node_worker -->|"runs analysis"| node_orchestrator
node_orchestrator -->|"queries call paths"| node_graph
node_orchestrator -->|"searches similar verified reports"| node_vector
node_orchestrator -->|"supplies RCA context"| node_llm_client
node_llm_client -->|"requests structured analysis"| node_gemini
node_worker -->|"consumes RCA report"| node_dto
node_repositories -->|"reads and writes"| node_postgres
node_worker -->|"routes exhausted retries"| node_dlt_topic
node_dlt_topic -->|"delivers failed requests"| node_dlt_listener
node_dlt_listener -->|"marks incidents failed"| node_repositories
node_human -->|"requests reports or verifies"| node_api
node_api -->|"delegates report operations"| node_report_service
node_report_service -->|"loads reports and counts"| node_repositories
node_report_service -->|"adds verified report"| node_vector
node_api -->|"returns statistics"| node_stats

click node_ingestion "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/TelemetryIngestionService.java"
click node_signature "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/ErrorSignature.java"
click node_worker "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/IncidentAnalysisService.java"
click node_orchestrator "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/RcaOrchestratorService.java"
click node_llm_client "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/LlmClient.java"
click node_repositories "https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/repository"
click node_domain_models "https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/model"
click node_dto "https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/dto"
click node_dlt_listener "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/DeadLetterListener.java"
click node_api "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/controller/IncidentController.java"
click node_report_service "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/ReportService.java"
click node_stats "https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/dto/StatsResponse.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_raw_topic,node_ingestion,node_signature toneBlue
class node_analysis_topic,node_worker,node_orchestrator,node_llm_client,node_dto,node_dlt_topic,node_dlt_listener toneAmber
class node_graph,node_vector toneMint
class node_postgres,node_repositories,node_domain_models toneRose
class node_api,node_report_service,node_stats,node_producer,node_gemini,node_human toneIndigo
```

## Components

### Ingestion

- **Raw Kafka topic**
- [Telemetry ingestion](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/TelemetryIngestionService.java): `src/main/java/com/shashi/rca/service/TelemetryIngestionService.java`
- [Error signature](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/ErrorSignature.java): `src/main/java/com/shashi/rca/service/ErrorSignature.java`

### RCA analysis

- **Analysis topic**
- [Analysis worker](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/IncidentAnalysisService.java): `src/main/java/com/shashi/rca/service/IncidentAnalysisService.java`
- [RCA orchestrator](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/RcaOrchestratorService.java): `src/main/java/com/shashi/rca/service/RcaOrchestratorService.java`
- [Gemini client](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/LlmClient.java): `src/main/java/com/shashi/rca/service/LlmClient.java`
- [RCA and API DTOs](https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/dto): `src/main/java/com/shashi/rca/dto`
- **Analysis dead-letter topic**
- [Dead-letter listener](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/DeadLetterListener.java): `src/main/java/com/shashi/rca/service/DeadLetterListener.java`

### Knowledge context

- **Service dependency graph**
- **Verified incident vectors**

### Persistence

- **PostgreSQL incident and report data**
- [Incident and report repositories](https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/repository): `src/main/java/com/shashi/rca/repository`
- [Incident and report models](https://github.com/shashi999kant/ai-rca-platform/tree/main/src/main/java/com/shashi/rca/model): `src/main/java/com/shashi/rca/model`

### Reports and API

- [Incident and report REST API](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/controller/IncidentController.java): `src/main/java/com/shashi/rca/controller/IncidentController.java`
- [Report service](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/service/ReportService.java): `src/main/java/com/shashi/rca/service/ReportService.java`
- [Grouping statistics](https://github.com/shashi999kant/ai-rca-platform/blob/main/src/main/java/com/shashi/rca/dto/StatsResponse.java): `src/main/java/com/shashi/rca/dto/StatsResponse.java`

### Other components

- **Telemetry producer**
- **Google Gemini**
- **On-call engineer**

## Connections

- Telemetry producer → Raw Kafka topic: publishes telemetry (evidence: `README.md`)
- Raw Kafka topic → Telemetry ingestion: delivers events (evidence: `README.md`)
- Telemetry ingestion → Error signature: normalizes errors (evidence: `src/main/java/com/shashi/rca/service/TelemetryIngestionService.java`)
- Telemetry ingestion → Incident and report repositories: deduplicates and stores (evidence: `src/main/java/com/shashi/rca/service/TelemetryIngestionService.java`)
- Telemetry ingestion → Analysis topic: queues incident ID (evidence: `src/main/java/com/shashi/rca/service/TelemetryIngestionService.java`)
- Analysis topic → Analysis worker: delivers requests (evidence: `README.md`)
- Analysis worker → Incident and report repositories: claims and saves incident (evidence: `src/main/java/com/shashi/rca/service/IncidentAnalysisService.java`)
- Analysis worker → RCA orchestrator: runs analysis (evidence: `src/main/java/com/shashi/rca/service/IncidentAnalysisService.java`)
- RCA orchestrator → Service dependency graph: queries call paths (evidence: `src/main/java/com/shashi/rca/service/RcaOrchestratorService.java`)
- RCA orchestrator → Verified incident vectors: searches similar verified reports (evidence: `src/main/java/com/shashi/rca/service/RcaOrchestratorService.java`)
- RCA orchestrator → Gemini client: supplies RCA context (evidence: `src/main/java/com/shashi/rca/service/RcaOrchestratorService.java`)
- Gemini client → Google Gemini: requests structured analysis (evidence: `README.md`)
- Analysis worker → RCA and API DTOs: consumes RCA report (evidence: `src/main/java/com/shashi/rca/service/IncidentAnalysisService.java`)
- Incident and report repositories → PostgreSQL incident and report data: reads and writes (evidence: `README.md`)
- Analysis worker → Analysis dead-letter topic: routes exhausted retries (evidence: `README.md`)
- Analysis dead-letter topic → Dead-letter listener: delivers failed requests (evidence: `README.md`)
- Dead-letter listener → Incident and report repositories: marks incidents failed (evidence: `src/main/java/com/shashi/rca/service/DeadLetterListener.java`)
- On-call engineer → Incident and report REST API: requests reports or verifies (evidence: `README.md`)
- Incident and report REST API → Report service: delegates report operations (evidence: `src/main/java/com/shashi/rca/controller/IncidentController.java`)
- Report service → Incident and report repositories: loads reports and counts (evidence: `src/main/java/com/shashi/rca/service/ReportService.java`)
- Report service → Verified incident vectors: adds verified report (evidence: `src/main/java/com/shashi/rca/service/ReportService.java`)
- Incident and report REST API → Grouping statistics: returns statistics (evidence: `README.md`)
