# palani1munusamy/javadocrag architecture

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

- Interactive diagram: https://gitdiagram.com/palani1munusamy/javadocrag
- Repository: https://github.com/palani1munusamy/javadocrag

## Overview

JavaDoc RAG ingests Oracle JDK 25 API documentation (and optional PDFs), then serves cited developer answers through a hybrid retrieval pipeline. Ingestion discovers and fetches pages, parses them into structured sections, chunks content, and builds text and image indexes. At query time, the API parses symbols and intent, performs direct symbol lookup or hybrid retrieval, and asks Claude to formulate a cited response. The graph also includes suggestions, chat, and image-assisted queries. Some source excerpts are partial; edges for unsampled internals follow explicit README documentation.

Main entry points: [`src/cli/ingest.py`](https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/ingest.py) (Ingest CLI), [`src/cli/serve.py`](https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/serve.py) (FastAPI Service), [`src/indexer/hybrid_retriever.py`](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/hybrid_retriever.py) (Hybrid Retriever), [`src/indexer/db_store.py`](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/db_store.py) (SQLite Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion"]
  node_ingest_cli["Ingest CLI<br/>[ingest.py]"]
  node_crawler["Javadoc Crawler<br/>[crawler.py]"]
  node_javadoc_parser["HTML Parser<br/>[parser.py]"]
  node_pdf_parser["PDF Parser<br/>[pdf_parser.py]"]
  node_chunker["Section Chunker<br/>[chunker.py]"]
end

subgraph group_storage["Knowledge Stores"]
  node_metadata_db[("SQLite Metadata<br/>[db_store.py]")]
  node_embedder["Text Embedder<br/>[embedder.py]"]
  node_bm25_index[("BM25 Index<br/>[bm25_index.py]")]
  node_faiss_store[("FAISS Index<br/>[faiss_store.py]")]
  node_image_embedder["Image Embedder<br/>[image_embedder.py]"]
end

subgraph group_query["Query and Retrieval"]
  node_query_parser["Query Parser<br/>[query_parser.py]"]
  node_retriever["Hybrid Retriever"]
end

subgraph group_serving["Answer Service"]
  node_api["FastAPI Service<br/>[serve.py]"]
  node_generator["Answer Generator<br/>[generator.py]"]
  node_web_ui["Web Interface<br/>[index.html]"]
end

node_developer(("Developer"))
node_oracle_docs["Oracle JDK Docs"]
node_claude["Anthropic Claude"]

node_developer -->|"asks questions"| node_api
node_developer -->|"uses interface"| node_web_ui
node_web_ui -->|"submits queries"| node_api
node_ingest_cli -->|"runs crawl"| node_crawler
node_crawler -->|"fetches pages"| node_oracle_docs
node_crawler -->|"stores HTML"| node_metadata_db
node_ingest_cli -->|"reads pages"| node_metadata_db
node_ingest_cli -->|"parses HTML"| node_javadoc_parser
node_ingest_cli -.->|"parses PDFs"| node_pdf_parser
node_ingest_cli -->|"chunks sections"| node_chunker
node_javadoc_parser -->|"returns sections"| node_chunker
node_pdf_parser -.->|"returns sections"| node_chunker
node_ingest_cli -->|"writes chunks"| node_metadata_db
node_ingest_cli -->|"embeds chunks"| node_embedder
node_ingest_cli -->|"builds index"| node_bm25_index
node_ingest_cli -->|"builds vectors"| node_faiss_store
node_ingest_cli -->|"embeds images"| node_image_embedder
node_ingest_cli -->|"stores image vectors"| node_faiss_store
node_api -->|"parses question"| node_query_parser
node_query_parser -->|"returns symbols"| node_api
node_api -->|"looks up symbols"| node_metadata_db
node_api -->|"requests matches"| node_retriever
node_retriever -->|"searches terms"| node_bm25_index
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"searches vectors"| node_faiss_store
node_retriever -->|"loads chunks"| node_metadata_db
node_api -.->|"searches images"| node_retriever
node_retriever -.->|"embeds query image"| node_image_embedder
node_retriever -.->|"searches image vectors"| node_faiss_store
node_api -->|"supplies context"| node_generator
node_generator -->|"generates answer"| node_claude
node_generator -->|"returns citations"| node_api

click node_ingest_cli "https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/ingest.py"
click node_crawler "https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/crawler.py"
click node_javadoc_parser "https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/parser.py"
click node_pdf_parser "https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/pdf_parser.py"
click node_chunker "https://github.com/palani1munusamy/javadocrag/blob/main/src/chunker/chunker.py"
click node_metadata_db "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/db_store.py"
click node_embedder "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/embedder.py"
click node_bm25_index "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/bm25_index.py"
click node_faiss_store "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/faiss_store.py"
click node_image_embedder "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/image_embedder.py"
click node_api "https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/serve.py"
click node_query_parser "https://github.com/palani1munusamy/javadocrag/blob/main/src/query/query_parser.py"
click node_retriever "https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/hybrid_retriever.py"
click node_generator "https://github.com/palani1munusamy/javadocrag/blob/main/src/generator/generator.py"
click node_web_ui "https://github.com/palani1munusamy/javadocrag/blob/main/static/index.html"

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_ingest_cli,node_crawler,node_javadoc_parser,node_pdf_parser,node_chunker toneBlue
class node_metadata_db,node_embedder,node_bm25_index,node_faiss_store,node_image_embedder toneAmber
class node_query_parser,node_retriever toneMint
class node_api,node_generator,node_web_ui toneRose
class node_developer,node_oracle_docs,node_claude toneIndigo
```

## Components

### Ingestion

- [Ingest CLI](https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/ingest.py): `src/cli/ingest.py`
- [Javadoc Crawler](https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/crawler.py): `src/crawler/crawler.py`
- [HTML Parser](https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/parser.py): `src/crawler/parser.py`
- [PDF Parser](https://github.com/palani1munusamy/javadocrag/blob/main/src/crawler/pdf_parser.py): `src/crawler/pdf_parser.py`
- [Section Chunker](https://github.com/palani1munusamy/javadocrag/blob/main/src/chunker/chunker.py): `src/chunker/chunker.py`

### Knowledge Stores

- [SQLite Metadata](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/db_store.py): `src/indexer/db_store.py`
- [Text Embedder](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/embedder.py): `src/indexer/embedder.py`
- [BM25 Index](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/bm25_index.py): `src/indexer/bm25_index.py`
- [FAISS Index](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/faiss_store.py): `src/indexer/faiss_store.py`
- [Image Embedder](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/image_embedder.py): `src/indexer/image_embedder.py`

### Query and Retrieval

- [Query Parser](https://github.com/palani1munusamy/javadocrag/blob/main/src/query/query_parser.py): `src/query/query_parser.py`
- [Hybrid Retriever](https://github.com/palani1munusamy/javadocrag/blob/main/src/indexer/hybrid_retriever.py): `src/indexer/hybrid_retriever.py`

### Answer Service

- [FastAPI Service](https://github.com/palani1munusamy/javadocrag/blob/main/src/cli/serve.py): `src/cli/serve.py`
- [Answer Generator](https://github.com/palani1munusamy/javadocrag/blob/main/src/generator/generator.py): `src/generator/generator.py`
- [Web Interface](https://github.com/palani1munusamy/javadocrag/blob/main/static/index.html): `static/index.html`

### Other components

- **Developer**
- **Oracle JDK Docs**
- **Anthropic Claude**

## Connections

- Developer → FastAPI Service: asks questions
- Developer → Web Interface: uses interface
- Web Interface → FastAPI Service: submits queries
- Ingest CLI → Javadoc Crawler: runs crawl
- Javadoc Crawler → Oracle JDK Docs: fetches pages
- Javadoc Crawler → SQLite Metadata: stores HTML
- Ingest CLI → SQLite Metadata: reads pages
- Ingest CLI → HTML Parser: parses HTML
- Ingest CLI → PDF Parser: parses PDFs
- Ingest CLI → Section Chunker: chunks sections
- HTML Parser → Section Chunker: returns sections
- PDF Parser → Section Chunker: returns sections
- Ingest CLI → SQLite Metadata: writes chunks
- Ingest CLI → Text Embedder: embeds chunks
- Ingest CLI → BM25 Index: builds index
- Ingest CLI → FAISS Index: builds vectors
- Ingest CLI → Image Embedder: embeds images
- Ingest CLI → FAISS Index: stores image vectors
- FastAPI Service → Query Parser: parses question
- Query Parser → FastAPI Service: returns symbols
- FastAPI Service → SQLite Metadata: looks up symbols
- FastAPI Service → Hybrid Retriever: requests matches
- Hybrid Retriever → BM25 Index: searches terms
- Hybrid Retriever → Text Embedder: embeds query
- Hybrid Retriever → FAISS Index: searches vectors
- Hybrid Retriever → SQLite Metadata: loads chunks
- FastAPI Service → Hybrid Retriever: searches images
- Hybrid Retriever → Image Embedder: embeds query image
- Hybrid Retriever → FAISS Index: searches image vectors
- FastAPI Service → Answer Generator: supplies context
- Answer Generator → Anthropic Claude: generates answer
- Answer Generator → FastAPI Service: returns citations