# vaibhav-zemo/ai-rca-platform architecture

> Architecture diagram of the GitHub repository vaibhav-zemo/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/vaibhav-zemo/ai-rca-platform
- Repository: https://github.com/vaibhav-zemo/ai-rca-platform

## Overview

This is a Spring Boot platform for turning streamed microservice telemetry into structured root-cause reports. Its main workflow consumes Kafka events, filters and deduplicates incidents, enriches analysis with Neo4j topology and pgvector history, requests structured Gemini output, persists the incident and report, and feeds the outcome back to vector search. The README documents these capabilities; the graph initializer and principal workflow are excerpted, while wiring for some infrastructure relies on README statements and configuration.

Main entry points: [`src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java) (Telemetry ingestion), [`src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java`](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java) (RCA orchestrator), [`src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java`](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java) (Persisted RCA report), [`src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java`](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java) (Pipeline check API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry intake"]
  node_ingestion["Telemetry ingestion"]
  node_telemetry["Telemetry message"]
  node_boot_controller["Pipeline check API"]
  node_application["Spring Boot application"]
end

subgraph group_analysis["RCA analysis"]
  node_orchestrator["RCA orchestrator"]
  node_report_dto["Structured RCA report<br/>[RcaReport.java]"]
  node_vector_store[("Vector history")]
end

subgraph group_topology["Service topology"]
  node_service_node["Service graph node<br/>[ServiceNode.java]"]
  node_graph_repo["Service graph repository"]
  node_graph_initializer["Topology seeder"]
end

subgraph group_persistence["Incident records"]
  node_incident["Incident record<br/>[Incident.java]"]
  node_incident_repo["Incident repository"]
  node_report_entity["Persisted RCA report"]
  node_report_repo["Report repository"]
end

subgraph group_integration["AI and stores"]
  node_kafka["Kafka topic"]
  node_postgres[("PostgreSQL pgvector")]
  node_neo4j[("Neo4j topology")]
  node_gemini{{"Gemini model"}}
end

node_producer(("Telemetry producer"))

node_producer -->|"publishes telemetry"| node_kafka
node_kafka -->|"delivers events"| node_ingestion
node_ingestion -->|"parses payload"| node_telemetry
node_ingestion -->|"checks and saves"| node_incident_repo
node_incident_repo -->|"stores incident"| node_incident
node_ingestion -->|"requests analysis"| node_orchestrator
node_orchestrator -->|"queries dependencies"| node_neo4j
node_orchestrator -->|"searches history"| node_vector_store
node_orchestrator -->|"requests diagnosis"| node_gemini
node_orchestrator -->|"returns structured result"| node_report_dto
node_ingestion -->|"builds report record"| node_report_entity
node_ingestion -->|"saves report"| node_report_repo
node_report_repo -->|"stores report"| node_report_entity
node_report_entity -->|"references incident"| node_incident
node_ingestion -->|"adds learned outcome"| node_vector_store
node_vector_store -->|"persists vectors"| node_postgres
node_graph_initializer -->|"seeds topology"| node_neo4j
node_service_node -.->|"models service graph"| node_neo4j
node_graph_repo -.->|"accesses graph"| node_neo4j
node_boot_controller -->|"checks vector storage"| node_vector_store
node_boot_controller -->|"checks model call"| node_gemini

click node_ingestion "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java"
click node_telemetry "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/dto/TelemetryMessage.java"
click node_incident "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/Incident.java"
click node_incident_repo "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/IncidentRepository.java"
click node_orchestrator "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java"
click node_report_dto "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/dto/RcaReport.java"
click node_report_entity "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java"
click node_report_repo "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/RcaReportRepository.java"
click node_service_node "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/graph/ServiceNode.java"
click node_graph_repo "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/graph/ServiceGraphRepository.java"
click node_graph_initializer "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/config/GraphDataInitializer.java"
click node_boot_controller "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java"
click node_application "https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/AiRcaPlatformApplication.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_ingestion,node_telemetry,node_boot_controller,node_application toneBlue
class node_orchestrator,node_report_dto,node_vector_store toneAmber
class node_service_node,node_graph_repo,node_graph_initializer toneMint
class node_incident,node_incident_repo,node_report_entity,node_report_repo toneRose
class node_kafka,node_postgres,node_neo4j,node_gemini,node_producer toneIndigo
```

## Components

### Telemetry intake

- [Telemetry ingestion](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java): `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`
- [Telemetry message](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/dto/TelemetryMessage.java): `src/main/java/org/vaibhav/aircaplatform/dto/TelemetryMessage.java`
- [Pipeline check API](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java): `src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java`
- [Spring Boot application](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/AiRcaPlatformApplication.java): `src/main/java/org/vaibhav/aircaplatform/AiRcaPlatformApplication.java`

### RCA analysis

- [RCA orchestrator](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java): `src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java`
- [Structured RCA report](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/dto/RcaReport.java): `src/main/java/org/vaibhav/aircaplatform/dto/RcaReport.java`
- **Vector history**

### Service topology

- [Service graph node](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/graph/ServiceNode.java): `src/main/java/org/vaibhav/aircaplatform/model/graph/ServiceNode.java`
- [Service graph repository](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/graph/ServiceGraphRepository.java): `src/main/java/org/vaibhav/aircaplatform/repository/graph/ServiceGraphRepository.java`
- [Topology seeder](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/config/GraphDataInitializer.java): `src/main/java/org/vaibhav/aircaplatform/config/GraphDataInitializer.java`

### Incident records

- [Incident record](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/Incident.java): `src/main/java/org/vaibhav/aircaplatform/model/Incident.java`
- [Incident repository](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/IncidentRepository.java): `src/main/java/org/vaibhav/aircaplatform/repository/IncidentRepository.java`
- [Persisted RCA report](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java): `src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java`
- [Report repository](https://github.com/vaibhav-zemo/ai-rca-platform/blob/main/src/main/java/org/vaibhav/aircaplatform/repository/RcaReportRepository.java): `src/main/java/org/vaibhav/aircaplatform/repository/RcaReportRepository.java`

### AI and stores

- **Kafka topic**
- **PostgreSQL pgvector**
- **Neo4j topology**
- **Gemini model**

### Other components

- **Telemetry producer**

## Connections

- Telemetry producer → Kafka topic: publishes telemetry (evidence: `README.md`)
- Kafka topic → Telemetry ingestion: delivers events (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Telemetry ingestion → Telemetry message: parses payload (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Telemetry ingestion → Incident repository: checks and saves (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Incident repository → Incident record: stores incident (evidence: `src/main/java/org/vaibhav/aircaplatform/repository/IncidentRepository.java`)
- Telemetry ingestion → RCA orchestrator: requests analysis (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- RCA orchestrator → Neo4j topology: queries dependencies (evidence: `src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java`)
- RCA orchestrator → Vector history: searches history (evidence: `src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java`)
- RCA orchestrator → Gemini model: requests diagnosis (evidence: `README.md`)
- RCA orchestrator → Structured RCA report: returns structured result (evidence: `src/main/java/org/vaibhav/aircaplatform/service/RcaOrchestratorService.java`)
- Telemetry ingestion → Persisted RCA report: builds report record (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Telemetry ingestion → Report repository: saves report (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Report repository → Persisted RCA report: stores report (evidence: `src/main/java/org/vaibhav/aircaplatform/repository/RcaReportRepository.java`)
- Persisted RCA report → Incident record: references incident (evidence: `src/main/java/org/vaibhav/aircaplatform/model/RcaReportEntity.java`)
- Telemetry ingestion → Vector history: adds learned outcome (evidence: `src/main/java/org/vaibhav/aircaplatform/service/TelemetryIngestionService.java`)
- Vector history → PostgreSQL pgvector: persists vectors (evidence: `README.md`)
- Topology seeder → Neo4j topology: seeds topology (evidence: `src/main/java/org/vaibhav/aircaplatform/config/GraphDataInitializer.java`)
- Service graph node → Neo4j topology: models service graph
- Service graph repository → Neo4j topology: accesses graph
- Pipeline check API → Vector history: checks vector storage (evidence: `src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java`)
- Pipeline check API → Gemini model: checks model call (evidence: `src/main/java/org/vaibhav/aircaplatform/controller/RcaBootController.java`)
