# gaurav-kumar98/cvinsight architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav-kumar98/cvinsight
- Repository: https://github.com/gaurav-kumar98/cvinsight

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based resume analysis tool with a plugin-based architecture.
- Purpose: Ingest PDF/DOCX resumes, extract structured data (profile, skills, education, experience, years of experience) via LLMs (Google’s Gemini), and emit JSON outputs while tracking token usage and logging.

##### File Structure Analysis
- Top-Level Scripts:
- main.py – CLI entry point
- resume_processor.py – Orchestrates resume processing
- llm_service.py – Wraps LLM API calls
- Configuration & Constants:
- config.py / .env – Environment and runtime parameters
- constants.py – Shared constants
- Plugin Subsystems:
- base_plugins/ – Abstract BasePlugin and built-in extractors
- custom_plugins/ – User-provided plugins extending BasePlugin
- plugins/ – Loader, registry, and plugin config
- Utilities: utils/ – File I/O, cleanup, date parsing, logging helpers
- Models: models/ – Resume and plugin data schemas
- Documentation: docs/wiki/ – Design, usage, and extension guides
- Resumes/ – Sample inputs
- Results & Logs (configured at runtime)

##### Key Architectural Insights from README
- Plugin Manager dynamically discovers and loads all plugins (both built-in and custom)
- Concurrent processing: resumes are processed in parallel across extractors
- LLM interaction is centralized via llm_service.py
- Token usage is tracked per plugin and logged separately, with rotation and retention policies

##### Components
a. Input Layer
- Resume Files (PDF/DOCX) in Resumes/ folder
- Configuration (.env, config.py)
b. Orchestration Layer
- CLI main.py
- ResumeProcessor
- PluginManager / plugins.loader
c. Processing Layer
- BasePlugin Implementations (Profile, Skills, Education, Experience, YoE)
- CustomPlugins (keyword_matcher, etc.)
- llm_service (handles REST/gRPC calls to Gemini LLM)
d. Data & Storage Layer
- JSON Results Directory
- Logs Directory (token usage logs, application logs)
- Models for structured data (models/resume_models.py)
e. Utilities & Support
- utils for cleanup, file operations, logging, date parsing
f. External Services
- Google Gemini LLM API

##### Relationships and Interactions
- main.py → ResumeProcessor triggers processing for each resume
- ResumeProcessor → PluginManager loads plugins; for each plugin:
- Plugin → llm_service (synchronous or async API call)
- llm_service → External LLM API → llm_service → Plugin
- Plugin outputs → ResumeProcessor aggregates into final JSON
- ResumeProcessor writes to Results/ and emits token usage to Logs/
- Utility modules are used at various stages (file reading, logging, cleanup)

##### Architectural Patterns and Design Principles
- Plugin Pattern: Decouples core orchestration from extractors
- Dependency Injection: Config and constants injected into services
- Concurrency: Parallel execution of plugins to improve throughput
- Single Responsibility: Separate modules for orchestration, LLM interaction, file I/O, logging
- Config-Driven: .env and config.py drive runtime behavior

