# ioncrade/rankwise architecture

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

- Interactive diagram: https://gitdiagram.com/ioncrade/rankwise
- Repository: https://github.com/ioncrade/rankwise

## Overview

##### Project type and purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) web application named “RankWise.”
- Purpose: Users upload PDF documents, the system extracts and indexes text chunks, and answers user queries by retrieving relevant passages, re-ranking them, chaining retrievals, and finally generating answers with a Groq LLM.

##### File structure
- Top-level:
– backend/ (Flask API, PDF processing, vector store)
– frontend/ (React UI)
- backend/app.py: Main Flask server exposing upload and query endpoints
- backend/backend/faiss_index.bin + metadata.pkl: Serialized FAISS index and chunk metadata
- backend/build/: Production React build served by Flask in prod
- frontend/src/: React components, app entry point, CSS, tests
- Configuration files: requirements.txt, package.json, .env (for API key)

##### README for additional insights
- Clear two-tier architecture: Flask backend + React frontend
- PDF processing pipeline: PyMuPDF → text splitting → Sentence-Transformers for embeddings → FAISS vector DB
- Query pipeline: Hybrid dense + semantic search → CrossEncoder re-ranking → Chained retrieval → Multi-hop QA → Groq LLM call
- Tech stack: Flask, PyMuPDF, Sentence-Transformers, FAISS, CrossEncoder, Groq API, React

##### Final advice
- Be detailed: decompose the backend into ingestion, embedding, retrieval, re-ranking, chaining, generation, and storage modules
- Essential elements: user, UI, API boundary, PDF pipeline, vector store, ranking modules, LLM, and history

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        direction TB
        Browser["User's Browser (React UI)"]:::frontend
        FrontServer["Frontend Dev/Static Server"]:::frontend
        ProdBuild["Production React Build"]:::frontend
    end

    subgraph "Backend"
        direction TB
        API["Flask Backend API"]:::backend
        PDF["PDF Processing Module\n(PyMuPDF extractor & chunker)"]:::backend
        Emb["Embedding Module\n(Sentence-Transformers)"]:::backend
        VS["Vector Store\n(FAISS Index + Metadata)"]:::db
        Search["Search & Ranking Module\n(Hybrid Retriever & CrossEncoder)"]:::backend
        Chain["Chained Retrieval Controller"]:::backend
        History["Response History Store"]:::backend
        LLM["Groq LLM (External Service)"]:::external
    end

    Browser --> FrontServer
    Browser -->|"HTTP(S) /upload"| API
    FrontServer --> Browser
    API -->|"PDF bytes"| PDF
    PDF -->|"text chunks"| Emb
    Emb -->|"embeddings"| VS

    Browser -->|"HTTP(S) /query"| API
    API -->|"query"| Search
    VS -->|"search/read"| Search
    Search -->|"ranked chunks"| Chain
    Chain -.->|"follow-up queries"| Search
    Chain -->|"context"| LLM
    LLM -->|"answer"| API
    API -->|"response"| Browser

    API --> History
    History --> API

    ProdBuild --> API

    click Browser "https://github.com/ioncrade/rankwise/blob/main/frontend/src/App.js"
    click Browser "https://github.com/ioncrade/rankwise/blob/main/frontend/src/index.js"
    click Browser "https://github.com/ioncrade/rankwise/blob/main/frontend/public/index.html"
    click FrontServer "https://github.com/ioncrade/rankwise/blob/main/frontend/package.json"
    click FrontServer "https://github.com/ioncrade/rankwise/tree/main/backend/build/static/"
    click ProdBuild "https://github.com/ioncrade/rankwise/blob/main/backend/build/index.html"
    click ProdBuild "https://github.com/ioncrade/rankwise/tree/main/backend/build/static/"
    click API "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click PDF "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click Emb "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click Search "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click Chain "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click History "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"
    click VS "https://github.com/ioncrade/rankwise/blob/main/backend/backend/faiss_index.bin"
    click VS "https://github.com/ioncrade/rankwise/blob/main/backend/backend/metadata.pkl"
    click LLM "https://github.com/ioncrade/rankwise/blob/main/backend/app.py"

    classDef frontend fill:#cce5ff,stroke:#0366d6,color:#000
    classDef backend fill:#d4edda,stroke:#28a745,color:#000
    classDef db fill:#ffe5b4,stroke:#d98800,color:#000
    classDef external fill:#f0e0ff,stroke:#6f42c1,color:#000
```
