# dpkb-dev/springai-med-qa architecture

> Architecture diagram of the GitHub repository dpkb-dev/springai-med-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dpkb-dev/springai-med-qa
- Repository: https://github.com/dpkb-dev/springai-med-qa

## Overview

This is a Spring Boot medical consultation and claims-assessment backend. Its primary workflow accepts a patient chat request, builds session-aware context, streams an LLM response with scoped medical RAG, and retains conversation memory; REST endpoints also manage sessions and RAG documents. Separate claims workflows assess policy clauses and consistency, and evaluate underwriting eligibility. The graph preserves these documented capabilities and the shared security, persistence, audit, and rate-limit layers. Arrows are limited to relationships visible in excerpts, SOURCE INDEX references, or README statements; unsampled wiring is omitted.

Main entry points: [`src/main/java/com/med/qa/service/MedChatSessionService.java`](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/MedChatSessionService.java) (Session management), [`src/main/java/com/med/qa/service/claims/ClaimProcessingService.java`](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimProcessingService.java) (Claim orchestration), [`src/main/java/com/med/qa/rag/MedRetrievalService.java`](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedRetrievalService.java) (Scoped retrieval), [`src/main/java/com/med/qa/service/ChatStreamService.java`](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/ChatStreamService.java) (Chat streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and workflows"]
  node_chat_api["Chat API"]
  node_session_api["Session API"]
  node_stream["Chat streaming"]
end

subgraph group_rag["Medical RAG"]
  node_rag_admin["RAG administration"]
  node_ingestion["Document ingestion"]
  node_retrieval["Scoped retrieval"]
  node_rag_advisor["RAG advisor"]
  node_vector_store[("Vector store")]
end

subgraph group_memory["Session memory"]
  node_session_service["Session management"]
  node_chat_memory["Chat memory repository"]
  node_memory_repository["Memory storage adapter"]
  node_redis_cache["Redis message cache"]
  node_session_lock["Session lock"]
  node_sql_store[("MySQL session store")]
end

subgraph group_claims["Claims and underwriting"]
  node_claims_api["Claims APIs"]
  node_assessment_api["Claim assessment API"]
  node_claim_processing["Claim orchestration"]
  node_claim_consistency["Consistency review"]
  node_claim_eligibility["Claim eligibility"]
  node_underwriting_api["Policy eligibility API"]
  node_underwriting["Underwriting rules"]
  node_declared_conditions[("Declared conditions")]
end

subgraph group_platform["Shared platform"]
  node_security["Authentication and access"]
  node_audit["Operation auditing<br/>[AuditService.java]"]
  node_rate_limit["Rate limiting"]
  node_responses["API errors and results"]
end

node_client(("Patient or staff"))
node_llm["Chat model"]

node_client -->|"submits chat"| node_chat_api
node_chat_api -.->|"streams through"| node_stream
node_stream -->|"adds advisor"| node_rag_advisor
node_stream -->|"streams prompt"| node_llm
node_rag_advisor -.->|"retrieves context"| node_retrieval
node_retrieval -->|"searches vectors"| node_vector_store
node_rag_admin -->|"ingests or deletes"| node_ingestion
node_rag_admin -->|"previews search"| node_retrieval
node_ingestion -->|"writes documents"| node_vector_store
node_client -.->|"manages sessions"| node_session_api
node_session_api -.->|"delegates session work"| node_session_service
node_session_service -->|"reads and writes"| node_sql_store
node_session_service -->|"uses cache"| node_redis_cache
node_session_service -->|"locks mutations"| node_session_lock
node_chat_memory -.->|"delegates storage"| node_memory_repository
node_claims_api -.->|"orchestrates claims"| node_claim_processing
node_assessment_api -.->|"requests assessment"| node_claim_processing
node_claim_processing -->|"delegates consistency"| node_claim_consistency
node_claim_processing -->|"delegates eligibility"| node_claim_eligibility
node_claim_eligibility -->|"retrieves policy clauses"| node_retrieval
node_claim_eligibility -->|"extracts clause facts"| node_llm
node_claim_consistency -->|"extracts document facts"| node_llm
node_underwriting_api -.->|"checks eligibility"| node_underwriting
node_claim_processing -->|"delegates policy check"| node_underwriting
node_underwriting -->|"loads declarations"| node_declared_conditions
node_session_service -->|"marks audited action"| node_audit

click node_chat_api "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ChatController.java"
click node_session_api "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/SessionController.java"
click node_stream "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/ChatStreamService.java"
click node_rag_admin "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/RagAdminController.java"
click node_ingestion "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedDocumentService.java"
click node_retrieval "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedRetrievalService.java"
click node_rag_advisor "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedRagAdvisorFactory.java"
click node_session_service "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/MedChatSessionService.java"
click node_chat_memory "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/MedSpringAiChatMemoryRepository.java"
click node_memory_repository "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/repository/MedChatMemoryRepository.java"
click node_redis_cache "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/cache/RedisMessageCache.java"
click node_session_lock "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/lock/SessionLockService.java"
click node_sql_store "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/mapper/ChatSessionMapper.java"
click node_claims_api "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ClaimsController.java"
click node_assessment_api "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ClaimAssessmentController.java"
click node_claim_processing "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimProcessingService.java"
click node_claim_consistency "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimConsistencyService.java"
click node_claim_eligibility "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimEligibilityService.java"
click node_underwriting_api "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/PolicyEligibilityController.java"
click node_underwriting "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/underwriting/PolicyEligibilityService.java"
click node_declared_conditions "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/mapper/DeclaredConditionMapper.java"
click node_security "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/security/ApiKeyAuthFilter.java"
click node_audit "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/AuditService.java"
click node_rate_limit "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/common/ratelimit/RateLimitService.java"
click node_responses "https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/common/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_chat_api,node_session_api,node_stream toneBlue
class node_rag_admin,node_ingestion,node_retrieval,node_rag_advisor,node_vector_store toneAmber
class node_session_service,node_chat_memory,node_memory_repository,node_redis_cache,node_session_lock,node_sql_store toneMint
class node_claims_api,node_assessment_api,node_claim_processing,node_claim_consistency,node_claim_eligibility,node_underwriting_api,node_underwriting,node_declared_conditions toneRose
class node_security,node_audit,node_rate_limit,node_responses,node_client,node_llm toneIndigo
```

## Components

### API and workflows

- [Chat API](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ChatController.java): `src/main/java/com/med/qa/controller/ChatController.java`
- [Session API](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/SessionController.java): `src/main/java/com/med/qa/controller/SessionController.java`
- [Chat streaming](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/ChatStreamService.java): `src/main/java/com/med/qa/service/ChatStreamService.java`

### Medical RAG

- [RAG administration](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/RagAdminController.java): `src/main/java/com/med/qa/controller/RagAdminController.java`
- [Document ingestion](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedDocumentService.java): `src/main/java/com/med/qa/rag/MedDocumentService.java`
- [Scoped retrieval](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedRetrievalService.java): `src/main/java/com/med/qa/rag/MedRetrievalService.java`
- [RAG advisor](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/rag/MedRagAdvisorFactory.java): `src/main/java/com/med/qa/rag/MedRagAdvisorFactory.java`
- **Vector store**

### Session memory

- [Session management](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/MedChatSessionService.java): `src/main/java/com/med/qa/service/MedChatSessionService.java`
- [Chat memory repository](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/MedSpringAiChatMemoryRepository.java): `src/main/java/com/med/qa/memory/MedSpringAiChatMemoryRepository.java`
- [Memory storage adapter](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/repository/MedChatMemoryRepository.java): `src/main/java/com/med/qa/memory/repository/MedChatMemoryRepository.java`
- [Redis message cache](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/cache/RedisMessageCache.java): `src/main/java/com/med/qa/memory/cache/RedisMessageCache.java`
- [Session lock](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/memory/lock/SessionLockService.java): `src/main/java/com/med/qa/memory/lock/SessionLockService.java`
- [MySQL session store](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/mapper/ChatSessionMapper.java): `src/main/java/com/med/qa/mapper/ChatSessionMapper.java`

### Claims and underwriting

- [Claims APIs](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ClaimsController.java): `src/main/java/com/med/qa/controller/ClaimsController.java`
- [Claim assessment API](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/ClaimAssessmentController.java): `src/main/java/com/med/qa/controller/ClaimAssessmentController.java`
- [Claim orchestration](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimProcessingService.java): `src/main/java/com/med/qa/service/claims/ClaimProcessingService.java`
- [Consistency review](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimConsistencyService.java): `src/main/java/com/med/qa/service/claims/ClaimConsistencyService.java`
- [Claim eligibility](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/claims/ClaimEligibilityService.java): `src/main/java/com/med/qa/service/claims/ClaimEligibilityService.java`
- [Policy eligibility API](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/controller/PolicyEligibilityController.java): `src/main/java/com/med/qa/controller/PolicyEligibilityController.java`
- [Underwriting rules](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/underwriting/PolicyEligibilityService.java): `src/main/java/com/med/qa/service/underwriting/PolicyEligibilityService.java`
- [Declared conditions](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/mapper/DeclaredConditionMapper.java): `src/main/java/com/med/qa/mapper/DeclaredConditionMapper.java`

### Shared platform

- [Authentication and access](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/security/ApiKeyAuthFilter.java): `src/main/java/com/med/qa/security/ApiKeyAuthFilter.java`
- [Operation auditing](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/service/AuditService.java): `src/main/java/com/med/qa/service/AuditService.java`
- [Rate limiting](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/common/ratelimit/RateLimitService.java): `src/main/java/com/med/qa/common/ratelimit/RateLimitService.java`
- [API errors and results](https://github.com/dpkb-dev/springai-med-qa/blob/main/src/main/java/com/med/qa/common/exception/GlobalExceptionHandler.java): `src/main/java/com/med/qa/common/exception/GlobalExceptionHandler.java`

### Other components

- **Patient or staff**
- **Chat model**

## Connections

- Patient or staff → Chat API: submits chat (evidence: `README.md`)
- Chat API → Chat streaming: streams through (evidence: `src/main/java/com/med/qa/controller/ChatController.java`)
- Chat streaming → RAG advisor: adds advisor (evidence: `src/main/java/com/med/qa/service/ChatStreamService.java`)
- Chat streaming → Chat model: streams prompt (evidence: `src/main/java/com/med/qa/service/ChatStreamService.java`)
- RAG advisor → Scoped retrieval: retrieves context
- Scoped retrieval → Vector store: searches vectors (evidence: `src/main/java/com/med/qa/rag/MedRetrievalService.java`)
- RAG administration → Document ingestion: ingests or deletes (evidence: `src/main/java/com/med/qa/controller/RagAdminController.java`)
- RAG administration → Scoped retrieval: previews search (evidence: `src/main/java/com/med/qa/controller/RagAdminController.java`)
- Document ingestion → Vector store: writes documents (evidence: `src/main/java/com/med/qa/rag/MedDocumentService.java`)
- Patient or staff → Session API: manages sessions
- Session API → Session management: delegates session work (evidence: `src/main/java/com/med/qa/controller/SessionController.java`)
- Session management → MySQL session store: reads and writes (evidence: `src/main/java/com/med/qa/service/MedChatSessionService.java`)
- Session management → Redis message cache: uses cache (evidence: `src/main/java/com/med/qa/service/MedChatSessionService.java`)
- Session management → Session lock: locks mutations (evidence: `src/main/java/com/med/qa/service/MedChatSessionService.java`)
- Chat memory repository → Memory storage adapter: delegates storage (evidence: `src/main/java/com/med/qa/memory/MedSpringAiChatMemoryRepository.java`)
- Claims APIs → Claim orchestration: orchestrates claims
- Claim assessment API → Claim orchestration: requests assessment
- Claim orchestration → Consistency review: delegates consistency (evidence: `src/main/java/com/med/qa/service/claims/ClaimProcessingService.java`)
- Claim orchestration → Claim eligibility: delegates eligibility (evidence: `src/main/java/com/med/qa/service/claims/ClaimProcessingService.java`)
- Claim eligibility → Scoped retrieval: retrieves policy clauses (evidence: `src/main/java/com/med/qa/service/claims/ClaimEligibilityService.java`)
- Claim eligibility → Chat model: extracts clause facts (evidence: `src/main/java/com/med/qa/service/claims/ClaimEligibilityService.java`)
- Consistency review → Chat model: extracts document facts (evidence: `src/main/java/com/med/qa/service/claims/ClaimConsistencyService.java`)
- Policy eligibility API → Underwriting rules: checks eligibility
- Claim orchestration → Underwriting rules: delegates policy check (evidence: `src/main/java/com/med/qa/service/claims/ClaimProcessingService.java`)
- Underwriting rules → Declared conditions: loads declarations (evidence: `src/main/java/com/med/qa/service/underwriting/PolicyEligibilityService.java`)
- Session management → Operation auditing: marks audited action (evidence: `src/main/java/com/med/qa/service/MedChatSessionService.java`)
