# n-kishore1983/ai-hoa-support architecture

> Architecture diagram of the GitHub repository n-kishore1983/ai-hoa-support, 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/n-kishore1983/ai-hoa-support
- Repository: https://github.com/n-kishore1983/ai-hoa-support

## Overview

AI HOA Support ingests governing-document PDFs, extracts and chunks their text, indexes them for hybrid retrieval, and exposes search through an MCP tool for agents. At startup, the configured folder loader checks Redis for duplicate files, reads PDF pages, and delegates chunk storage; OCR detection and fallback handle image-based content. For questions, the support service searches the vector store and Lucerne, fuses matches, and prompts a chat model to produce a grounded response. README documents external stores and MCP capabilities; some integration wiring is configuration-driven and not shown in the excerpts.

Main entry points: [`src/main/java/com/learning/services/HoaSupportService.java`](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/HoaSupportService.java) (MCP support tool), [`src/main/java/com/learning/init/HoaDocumentLoader.java`](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/init/HoaDocumentLoader.java) (PDF folder loader), [`src/main/java/com/learning/AppConfig.java`](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/AppConfig.java) (Service configuration), [`src/main/java/com/learning/services/SemanticDocumentSplitter.java`](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/SemanticDocumentSplitter.java) (Semantic chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_loader["PDF folder loader"]
  node_splitter["Semantic chunking"]
  node_ocr["OCR detection"]
  node_payload["Document payload"]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_support["MCP support tool"]
  node_lucerne_writer["Lucerne writer"]
  node_lucerne_search["Lucerne search<br/>[LucerneSearch.java]"]
end

subgraph group_integration["Application integration"]
  node_application["Spring Boot app"]
  node_token_advisor["Token usage advisor"]
  node_config["Service configuration<br/>[AppConfig.java]"]
end

subgraph group_models["Model services"]
  node_embedding{{"Embedding model"}}
  node_chat_model{{"Chat model"}}
end

node_agent(("Resident / agent"))
node_pdf_folder["HOA PDF folder"]
node_redis[("Redis cache")]
node_vector_store[("Chroma vector store")]
node_agent_result["Grounded answer"]

node_agent -->|"calls MCP tool"| node_support
node_support -->|"returns excerpts / answer"| node_agent_result
node_pdf_folder -->|"provides PDFs"| node_loader
node_application -->|"initializes loader"| node_loader
node_loader -->|"checks checksum"| node_redis
node_loader -->|"delegates chunk storage"| node_support
node_loader -->|"checks image content"| node_ocr
node_support -->|"checks OCR content"| node_ocr
node_support -->|"splits text"| node_splitter
node_splitter -->|"embeds sentences"| node_embedding
node_support -->|"adds chunks / searches"| node_vector_store
node_support -->|"writes chunks"| node_lucerne_writer
node_support -->|"searches BM25"| node_lucerne_search
node_support -->|"records checksum"| node_redis
node_support -->|"prompts model"| node_chat_model
node_support -->|"configures advisor"| node_token_advisor
node_config -->|"creates writer"| node_lucerne_writer
node_config -->|"creates searcher"| node_lucerne_search
node_config -->|"configures provider"| node_embedding
node_config -->|"configures provider"| node_chat_model

click node_application "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/AiHoaSupportApplication.java"
click node_loader "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/init/HoaDocumentLoader.java"
click node_support "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/HoaSupportService.java"
click node_splitter "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/SemanticDocumentSplitter.java"
click node_ocr "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/PdfOcrDetector.java"
click node_lucerne_writer "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/LucerneDocumentWriter.java"
click node_lucerne_search "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/LucerneSearch.java"
click node_token_advisor "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/advisors/TokenUsageAdvisor.java"
click node_config "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/AppConfig.java"
click node_payload "https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/domain/HoaDocumentPayload.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_loader,node_splitter,node_ocr,node_payload toneBlue
class node_support,node_lucerne_writer,node_lucerne_search,node_redis,node_vector_store toneAmber
class node_application,node_token_advisor,node_config toneMint
class node_embedding,node_chat_model toneRose
class node_agent,node_pdf_folder,node_agent_result toneIndigo
```

## Components

### Document ingestion

- [PDF folder loader](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/init/HoaDocumentLoader.java): `src/main/java/com/learning/init/HoaDocumentLoader.java`
- [Semantic chunking](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/SemanticDocumentSplitter.java): `src/main/java/com/learning/services/SemanticDocumentSplitter.java`
- [OCR detection](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/PdfOcrDetector.java): `src/main/java/com/learning/services/PdfOcrDetector.java`
- [Document payload](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/domain/HoaDocumentPayload.java): `src/main/java/com/learning/domain/HoaDocumentPayload.java`

### Hybrid retrieval

- [MCP support tool](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/HoaSupportService.java): `src/main/java/com/learning/services/HoaSupportService.java`
- [Lucerne writer](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/LucerneDocumentWriter.java): `src/main/java/com/learning/services/LucerneDocumentWriter.java`
- [Lucerne search](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/services/LucerneSearch.java): `src/main/java/com/learning/services/LucerneSearch.java`

### Application integration

- [Spring Boot app](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/AiHoaSupportApplication.java): `src/main/java/com/learning/AiHoaSupportApplication.java`
- [Token usage advisor](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/advisors/TokenUsageAdvisor.java): `src/main/java/com/learning/advisors/TokenUsageAdvisor.java`
- [Service configuration](https://github.com/n-kishore1983/ai-hoa-support/blob/main/src/main/java/com/learning/AppConfig.java): `src/main/java/com/learning/AppConfig.java`

### Model services

- **Embedding model**
- **Chat model**

### Other components

- **Resident / agent**
- **HOA PDF folder**
- **Redis cache**
- **Chroma vector store**
- **Grounded answer**

## Connections

- Resident / agent → MCP support tool: calls MCP tool (evidence: `README.md`)
- MCP support tool → Grounded answer: returns excerpts / answer (evidence: `README.md`)
- HOA PDF folder → PDF folder loader: provides PDFs (evidence: `src/main/java/com/learning/init/HoaDocumentLoader.java`)
- Spring Boot app → PDF folder loader: initializes loader (evidence: `src/main/java/com/learning/init/HoaDocumentLoader.java`)
- PDF folder loader → Redis cache: checks checksum (evidence: `src/main/java/com/learning/init/HoaDocumentLoader.java`)
- PDF folder loader → MCP support tool: delegates chunk storage (evidence: `src/main/java/com/learning/init/HoaDocumentLoader.java`)
- PDF folder loader → OCR detection: checks image content (evidence: `src/main/java/com/learning/init/HoaDocumentLoader.java`)
- MCP support tool → OCR detection: checks OCR content (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- MCP support tool → Semantic chunking: splits text (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- Semantic chunking → Embedding model: embeds sentences (evidence: `src/main/java/com/learning/services/SemanticDocumentSplitter.java`)
- MCP support tool → Chroma vector store: adds chunks / searches (evidence: `README.md`)
- MCP support tool → Lucerne writer: writes chunks (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- MCP support tool → Lucerne search: searches BM25 (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- MCP support tool → Redis cache: records checksum (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- MCP support tool → Chat model: prompts model (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- MCP support tool → Token usage advisor: configures advisor (evidence: `src/main/java/com/learning/services/HoaSupportService.java`)
- Service configuration → Lucerne writer: creates writer (evidence: `src/main/java/com/learning/AppConfig.java`)
- Service configuration → Lucerne search: creates searcher (evidence: `src/main/java/com/learning/AppConfig.java`)
- Service configuration → Embedding model: configures provider (evidence: `src/main/java/com/learning/AppConfig.java`)
- Service configuration → Chat model: configures provider (evidence: `src/main/java/com/learning/AppConfig.java`)