# astrochialinko/watsonqasystem architecture

> Architecture diagram of the GitHub repository astrochialinko/watsonqasystem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astrochialinko/watsonqasystem
- Repository: https://github.com/astrochialinko/watsonqasystem

## Overview

##### Project type and purpose
- This is an open-source, experimental QA / IR (information retrieval) tool that replicates part of IBM Watson’s Jeopardy QA pipeline, focusing on indexing Wikipedia pages and retrieving the most likely page for a given trivia clue.

##### File structure
- Top-level artifacts:
- pom.xml: Maven build, dependencies (Lucene, OpenNLP, OpenAI API)
- src/main/java/edu/arizona/cs: core Java code
– BuildIndex.java: builds Lucene indexes from Wikipedia dump
– *Analyzer.java (LemmaAnalyzer, WikipediaAnalyzer): custom Lucene Analyzers
– QueryEngine.java: issues queries against Lucene index, optional GPT re-ranking
– MainWatson.java: orchestrator / CLI entry point
– ResultClass.java: holds retrieval results
- src/main/resources/questions.txt: 100 Jeopardy questions
- index folders (not shown in file_tree but in README): four separate Lucene indexes (std, lemma, stem, wiki)
- src/test/java/...: JUnit tests for each retrieval configuration
- analysis/analysis_plot.py & outputs/: Python script for plotting performance

##### README for additional insights
- Describes five retrieval modes (standard tokenizer, lemmatization, stemming, Wikipedia tokenizer, ChatGPT rerank)
- Performance metrics (P@1, MRR)
- External dependencies: Lucene, OpenNLP dictionary, OpenAI API for ChatGPT reranking

a. Main components
1. Data Ingestion & Indexing
- Wikipedia Dump → BuildIndex → Lucene Index (std/lemma/stem/wiki)
2. Query Processing
- questions.txt or interactive input → QueryEngine
- Lucene Analyzers (Standard, LemmaAnalyzer, PorterStem, WikiAnalyzer)
3. Retrieval & Ranking
- Lucene Searcher applies chosen Similarity (BM25, Boolean, etc.)
- Results → ResultClass
4. Optional Reranking
- Top-K results → OpenAI ChatGPT API → reranked list
5. Evaluation & Analysis
- TestWaston*.java → performance metrics
- analysis_plot.py → plots MRR/P@1 from outputs/

b. Relationships & data flows

c. Architectural patterns / design principles
- Modular “Analyzer” strategy: interchangeable tokenization pipelines via Lucene’s Analyzer API
- Pluggable retrieval modes: tests select one similarity/analysis chain
- Separation of concerns: indexing vs. querying vs. evaluation vs. analysis

d. Key technologies / libraries
- Apache Lucene (indexing, search, Analyzer framework, Similarity measures)
- Apache OpenNLP for lemmatization (en-lemmatizer.dict, LemmaAnalyzer)
- OpenAI API (ChatGPT) for reranking in TestWastonStemChat
- JUnit / Maven Surefire for automated testing
- Python / matplotlib (analysis_plot.py) for performance visualization

## Diagram (Mermaid)

```mermaid
graph TB
    classDef data fill:#AED6F1,color:#1B4F72
    classDef core fill:#ABEBC6,color:#1D8348
    classDef external fill:#F5B041,color:#873600
    classDef eval fill:#D5D8DC,color:#424949

    pom["pom.xml"]:::data

    subgraph "Orchestrator"
        MW["MainWatson"]:::core
    end

    subgraph "Indexing"
        docWiki["Wikipedia Dump"]:::data
        BI["BuildIndex"]:::core
        stdIndex(("std index")):::data
        lemmaIndex(("lemma index")):::data
        stemIndex(("stem index")):::data
        wikiIndex(("wiki index")):::data

        docWiki -->|raw wiki files| BI
        MW --> BI
        BI --> stdIndex
        BI --> lemmaIndex
        BI --> stemIndex
        BI --> wikiIndex
    end

    subgraph "Querying"
        QIN["questions.txt"]:::data
        QE["QueryEngine"]:::core
        SA["StandardAnalyzer"]:::core
        LA["LemmaAnalyzer"]:::core
        PSTA["PorterStemAnalyzer"]:::core
        WA["WikipediaAnalyzer"]:::core
        dict["en-lemmatizer.dict"]:::data
        res["ResultClass"]:::core

        MW --> QE
        QIN -->|queries| QE
        QE --> SA
        QE --> LA
        QE --> PSTA
        QE --> WA
        dict --> LA
        SA -->|tokenized terms| QE
        LA -->|lemmatized terms| QE
        PSTA -->|stemmed terms| QE
        WA -->|wiki tokens| QE
        QE -->|initial results| res
    end

    subgraph "Reranking"
        GPT["OpenAI ChatGPT API"]:::external
        res -->|top-K docs| GPT
        GPT -->|reranked results| res
    end

    subgraph "Evaluation"
        subgraph "JUnit Tests"
            TStd["TestWastonStd"]:::eval
            TLem["TestWastonLemma"]:::eval
            TStem["TestWastonStem"]:::eval
            TWiki["TestWastonWiki"]:::eval
            TChat["TestWastonStemChat"]:::eval
        end
        outs["outputs folder"]:::eval
        AP["analysis_plot.py"]:::eval

        TStd -->|invoke| QE
        TLem -->|invoke| QE
        TStem -->|invoke| QE
        TWiki -->|invoke| QE
        TChat -->|invoke| QE
        res -->|results| TStd
        res -->|results| TLem
        res -->|results| TStem
        res -->|results| TWiki
        res -->|results| TChat
        subgraph "Outputs"
            TStd --> outs
            TLem --> outs
            TStem --> outs
            TWiki --> outs
            TChat --> outs
        end
        outs -->|data| AP
    end

    click BI "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/BuildIndex.java"
    click LA "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/LemmaAnalyzer.java"
    click WA "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/WikipediaAnalyzer.java"
    click QE "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/QueryEngine.java"
    click MW "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/MainWatson.java"
    click res "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/java/edu/arizona/cs/ResultClass.java"
    click QIN "https://github.com/astrochialinko/watsonqasystem/blob/main/src/main/resources/questions.txt"
    click dict "https://github.com/astrochialinko/watsonqasystem/blob/main/en-lemmatizer.dict"
    click pom "https://github.com/astrochialinko/watsonqasystem/blob/main/pom.xml"
    click TStd "https://github.com/astrochialinko/watsonqasystem/blob/main/src/test/java/edu/arizona/cs/TestWastonStd.java"
    click TLem "https://github.com/astrochialinko/watsonqasystem/blob/main/src/test/java/edu/arizona/cs/TestWastonLemma.java"
    click TStem "https://github.com/astrochialinko/watsonqasystem/blob/main/src/test/java/edu.arizona/cs/TestWastonStem.java"
    click TWiki "https://github.com/astrochialinko/watsonqasystem/blob/main/src/test/java/edu/arizona/cs/TestWastonWiki.java"
    click TChat "https://github.com/astrochialinko/watsonqasystem/blob/main/src/test/java/edu.arizona/cs/TestWastonStemChat.java"
    click AP "https://github.com/astrochialinko/watsonqasystem/blob/main/analysis/analysis_plot.py"
```