##### Technologies, Frameworks, and Libraries
- Python 3.x
- Google Gemini LLM (via REST/gRPC)
- python-docx (for DOCX parsing), pdfminer or similar (for PDF)
- Standard logging module with rotation handlers
- argparse or click for CLI
- concurrent.futures or asyncio for parallelism

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        Resumes["Resume Files (PDF/DOCX)"]:::input
        EnvFile[".env.example"]:::input
        ConfigPy["config.py"]:::input
        ConstantsPy["constants.py"]:::input
        PluginsConfig["plugins/config.py"]:::input
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        CLI["main.py"]:::orchestration
        Processor["resume_processor.py"]:::orchestration
        subgraph "Plugin Manager"
            PM_Base["base_plugins/plugin_manager.py"]:::orchestration
            PM_Loader["plugins/loader.py"]:::orchestration
            PM_Registry["plugins/registry.py"]:::orchestration
        end
    end

    %% Processing Layer
    subgraph "Processing Layer"
        subgraph "Parallel Execution"
            ProfileExt["ProfileExtractor"]:::plugin
            SkillsExt["SkillsExtractor"]:::plugin
            EducationExt["EducationExtractor"]:::plugin
            ExperienceExt["ExperienceExtractor"]:::plugin
            YoEExt["YoEExtractor"]:::plugin
            CustomExt["CustomPlugin: keyword_matcher"]:::plugin
        end
        LLMService["llm_service.py"]:::plugin
    end

    %% Data & Storage Layer
    subgraph "Data & Storage Layer"
        ResultsDir["JSON Results Directory"]:::storage
        LogsDir["Logs Directory"]:::storage
        DataModels["models/resume_models.py"]:::storage
    end

    %% Utilities & Support
    subgraph "Utilities & Support"
        FileUtils["utils/file_utils.py"]:::utilities
        Cleanup["utils/cleanup.py"]:::utilities
        DateUtils["utils/date_utils.py"]:::utilities
        CommonUtil["utils/common.py"]:::utilities
        LogUtil["utils/log_utils.py"]:::utilities
        LoggingUtil["utils/logging_utils.py"]:::utilities
    end

    %% External Services
    Gemini["Google Gemini LLM API"]:::external

    %% Data Flows
    Resumes -->|raw files| CLI
    EnvFile -->|config| CLI
    ConfigPy --> CLI
    ConstantsPy --> CLI
    PluginsConfig --> CLI

    CLI -->|"start processing"| Processor
    Processor -->|load plugins| PM_Base
    Processor --> PM_Loader
    Processor --> PM_Registry

    PM_Loader -->|provides plugin list| ProfileExt
    PM_Loader --> SkillsExt
    PM_Loader --> EducationExt
    PM_Loader --> ExperienceExt
    PM_Loader --> YoEExt
    PM_Loader --> CustomExt

    ProfileExt -->|prompt/response| LLMService
    SkillsExt --> LLMService
    EducationExt --> LLMService
    ExperienceExt --> LLMService
    YoEExt --> LLMService
    CustomExt --> LLMService

    LLMService -->|LLM call| Gemini
    Gemini -->|response| LLMService
    LLMService -->|parsed response| ProfileExt
    LLMService --> SkillsExt
    LLMService --> EducationExt
    LLMService --> ExperienceExt
    LLMService --> YoEExt
    LLMService --> CustomExt

    ProfileExt -->|extracted data| Processor
    SkillsExt --> Processor
    EducationExt --> Processor
    ExperienceExt --> Processor
    YoEExt --> Processor
    CustomExt --> Processor

    Processor -->|JSON output| ResultsDir
    Processor -->|token usage logs| LogsDir

    %% Utilities connections (dashed)
    FileUtils -.-> CLI
    FileUtils -.-> Processor
    Cleanup -.-> Processor
    DateUtils -.-> ProfileExt
    CommonUtil -.-> CustomExt
    LogUtil -.-> Processor
    LoggingUtil -.-> LLMService

    %% Click Events
    click Resumes "https://github.com/gaurav-kumar98/cvinsight/tree/main/Resumes/"
    click EnvFile "https://github.com/gaurav-kumar98/cvinsight/blob/main/.env.example"
    click ConfigPy "https://github.com/gaurav-kumar98/cvinsight/blob/main/config.py"
    click ConstantsPy "https://github.com/gaurav-kumar98/cvinsight/blob/main/constants.py"
    click PluginsConfig "https://github.com/gaurav-kumar98/cvinsight/blob/main/plugins/config.py"
    click CLI "https://github.com/gaurav-kumar98/cvinsight/blob/main/main.py"
    click Processor "https://github.com/gaurav-kumar98/cvinsight/blob/main/resume_processor.py"
    click PM_Base "https://github.com/gaurav-kumar98/cvinsight/blob/main/base_plugins/plugin_manager.py"
    click PM_Loader "https://github.com/gaurav-kumar98/cvinsight/blob/main/plugins/loader.py"
    click PM_Registry "https://github.com/gaurav-kumar98/cvinsight/blob/main/plugins/registry.py"
    click ProfileExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/base_plugins/profile_extractor/"
    click SkillsExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/base_plugins/skills_extractor/"
    click EducationExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/base_plugins/education_extractor/"
    click ExperienceExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/base_plugins/experience_extractor/"
    click YoEExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/base_plugins/yoe_extractor/"
    click CustomExt "https://github.com/gaurav-kumar98/cvinsight/tree/main/custom_plugins/keyword_matcher/"
    click LLMService "https://github.com/gaurav-kumar98/cvinsight/blob/main/llm_service.py"
    click DataModels "https://github.com/gaurav-kumar98/cvinsight/blob/main/models/resume_models.py"
    click FileUtils "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/file_utils.py"
    click Cleanup "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/cleanup.py"
    click DateUtils "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/date_utils.py"
    click CommonUtil "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/common.py"
    click LogUtil "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/log_utils.py"
    click LoggingUtil "https://github.com/gaurav-kumar98/cvinsight/blob/main/utils/logging_utils.py"

    %% Styles
    classDef input fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef orchestration fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef plugin fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef storage fill:#e3f2fd,stroke:#0d47a1,color:#1565c0
    classDef utilities fill:#f1f8e9,stroke:#33691e,color:#558b2f
    classDef external fill:#f3e5f5,stroke:#4a148c,color:#6a1b9a
```
