# viniciusbktech/semantic-comparison architecture

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

- Interactive diagram: https://gitdiagram.com/viniciusbktech/semantic-comparison
- Repository: https://github.com/viniciusbktech/semantic-comparison

## Overview

##### Project type and purpose
- This is a full-stack web application (“Semantic Comparison Project”) for semantically comparing news articles.
- Backend: FastAPI service + Elasticsearch for embedding-based search and reranking.
- Frontend: React single-page application for user queries, results display, and interaction.

##### File structure
Top-level:
- backend/ – FastAPI application
– app/main.py (entry point, REST endpoints)
– app/elastic_utils.py (helpers to index/query Elasticsearch)
– app/models.py (Pydantic models for request/response)
– requirements.txt (Python deps)
– semantic_comparison-venv/ (virtual environment)
- frontend/ – React application
– public/index.html (HTML shell)
– src/ (JSX/CSS)
- App.jsx (root component)
- ComparisonView.jsx (results UI)
- ConfigPanel.jsx (query config UI)
– package.json & lock (Node deps)

##### README for additional insights
- Backend exposes REST endpoints for semantic search, uses Elasticsearch 8+, Python 3.8+.
- Frontend runs under Node.js 18+.
- Deployment calls for a reverse proxy (nginx), HTTPS, and environment variables.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Proxy
    User["User Browser"]:::user
    Nginx["Nginx Reverse Proxy"]:::proxy

    User --> Nginx
    Nginx -->|"HTTP(S) REST API"| Main

    %% Frontend Layer
    subgraph "Frontend"
        Shell["HTML Shell<br/>public/index.html"]:::frontend
        Index["Entry Point<br/>src/index.js"]:::frontend
        App["App.jsx<br/>Root Component"]:::frontend
        Comparison["ComparisonView.jsx"]:::frontend
        Config["ConfigPanel.jsx"]:::frontend
        Styles["CSS Stylesheets"]:::frontend
        Package["package.json &<br/>package-lock.json"]:::frontend
    end

    Nginx -->|"Serves Static Files"| Shell
    Shell --> Index
    Index --> App
    App --> Comparison
    App --> Config
    App --> Styles
    App --> Package

    %% Backend Layer
    subgraph "Backend"
        Main["main.py<br/>REST Endpoints"]:::backend
        FastAPI["FastAPI Service"]:::backend
        Utils["elastic_utils.py"]:::backend
        Models["models.py<br/>Pydantic Models"]:::backend
        Requirements["requirements.txt"]:::backend
        README["README.md"]:::backend
    end

    Main --> FastAPI
    FastAPI --> Models
    FastAPI --> Utils
    Main --> Requirements
    Main --> README

    %% Data Layer
    subgraph "Data Layer"
        ES["Elasticsearch Cluster"]:::db
    end

    FastAPI -->|"Vector Search & Rerank"| ES
    ES -->|"Search Results"| FastAPI
    FastAPI -->|"JSON Response"| App

    %% Click Events
    click React "https://github.com/viniciusbktech/semantic-comparison/tree/main/frontend/"
    click Shell "https://github.com/viniciusbktech/semantic-comparison/blob/main/frontend/public/index.html"
    click Index "https://github.com/viniciusbktech/semantic-comparison/blob/main/frontend/src/index.js"
    click App "https://github.com/viniciusbktech/semantic-comparison/blob/main/frontend/src/App.jsx"
    click Comparison "https://github.com/viniciusbktech/semantic-comparison/blob/main/frontend/src/ComparisonView.jsx"
    click Config "https://github.com/viniciusbktech/semantic-comparison/blob/main/frontend/src/ConfigPanel.jsx"
    click Styles "https://github.com/viniciusbktech/semantic-comparison/tree/main/frontend/src/"
    click Package "https://github.com/viniciusbktech/semantic-comparison/tree/main/frontend/"
    click FastAPI "https://github.com/viniciusbktech/semantic-comparison/tree/main/backend/app/"
    click Main "https://github.com/viniciusbktech/semantic-comparison/blob/main/backend/app/main.py"
    click Utils "https://github.com/viniciusbktech/semantic-comparison/blob/main/backend/app/elastic_utils.py"
    click Models "https://github.com/viniciusbktech/semantic-comparison/blob/main/backend/app/models.py"
    click Requirements "https://github.com/viniciusbktech/semantic-comparison/blob/main/backend/app/requirements.txt"
    click README "https://github.com/viniciusbktech/semantic-comparison/blob/main/backend/README.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFF2D8,stroke:#22863A,color:#22863A;
    classDef db fill:#FFF5B1,stroke:#735C0F,color:#735C0F;
    classDef proxy fill:#E3DFFF,stroke:#6F42C1,color:#6F42C1;
    classDef user fill:#FFEFEF,stroke:#CB2431,color:#CB2431;
```
