# peiyun2260/scorerag architecture

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

- Interactive diagram: https://gitdiagram.com/peiyun2260/scorerag
- Repository: https://github.com/peiyun2260/scorerag

## Overview

##### Project Type and Purpose
- ScoreRAG is a full-stack news-generation application consisting of:
- A FastAPI backend pipeline that retrieves, scores, and summarizes news.
- A React + Vite frontend UI for query input and result visualization.
- Data stores (ChromaDB for embeddings, MongoDB for raw articles).
- Integration with LLM providers (OpenAI, Groq) and HuggingFace embeddings.

##### File-Structure Analysis
- Top-level: `backend/`, `frontend/`, config files (`Makefile`, `pyproject.toml`, `requirements.txt`).
- `backend/app/` subdirectories:
- `api/` (FastAPI routers)
- `services/` (retrieval, scoring, summary, generation business logic)
- `db/` (Chroma & Mongo connectors)
- `llm_clients/` (OpenAI & Groq abstractions)
- `schemas/` (Pydantic models for request/response)
- `backend/scripts/`: command-line ingestion and pipeline test utilities.
- `backend/tests/`: unit tests for API routes.
- `frontend/`: standard React + Vite structure (`src/components`, `App.jsx`, `index.html`, `public/sample_output.json`).

##### README Insights
- Purpose: build “retrieval-augmented generation” pipeline for news.
- Key tech: FastAPI, React/Vite, ChromaDB, MongoDB, OpenAI/Groq, HuggingFace embeddings.
- Flow:
1. Ingest news into ChromaDB & MongoDB.
2. API `POST /api/query` → retrieve top-K docs via embedding search.
3. Re-rank with multi-round GPT scoring.
4. Produce summary and full article with citations.
5. Frontend displays results or sample JSON in demo mode.

