# marcocamilo/ai-resume-alignment-engine architecture

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

- Interactive diagram: https://gitdiagram.com/marcocamilo/ai-resume-alignment-engine
- Repository: https://github.com/marcocamilo/ai-resume-alignment-engine

## Overview

##### Project type and purpose
- This is a single‐page, full-stack Python web application (Streamlit) that implements an AI-powered resume alignment engine.

##### File structure
- Top-level
- app.py: Streamlit entrypoint, glues everything together
- requirements.txt, pyrightconfig.json: Python dependencies and type-checking config
- src/
- modules/
– nlp.py: text preprocessing, tokenization, similarity checks
– utils.py: shared utilities (e.g., file I/O, logging)
- templates/
– prompts.py: prompt templates for evaluation and optimization chains
– meta.py: chain configuration and LangChain instantiation
- description/: sample job-description markdown files
- resume/: sample resume markdown files
- No separate “backend” directory—app.py invokes src modules directly. No persistent database; data flows in memory.

##### Extract architectural insights from README
- Streamlit UI for user interaction
- Input Processing → AI Analysis (Gemini + LangChain) → Resume Evaluation Chains → Optimization Chains → Visualization (word clouds, tables)
- External service: Google Gemini API
- Core frameworks: Streamlit, LangChain, Google Cloud SDK

##### Main components and their interactions
a. Components
1) Streamlit Frontend (app.py)
2) Input Handler / Preprocessor (src/modules/nlp.py)
3) Chain Orchestrator (src/templates/meta.py + prompts.py)
4) External LLM Service (Google Gemini API)
5) Postprocessor & Visualizer (word-cloud generation, result formatting)
6) Static Samples (src/description, src/resume)
b. Relationships & data flow
- User ⇨ Streamlit UI ⇨ Input Handler
- Preprocessed text ⇨ LangChain orchestrator
- Orchestrator ⇨ Gemini API calls ⇨ LLM responses
- Responses ⇨ Postprocessor (score calculation, recommendation generation)
- Postprocessor ⇨ Visual components (word clouds, tables) ⇨ Streamlit UI
c. Architectural patterns / design principles
- Single-process service with modular code separation (UI vs. domain logic vs. templates vs. I/O)
- Pipeline style: clear stages (preprocessing → analysis → optimization → visualization)
- Prompt engineering via templated prompts and chain-of-thought orchestration (LangChain)
d. Key technologies / frameworks / libraries
- Streamlit (UI)
- LangChain (chain orchestration)
- Google Gemini API (LLM)
- Python modules: nlp, utils, prompts, meta
- Word-cloud or plotting library for visualization

##### Detailed breakdown
- Labels for each micro-module (e.g., “Prompt Templates,” “Chain Config,” “Resume Preprocessor”)
- Retry/fallback logic if the Gemini API fails (optional)
- Optional: annotate performance metrics (e.g., “20s average runtime”) on the data flows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and UI
    User((User)):::external
    User -->|interacts with| UI["Streamlit UI"]:::ui

    %% Static Samples
    subgraph "Static Samples"
        direction TB
        JD["Job Descriptions"]:::data
        RS["Resume Samples"]:::data
    end
    JD -.->|optional input| NLP
    RS -.->|optional input| NLP

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        NLP["Resume Preprocessor"]:::processing
        Utils["Shared Utilities"]:::processing
        Templates["Prompt Templates"]:::processing
        Meta["Chain Orchestrator"]:::processing
        EC["Evaluation Chain"]:::processing
        OC["Optimization Chain"]:::processing
    end

    %% External Service
    Gemini["Google Gemini API"]:::external

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        Post["Postprocessor & Visualizer"]:::viz
        VC["Visual Components"]:::viz
    end

    %% Data Flows
    UI -->|raw text| NLP
    NLP -->|preprocessed text| Meta
    Utils -->|shared services| NLP
    Utils -->|shared services| Meta
    Templates -->|prompt templates| Meta
    Meta -->|runs evaluation| EC
    Meta -->|runs optimization| OC
    EC -->|LLM request| Gemini
    OC -->|LLM request| Gemini
    Gemini -->|LLM response| EC
    Gemini -->|LLM response| OC
    EC -->|evaluation results| Post
    OC -->|optimization results| Post
    Post -->|visual data| VC
    VC -->|renders| UI

    %% Retry/Fallback
    Gemini -.->|error| Meta

    %% Click Events
    click UI "https://github.com/marcocamilo/ai-resume-alignment-engine/blob/main/app.py"
    click NLP "https://github.com/marcocamilo/ai-resume-alignment-engine/blob/main/src/modules/nlp.py"
    click Utils "https://github.com/marcocamilo/ai-resume-alignment-engine/blob/main/src/modules/utils.py"
    click Templates "https://github.com/marcocamilo/ai-resume-alignment-engine/blob/main/src/templates/prompts.py"
    click Meta "https://github.com/marcocamilo/ai-resume-alignment-engine/blob/main/src/templates/meta.py"
    click JD "https://github.com/marcocamilo/ai-resume-alignment-engine/tree/main/src/description/"
    click RS "https://github.com/marcocamilo/ai-resume-alignment-engine/tree/main/src/resume/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000;
    classDef processing fill:#D1FFD0,stroke:#000;
    classDef external fill:#FFD5A3,stroke:#000;
    classDef data fill:#E0E0E0,stroke:#000;
    classDef viz fill:#EAD1DC,stroke:#000;
    class User external
    class Gemini external
```
