# joe-hireable/hireablecvparser architecture

> Architecture diagram of the GitHub repository joe-hireable/hireablecvparser, 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/joe-hireable/hireablecvparser
- Repository: https://github.com/joe-hireable/hireablecvparser

## Overview

##### Main components
- Cloud Function Endpoint: The front door of the service, represented by main.py that handles incoming HTTP requests.
- Configuration Module: The config.py file that holds sensitive settings like project IDs, bucket names, and allowed domains.
- Document Processing Component: Modules such as DocumentProcessor (located in utils/document_processor.py) for downloading and processing CVs and job descriptions.
- Gemini Client: The util gemini_client.py that interfaces with the Gemini AI model.
- Google Cloud Storage (GCS): Although not a code module, storage.py in the utils folder and config settings indicate integration with GCS for caching and document storage.
- Prompt and Schema Management: The data directories that host various prompt templates and JSON output schemas for different tasks (parsing, personal statement, core skills, achievements, role analysis, and scoring).

##### Relationships and interactions
- Client Request → Cloud Function Endpoint: Incoming requests (with CV and JD URLs and task type) are received by the cloud function.
- Cloud Function → Document Processor: Once a request is received, the DocumentProcessor downloads the documents (possibly validates URLs, content type, etc.).
- Document Processor ↔ GCS: Documents are uploaded and retrieved from Google Cloud Storage, with the caching mechanism to improve performance.
- Cloud Function → Gemini Client: Depending on the task (extraction, analysis, scoring), appropriate prompt templates (from data/prompts) and few-shot examples (from data/few_shot_examples) are loaded and the Gemini API is called.
- Gemini Client → AI Model (Gemini 2.0 Flash): The actual analysis and optimization is performed by the Gemini AI. The response is structured as per the JSON schema specifications (data/schemas).
- Cloud Function → Client Response: Finally, the cloud function sends a structured JSON response (including status, errors if any, and processed data).

##### Key architectural/design principles
- Modular Architecture: Separation of concerns is evident with distinct modules for configuration, document processing, cloud storage interaction, and external API integration.
- API-oriented Design: The system exposes a RESTful API endpoint designed to handle various tasks through well-defined JSON request and response formats.
- External Service Integration: The design shows a clear integration with Google Cloud services (Cloud Functions, GCS, OpenTelemetry for tracing) and external AI services.
- Extensibility: With separate directories for prompts, schemas, and examples, it is easy to extend the functionality for additional CV optimization features.
- Security & Observability: URL validation, caching, and logging (structured JSON logs plus OpenTelemetry integration) are key aspects.

##### Relevant technologies and frameworks
- Python 3.11 (runtime environment)
- Google Cloud Functions and Google Cloud Storage integration
- Gemini 2.0 Flash AI model via the API
- OpenTelemetry for tracing and structured logging

##### Specific elements
– Cloud Function (main.py) as the central entry point.
– Config : (config.py) showing global settings.
– Data Components: Prompts, Schemas, Few-shot Examples.
– External Components: Google Cloud Storage and Gemini AI service.
– Show interaction between the Cloud Function and each internal component (document processing, storage, AI processing).
– Indicate bidirectional communication where needed (e.g., caching mechanism with GCS).
- Annotations:
- Visual Differentiation:
– Consider grouping the related components (like all document processing steps) together for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Request
    A["Client Request"]:::client

    %% Internal Processing Subgraph
    subgraph "Internal Processing"
        B["Cloud Function Endpoint"]:::backend
        C["Configuration Module"]:::backend
        D["Document Processor"]:::backend
        E["Gemini Client"]:::backend
        F["Storage Handler"]:::backend
    end

    %% Data Assets Subgraph
    subgraph "Data Assets"
        G["Prompt Templates"]:::data
        H["Few-Shot Examples"]:::data
        I["JSON Schemas"]:::data
    end

    %% External Services Subgraph
    subgraph "External Services"
        J["Google Cloud Storage"]:::external
        K["Gemini AI Service"]:::external
    end

    %% Connections
    A -->|"HTTP_Request"| B
    B -->|"Load_config"| C
    B -->|"Process_document"| D
    D -->|"Cache_document"| F
    F -->|"Store/Retrieve"| J
    B -->|"Invoke_Gemini_API"| E
    E -->|"Load_prompts"| G
    E -->|"Load_few_shot"| H
    E -->|"Load_schemas"| I
    E -->|"Analyze_CV"| K
    B -->|"HTTP_Response"| A

    %% Click Events for mapped components
    click B "https://github.com/joe-hireable/hireablecvparser/blob/main/main.py"
    click C "https://github.com/joe-hireable/hireablecvparser/blob/main/config.py"
    click D "https://github.com/joe-hireable/hireablecvparser/blob/main/utils/document_processor.py"
    click E "https://github.com/joe-hireable/hireablecvparser/blob/main/utils/gemini_client.py"
    click F "https://github.com/joe-hireable/hireablecvparser/blob/main/utils/storage.py"
    click G "https://github.com/joe-hireable/hireablecvparser/tree/main/data/prompts"
    click H "https://github.com/joe-hireable/hireablecvparser/tree/main/data/few_shot_examples"
    click I "https://github.com/joe-hireable/hireablecvparser/tree/main/data/schemas"

    %% Styles
    classDef client fill:#FFCC80,stroke:#E65100,stroke-width:2px;
    classDef backend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef data fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
```
