# ghoumbadji/jobmatcher-ai architecture

> Architecture diagram of the GitHub repository ghoumbadji/jobmatcher-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghoumbadji/jobmatcher-ai
- Repository: https://github.com/ghoumbadji/jobmatcher-ai

## Overview

This is a **single-repo, single-process Streamlit application** that runs locally (or on Streamlit Cloud) and provides **career/job-fit recommendations** based on:
- A **questionnaire UI** (Streamlit)
- A **semantic scoring engine** (SentenceTransformers embeddings + weighted scoring)
- An **LLM narrative layer** (Google Gemini via API) for personalized written guidance
- Supporting **NLP preprocessing** (NLTK)

So the “system” is not microservices; it’s a **modular Python app** with a clear runtime workflow and one notable external dependency: **Gemini API**.

- **Runtime flow** from UI → preprocessing → embedding/scoring → visualization → LLM recommendation
- **Module boundaries** aligned to files (`main.py`, `job_matcher.py`, `preprocessing.py`, `genai_recommender.py`)
- **External systems** (Gemini API, optionally model download/huggingface cache, NLTK data download)
- **Secrets/config** (`.streamlit/secrets.toml`)

##### Domain / Decision Engine
**`job_matcher.py` (Core scoring engine)**
- Owns: job profiles (Data Analyst/Scientist/Engineer/ML Eng), skill categories, weights, similarity calculations, aggregation into final scores.

##### NLP Utilities
**`preprocessing.py`**
- Owns: normalization pipeline (lowercasing, tokenization, lemmatization, stopword handling).

##### Generative AI Layer
**`genai_recommender.py`**
- Owns: constructing prompt, selecting Gemini model, calling Google Generative AI client, parsing/formatting response.

- **`requirements.txt`** → technologies used.
- **`.streamlit/secrets.toml`** (mentioned in README, not shown in file tree) → config store for `GEMINI_API_KEY`.
- **SentenceTransformer model** `all-mpnet-base-v2` → may be downloaded/cached at runtime.
- **NLTK corpora/resources** (stopwords, punkt, wordnet) → may be downloaded/cached.

These are worth showing as “runtime resources” because they affect deployment and first-run behavior.

##### Scores → `main.py` → Plotly charts + tables
5. Scores + best-match + rationale inputs → `main.py` → **Gemini recommender (`genai_recommender.py`)**

##### How to show boundaries
- **Container: “JobMatcher AI (Python/Streamlit app)”**
- Contains: main.py, job_matcher.py, preprocessing.py, genai_recommender.py
- **External container: “Google Cloud / Gemini API”**
- **Local runtime resources**: model cache + NLTK datasets

##### Extra details worth annotating (because they affect architecture)
- **Model selection**: SentenceTransformer `all-mpnet-base-v2` (embedding generation)
- **Gemini model variants**: “2.5 Flash or 2.0 Flash” (dynamic loading)
- **Privacy**: responses not stored; only sent to Gemini for generation
- **Deployment**: local/Streamlit Cloud; secrets via `.streamlit/secrets.toml`

That combination captures both *what it is* (modules + boundaries) and *how it works* (the user-to-output pipeline).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context + Containers (Vertical)
    %% =========================
    U["User"]:::actor

    subgraph R["Execution Runtime (Local Machine / Streamlit Cloud)"]
        direction TB

        subgraph APP["JobMatcher AI (Single-process Python + Streamlit)"]
            direction TB

            MAIN["Streamlit App (main.py)\nUI + Session State + Orchestration"]:::internal

            PRE["NLP Preprocessing (preprocessing.py)\nNormalize: tokenize/lemmatize/stopwords"]:::internal

            JM["Job Matching Engine (job_matcher.py)\nWeighted semantic scoring + aggregation"]:::internal

            GEN["Gemini Recommender (genai_recommender.py)\nPrompting + API client + formatting"]:::internal

            REQ["Python Dependencies (requirements.txt)\nstreamlit/plotly/nltk/sentence-transformers/google-genai"]:::support
            DOC["Project Docs (README.md)\nSetup + architecture notes"]:::support
        end

        subgraph RES["Local Runtime Resources (download/cache on first run)"]
            direction TB
            STMODEL[("SentenceTransformer Model Cache\nall-mpnet-base-v2")]:::resource
            NLTK[("NLTK Data Cache\nstopwords/punkt/wordnet")]:::resource
            SECRETS["Secrets/Config\n.streamlit/secrets.toml\nGEMINI_API_KEY"]:::config
        end
    end

    subgraph EXT["External Systems"]
        direction TB
        GEM["Google Gemini API\n(2.5 Flash / 2.0 Flash)"]:::external
    end

    NOTE1["Pattern: Layered modular design\nUI/Orchestration → NLP utils → Scoring engine → LLM adapter"]:::note
    NOTE2["Privacy: Local-first scoring\nOnly prompt data sent to Gemini for narrative generation"]:::note
    NOTE3["Deterministic scoring + probabilistic narrative\nWeighted similarity drives ranking; LLM explains/coaches"]:::note

    %% =========================
    %% Runtime Dataflow (end-to-end)
    %% =========================
    U -->|"Questionnaire responses (raw text)"| MAIN
    MAIN -->|"Raw answers"| PRE
    PRE -->|"Cleaned text / normalized tokens"| JM
    JM -->|"Embeddings + similarity per category"| STMODEL
    PRE -->|"Uses tokenizer/lemmatizer/stopwords"| NLTK
    JM -->|"Final affinity scores + best match"| MAIN
    MAIN -->|"Plotly charts + tables"| U
    MAIN -->|"Prompt inputs (scores + profile + user context)"| GEN
    GEN -->|"Reads key"| SECRETS
    GEN -->|"HTTPS request (prompt)"| GEM
    GEM -->|"Generated recommendation text"| GEN
    GEN -->|"Narrative recommendation"| MAIN
    MAIN -->|"Final guidance + next steps"| U

    %% =========================
    %% Static Dependencies (dashed)
    %% =========================
    MAIN -.->|"calls"| JM
    MAIN -.->|"calls"| GEN
    JM -.->|"uses"| PRE
    JM -.->|"uses"| STMODEL
    PRE -.->|"uses"| NLTK
    GEN -.->|"uses"| SECRETS
    GEN -.->|"calls"| GEM
    MAIN -.->|"runtime deps"| REQ
    APP -.->|"reference"| DOC

    NOTE1 -.-> APP
    NOTE2 -.-> GEN
    NOTE3 -.-> JM

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click MAIN "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/main.py"
    click JM "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/job_matcher.py"
    click PRE "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/preprocessing.py"
    click GEN "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/genai_recommender.py"
    click REQ "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/requirements.txt"
    click DOC "https://github.com/ghoumbadji/jobmatcher-ai/blob/main/README.md"

    %% =========================
    %% Styles (Color-coded)
    %% =========================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2,color:#111827
    classDef internal fill:#dbeafe,stroke:#1d4ed8,stroke-width:2,color:#0f172a
    classDef support fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5,color:#0f172a
    classDef resource fill:#e5e7eb,stroke:#374151,stroke-width:1.5,color:#111827
    classDef config fill:#dcfce7,stroke:#16a34a,stroke-width:2,color:#052e16
    classDef external fill:#ffedd5,stroke:#c2410c,stroke-width:2,color:#7c2d12
    classDef note fill:#fef9c3,stroke:#a16207,stroke-width:1.5,color:#713f12
```
