# chekri2123/agentic-profile-recommendation architecture

> Architecture diagram of the GitHub repository chekri2123/agentic-profile-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chekri2123/agentic-profile-recommendation
- Repository: https://github.com/chekri2123/agentic-profile-recommendation

## Overview

##### Project Type and Purpose
- The project appears to be a Python-based recommendation engine specifically aimed at recommending profiles or job opportunities. This is indicated by the presence of specialized data source modules (e.g., adzuna_jobs.py, jooble_jobs.py, linkedin_jobs.py) and core recommendation modules (recommendation_engine.py, recommendation_refiner.py, relevance_scorer.py).
- It likely integrates multiple external job or profile data sources, processes query inputs (via query_parser.py and query_generator.py), and eventually presents recommendations through both a backend (main.py) and an interactive frontend (streamlit_app.py).

##### Analyzing the File Structure
- The “app” directory encapsulates the core business logic:
- The “data_sources” subdirectory contains modules for interfacing with different external job or profile data sources. There’s a manager module that likely coordinates between these various sources.
- Other key modules such as database.py, main.py, query_generator.py, query_parser.py, and various recommendation-related modules indicate separate processing steps and components in the recommendation pipeline.
- The “streamlit_app.py” file suggests that there’s a web front-end (powered by Streamlit) which might serve as the user interface.
- Test files in the “tests” folder show that there is a good level of unit testing across major modules.
- The existence of a devcontainer and related configuration indicates that the project is set up for containerized development and possibly deployment.

a. Main Components:
- User Interface (Frontend): Represented by “streamlit_app.py”. This layer is responsible for accepting user input and displaying the recommendations.
- Application Core / Business Logic: Includes
- The Main Application (main.py) which likely orchestrates the flow.
- Query Processing: “query_parser.py” and “query_generator.py”.
- Recommendation Pipeline: “recommendation_engine.py”, “recommendation_refiner.py”, and “relevance_scorer.py”.
- Data Integration Layer: “data_sources” folder that includes modules for different external sources (adzuna_jobs.py, jooble_jobs.py, linkedin_jobs.py, interest_sources.py, web_search.py) and the “manager.py” that coordinates calls.
- Persistence Layer: “database.py” which manages all database interactions.
- Environment & Configuration: “config.py” and infrastructure files like .devcontainer (which supports containerization/deployment strategies).

b. Relationships and Interactions:
- User actions in the Streamlit UI trigger events that flow into the Main Application.
- The Main Application uses the query parser/generator to understand and formulate queries.
- The recommendation engine uses these queries to retrieve data. It leverages the data integration layer (managed by data_sources/manager.py) to pull data from multiple external job/profile APIs.
- After data retrieval, the recommendation components (including the relevance scorer and refiner) process and filter results before sending them to the UI.
- The Database module handles any data persistence, such as storing query logs, user data, or intermediary recommendations.

c. Architectural Patterns and Design Principles:
- Modular Design: Clear separation of concerns with dedicated modules for query processing, recommendation logic, external data fetching, and persistence.
- Pipeline/Workflow Pattern: Sequential processing from query input ➔ data retrieval ➔ scoring/refinement ➔ output.
- Extensibility: The data_sources modules indicate an extensible design that allows for additional external sources.

d. Relevant Technologies and Tools:
- Python is the core language, with modules organized under the “app” folder.
- Streamlit is used for the front end.
- Testing frameworks and structured tests indicate robust unit testing practices.
- Containerization support (.devcontainer) which might hint at Docker or similar.
- Likely some form of database (indicated by database.py), though the specific DBMS isn’t detailed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Streamlit UI"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        MainApp["Main Application"]:::business
        subgraph "Query Processing"
            QueryParser["Query Parser"]:::business
            QueryGenerator["Query Generator"]:::business
        end
        subgraph "Recommendation Pipeline"
            RecommEngine["Recommendation Engine"]:::business
            RecommRefiner["Recommendation Refiner"]:::business
            RelevScorer["Relevance Scorer"]:::business
        end
    end

    %% Data Integration Layer
    subgraph "Data Integration Layer"
        DataManager["Data Sources Manager"]:::integration
        subgraph "External Data Sources"
            Adzuna["Adzuna Jobs"]:::integration
            Jooble["Jooble Jobs"]:::integration
            LinkedIn["LinkedIn Jobs"]:::integration
            Interest["Interest Sources"]:::integration
            WebSearch["Web Search"]:::integration
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        Database["Database"]:::persistence
    end

    %% Environment & Configuration
    subgraph "Environment & Configuration"
        Config["Configuration"]:::environment
        Devcontainer["Devcontainer"]:::environment
    end

    %% Flow Connections
    UI -->|"trigger"| MainApp
    MainApp -->|"parse"| QueryParser
    MainApp -->|"generate"| QueryGenerator
    QueryParser -->|"processed_query"| RecommEngine
    QueryGenerator -->|"generated_query"| RecommEngine
    RecommEngine -->|"fetch_data"| DataManager
    DataManager -->|"adzuna"| Adzuna
    DataManager -->|"jooble"| Jooble
    DataManager -->|"linkedin"| LinkedIn
    DataManager -->|"interest"| Interest
    DataManager -->|"web_search"| WebSearch
    Adzuna -->|"data"| RecommEngine
    Jooble -->|"data"| RecommEngine
    LinkedIn -->|"data"| RecommEngine
    Interest -->|"data"| RecommEngine
    WebSearch -->|"data"| RecommEngine
    RecommEngine -->|"refine"| RecommRefiner
    RecommRefiner -->|"score"| RelevScorer
    RelevScorer -->|"store"| Database
    RelevScorer -->|"output"| UI
    MainApp -->|"log"| Database
    MainApp -->|"use_config"| Config

    %% Styles
    classDef frontend fill:#f8c8dc,stroke:#cc3366,stroke-width:2px;
    classDef business fill:#fff2cc,stroke:#d4a017,stroke-width:2px;
    classDef integration fill:#d0f0c0,stroke:#228b22,stroke-width:2px;
    classDef persistence fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef environment fill:#fdebd0,stroke:#e67e22,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/streamlit_app.py"
    click MainApp "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/main.py"
    click QueryParser "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/query_parser.py"
    click QueryGenerator "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/query_generator.py"
    click RecommEngine "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/recommendation_engine.py"
    click RecommRefiner "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/recommendation_refiner.py"
    click RelevScorer "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/relevance_scorer.py"
    click Adzuna "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/adzuna_jobs.py"
    click Jooble "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/jooble_jobs.py"
    click LinkedIn "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/linkedin_jobs.py"
    click Interest "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/interest_sources.py"
    click WebSearch "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/web_search.py"
    click DataManager "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/data_sources/manager.py"
    click Database "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/database.py"
    click Config "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/app/config.py"
    click Devcontainer "https://github.com/chekri2123/agentic-profile-recommendation/blob/main/.devcontainer/devcontainer.json"
```
