# leonnorblad/competencematching architecture

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

- Interactive diagram: https://gitdiagram.com/leonnorblad/competencematching
- Repository: https://github.com/leonnorblad/competencematching

## Overview

##### Project Type and Purpose
- The Competence Matching project is a lightweight, local, full-stack application focused on matching job listings to a candidate’s resume and requirements.
- It manages email ingestion, resume parsing and summarization, LLM-powered query generation, and a vector database (Chroma DB) search for retrieving the best job matches.

##### Main Components
- Terminal User Interface (TUI): Guides users through data ingestion, resume input, and matching prompt steps.
- Email Collection & Ingestion Module: Parses emails (from various formats like .csv, .eml, .xml, .pdf) and converts them into structured text files. It enriches the data with metadata tags (location, start date, remote options) and preprocesses them by converting dates and geolocations.
- Resume Parsing and Summarization Module: Uses PDF parsing (via Docling) to convert resumes into summarized text—dividing the resume into sections to generate an information-dense summary.
- LLM-Based Query Writer: Generates database queries using a local LLM (Llama) influenced by the user’s job preferences and resume summary. It converts natural language to structured query objects with precise filtering (e.g., date ranges, geographic coordinates).
- Vector Database (Chroma DB): Stores "chunked" versions of job listings (and ideal job listing simulations generated using HyDe) alongside their metadata. This component is central to performing semantic similarity matching.
- Storage & Local Data Management: Responsible for storing parsed emails, resumes, results, and the vector databases. According to the README, all these local data files are kept within a specific folder structure (e.g., user_data/email_folders, resumes, results, vdbs, and created_databases.json).

##### Emphasizing Storage-to-Vector DB Connection
- Reverse flow where query results from the Vector DB are used to fetch and update local matching results.

##### Architectural Patterns & Design Principles
- Modularity: Different modules handle ingestion, parsing, query generation, and matching.
- Layered Design: Separate the presentation layer (TUI) from the application logic (email parsing, resume summarization, query writer, etc.) and data layer (local storage and vector DB).
- Separation of Concerns: Each module (e.g., competence_matching, vdb) has a dedicated responsibility as shown in the project file tree.
- Data Flow Combination: The initial filtering uses structured metadata before applying semantic matching via HyDe, ensuring a robust two-stage result retrieval process.

##### Relevant Technologies and Frameworks
- Llama (for local LLM inference).
- Chroma (for vector database indexing).
- Langchain (for LLM integrations).
- Geopy (for converting location data into coordinates).
- Docling (for PDF parsing).
- Python with a modular file structure spread across scr/competence_matching and scr/vdb.

##### Detailed Connections
- Data ingestion flows from “email/resume storage” into the vector DB for indexing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        A["Terminal User Interface (TUI)"]:::ui
    end

    %% Processing Modules Layer
    subgraph "Processing Modules"
        B["Email Collection & Ingestion Module"]:::mod
        C["Resume Parsing and Summarization Module"]:::mod
        D["LLM-Based Query Writer"]:::mod
    end

    %% Data and Storage Layer
    subgraph "Data & Storage"
        E["Local Storage & Data Management"]:::storage
        F["Vector Database (Chroma DB)"]:::db
        G["Matching Engine & Result Sorter"]:::mod
    end

    %% Connections from User Interface to Processing Modules
    A -->|"initiates"| B
    A -->|"initiates"| C

    %% Connections within Processing Modules
    B -->|"sends_input"| D
    C -->|"sends_input"| D
    B -->|"stores"| E
    C -->|"stores"| E

    %% LLM Query Writer interacts with the Vector Database
    D -->|"queries"| F

    %% Direct Storage to Vector DB connection
    E -->|"indexes"| F

    %% Vector DB to Matching Engine and back to Storage
    F -->|"matches"| G
    G -->|"updates"| E

    %% Matching Engine sends results back to the UI
    G -->|"displays"| A

    %% Styling: Colors for each component layer
    classDef ui fill:#ff9999,stroke:#cc0000,stroke-width:2px;
    classDef mod fill:#99ccff,stroke:#3366ff,stroke-width:2px;
    classDef storage fill:#ccffcc,stroke:#33cc33,stroke-width:2px;
    classDef db fill:#ffe066,stroke:#ff8000,stroke-width:2px;

    %% Click Events for Components with Mapped Paths
    click A "https://github.com/leonnorblad/competencematching/blob/main/main.py"
    click B "https://github.com/leonnorblad/competencematching/blob/main/scr/competence_matching/matching.py"
    click C "https://github.com/leonnorblad/competencematching/blob/main/scr/utils.py"
    click D "https://github.com/leonnorblad/competencematching/blob/main/scr/competence_matching/prompts.py"
    click D "https://github.com/leonnorblad/competencematching/blob/main/scr/vdb/prompts.py"
    click E "https://github.com/leonnorblad/competencematching/tree/main/example_data"
    click F "https://github.com/leonnorblad/competencematching/blob/main/scr/vdb/vdb.py"
```
