# naman1995jain/shl-assessment-recommendation-system architecture

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

- Interactive diagram: https://gitdiagram.com/naman1995jain/shl-assessment-recommendation-system
- Repository: https://github.com/naman1995jain/shl-assessment-recommendation-system

## Overview

##### Main Components
- User Interfaces:
- Web UI: Represented by app.py (Streamlit application) that HR professionals or recruiters interact with.
- API Endpoint: Represented by api.py (FastAPI) which allows programmatic access to the system.
- Data Acquisition & Preparation:
- Scraping Component: scrape_shl2.py is responsible for gathering SHL assessment data, which is cached in shl_assessments.csv.
- Data Storage: The CSV file (shl_assessments.csv) acts as a local data store or cache.
- Processing & Integration:
- OpenRouter API Integration: openrouter_api.py handles interactions with the OpenRouter API (using the Mistral model) to generate embeddings and perform natural language content generation.
- Data Processing: Pandas and NumPy are used for data manipulation, while Plotly handles data visualization.
- Configuration & Environment:
- .env file: Stores essential API keys (e.g., the one for OpenRouter).

##### Out the Relationships and Data Flow
- The user (via web UI or API client) sends a query or job description.
- The Streamlit app (app.py) and/or FastAPI (api.py) receive the query.
- These components invoke the OpenRouter API (through openrouter_api.py) to transform and understand the semantics of the query, using AI embeddings.
- Data from shl_assessments.csv (populated by scrape_shl2.py) is processed using data libraries (Pandas/NumPy) and filtered based on the semantic match.
- The system then generates recommendations, including assessments metadata and candidate explanations for relevance.
- If using the Streamlit interface, the recommendations are further visualized using Plotly.
- The API endpoint returns a structured JSON response to the caller.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture clearly separates the user presentation layer (Streamlit UI), the API layer (FastAPI), and backend processing/integration (scraping, data processing, external API calls).
- Dual Interfaces: Recognize the design decision to support both interactive (web) access and programmatic (API) usage.
- External Service Integration: Emphasize the reliance on an external service (OpenRouter API) for advanced natural language processing tasks.
- Data Caching: The design uses persistent CSV storage for assessment data, ensuring that even if scraping isn’t run continuously, cached data is available.

##### Final Advice
- Every component is clearly labeled (e.g., “Streamlit Web UI (app.py)”, “FastAPI Service (api.py)”, “OpenRouter Integration (openrouter_api.py)”, “Data Scraper (scrape_shl2.py)”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        U("User"):::user
        A("Streamlit Web UI (app.py)"):::ui
        B("FastAPI Service (api.py)"):::ui
        D("Uvicorn"):::backend
    end

    %% Data Acquisition & Preparation
    subgraph "Data Acquisition & Preparation"
        S("Data Scraper (scrape_shl2.py)"):::backend
        CSV["Data Store (shl_assessments.csv)"]:::database
    end

    %% Processing & Integration
    subgraph "Processing & Integration"
        OR("OpenRouter Integration (openrouter_api.py)"):::external
        DP("Data Processing (Pandas/NumPy & Plotly)"):::backend
        ENV("Configuration (.env)"):::config
    end

    %% User interactions
    U -->|"sends query"| A
    U -->|"sends query"| B

    %% FastAPI deployment detail
    B -->|"runs on"| D

    %% UI invokes processing components
    A -->|"calls"| OR
    A -->|"calls"| DP
    B -->|"calls"| OR
    B -->|"calls"| DP

    %% External integration accesses configuration
    ENV -->|"API-keys"| OR

    %% Data processing reads cached data
    DP -->|"reads"| CSV

    %% OpenRouter returns results to processing
    OR -->|"returns embeddings"| DP

    %% Processed results returned to interfaces
    DP -->|"visualizes result"| A
    DP -->|"returns JSON"| B

    %% Data acquisition flow
    S -->|"populates"| CSV

    %% Click Events
    click A "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/app.py"
    click B "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/api.py"
    click S "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/scrape_shl2.py"
    click CSV "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/shl_assessments.csv"
    click OR "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/openrouter_api.py"
    click ENV "https://github.com/naman1995jain/shl-assessment-recommendation-system/blob/main/.env"

    %% Styles
    classDef user fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef ui fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef external fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef database fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef config fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
```