##### Components
a. Main Components
- Frontend (React/Vite SPA)
- Backend (FastAPI app)
- Data Stores: ChromaDB, MongoDB
- External LLM Services: OpenAI, Groq
- Embedding Service (HuggingFace model)
- CLI Scripts (ingest, test pipeline)
b. Relationships & Data Flow
- User interacts with Frontend → sends HTTP POST to FastAPI API Gateway.
- Router (`news_router.py`) invokes Service layer:
– EmbeddingService queries ChromaDB for top-K vectors.
– CoTService and ScoringService call OpenAI/Groq clients.
– SummaryService and GenerationService orchestrate LLM calls.
- DB connectors read/write from MongoDB (raw data) & ChromaDB (embeddings).
- Results flow back through API → Frontend renders summaries, references.
- CLI Scripts bypass UI for bulk ingestion or pipeline tests.
c. Architectural Patterns & Principles
- Layered architecture: API layer → Service (business logic) → Data/External integrations.
- Dependency inversion: LLM clients & DB connectors abstracted behind interfaces.
- Single Responsibility: each service class focuses on one pipeline stage.
- Config-driven: environment variables for keys and DB URIs (.env).
d. Key Technologies & Frameworks
- Backend: Python 3.9+, FastAPI, Pydantic, ChromaDB, PyMongo
- Frontend: React 18+, Vite, JSX
- LLMs: OpenAI GPT, Groq, HuggingFace embeddings
- Dev tools: Makefile, uv (uvicorn/virtualenv), pytest

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Layer
    subgraph "User-Facing Layer"
        direction TB
        U(User):::external
        subgraph Frontend
            direction TB
            HTML["Entry Point (index.html)"]:::frontend
            Main["Main.jsx"]:::frontend
            App["App.jsx"]:::frontend
            UI["NewsGenerator.jsx"]:::frontend
        end
    end

    %% Server-Side Layer
    subgraph "Server-Side Layer"
        direction TB
        API["API Router\n(news_router.py)"]:::backend
        subgraph Services
            direction TB
            ER["EmbeddingService\n(embedding_service.py)"]:::backend
            SC["CoTService\n(CoT_service.py)"]:::backend
            SU["SummaryService\n(summary_service.py)"]:::backend
            GE["GenerationService\n(generation_service.py)"]:::backend
        end
        subgraph "DB Connectors"
            direction TB
            CC["ChromaConnector\n(chroma_connector.py)"]:::backend
            MC["MongoConnector\n(mongo_connector.py)"]:::backend
        end
        SM["Schemas\n(news.py)"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Chroma[(ChromaDB)]:::datastore
        Mongo[(MongoDB)]:::datastore
    end

    %% External Services
    subgraph "External LLM & Embeddings"
        direction TB
        HF["HuggingFace Embedding Service"]:::external
        OA["OpenAI Client\n(openai_client.py)"]:::external
        GQ["Groq Client\n(groq_client.py)"]:::external
    end

    %% CLI Tools & Tests
    subgraph "CLI Tools & Tests"
        direction TB
        Ingest["Ingest Script\n(ingest_sample.py)"]:::scripts
        TestPipe["Test Pipeline Script\n(test_score_pipeline.py)"]:::scripts
        UnitTests["Unit Tests\n(test_news_router.py)"]:::scripts
    end

    %% Relationships
    U --> HTML
    HTML --> Main
    Main --> App
    App --> UI
    UI -- "HTTP POST /api/query\n(JSON)" --> API
    API --> SM
    API --> ER
    ER --> CC
    CC --> Chroma
    ER --> SC
    SC --> OA
    SC --> GQ
    SC --> SU
    SU --> OA
    SU --> GQ
    SU --> GE
    GE --> OA
    GE --> GQ
    GE --> MC
    MC --> Mongo
    API -- "JSON response" --> UI
    Ingest --> CC
    Ingest --> MC
    TestPipe --> API
    UnitTests --> API

    %% Click Events
    click HTML "https://github.com/peiyun2260/scorerag/blob/main/frontend/index.html"
    click Main "https://github.com/peiyun2260/scorerag/blob/main/frontend/src/main.jsx"
    click App "https://github.com/peiyun2260/scorerag/blob/main/frontend/src/App.jsx"
    click UI "https://github.com/peiyun2260/scorerag/blob/main/frontend/src/components/NewsGenerator.jsx"
    click API "https://github.com/peiyun2260/scorerag/blob/main/backend/app/api/news_router.py"
    click ER "https://github.com/peiyun2260/scorerag/blob/main/backend/app/services/embedding_service.py"
    click SC "https://github.com/peiyun2260/scorerag/blob/main/backend/app/services/CoT_service.py"
    click SU "https://github.com/peiyun2260/scorerag/blob/main/backend/app/services/summary_service.py"
    click GE "https://github.com/peiyun2260/scorerag/blob/main/backend/app/services/generation_service.py"
    click CC "https://github.com/peiyun2260/scorerag/blob/main/backend/app/db/chroma_connector.py"
    click MC "https://github.com/peiyun2260/scorerag/blob/main/backend/app/db/mongo_connector.py"
    click OA "https://github.com/peiyun2260/scorerag/blob/main/backend/app/llm_clients/openai_client.py"
    click GQ "https://github.com/peiyun2260/scorerag/blob/main/backend/app/llm_clients/groq_client.py"
    click SM "https://github.com/peiyun2260/scorerag/blob/main/backend/app/schemas/news.py"
    click Ingest "https://github.com/peiyun2260/scorerag/blob/main/backend/scripts/ingest_sample.py"
    click TestPipe "https://github.com/peiyun2260/scorerag/blob/main/backend/scripts/test_score_pipeline.py"
    click UnitTests "https://github.com/peiyun2260/scorerag/blob/main/backend/tests/test_news_router.py"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#2d662d,color:#000
    classDef backend fill:#cce0ff,stroke:#264d73,color:#000
    classDef datastore fill:#ffe0b3,stroke:#b36b00,color:#000
    classDef external fill:#e5ccff,stroke:#662d73,color:#000
    classDef scripts fill:#e0e0e0,stroke:#4d4d4d,color:#000
    classDef external,U external
    class SM,API,ER,SC,SU,GE,CC,MC backend
    class Chroma,Mongo datastore
    class HF,OA,GQ external
    class Ingest,TestPipe,UnitTests scripts
```
