# mr-aicoder/hirecopilot--automatic_hiring_agent architecture

> Architecture diagram of the GitHub repository mr-aicoder/hirecopilot--automatic_hiring_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-aicoder/hirecopilot--automatic_hiring_agent
- Repository: https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-agent AI application with a Streamlit UI, LangGraph orchestrator, LangChain agents, a local database, and external LLM/knowledge-base integrations.
- Primary purpose: automate hiring workflows (JD generation, resume screening, interview prep).

##### Main Components
A. User Interface (Streamlit)
- Entry point: `main.py` (invoked via `streamlit run app.py`)
- Handles user inputs: job title form, resume file uploads, candidate selection dropdown
B. Orchestration Layer (LangGraph Pipelines)
- `graphs/jd_graph.py` → JD-generation pipeline
- `graphs/screening_graph.py` → resume-screening pipeline
C. Agent Modules (LangChain Agents)
- MarketResearchAgent
- JDCrafterAgent
- InclusivityAgent
- ResumeParserAgent
- ScreeningAgent
- SummarizerAgent
- InterviewQuestionAgent
D. Utility Layer
- `utils/llm_provider.py` → abstracts LLM API calls (OpenAI, Google)
- `utils/output_parsers.py` → post-processes agent outputs into structured data
- `utils/database.py` → CRUD on SQLite (`hirecopilot.db`)
E. Data Stores & Knowledge Base
- Local SQLite database (`hirecopilot.db`) to persist JDs, parsed resumes, scores, summaries
- RAG knowledge base (`rag_source/inclusivity_knowledge_base.md`) used by InclusivityAgent
F. External Services
- OpenAI API (text generation, embedding)
- Google API (market research)

##### Interactions & Data Flow
1. User → Streamlit UI
- Submits job title → triggers JD pipeline
- Uploads resumes → triggers screening pipeline
- Selects candidate → triggers interview-prep pipeline
2. UI → Graph Orchestrator
- Calls the appropriate pipeline graph module
3. Orchestrator → Agents
- Each pipeline node invokes one or more agent modules
- Agents use `llm_provider` to call LLMs and `output_parsers` to structure results
- InclusivityAgent also reads the RAG knowledge-base markdown
4. Agents → Database
- Parsed and scored data is stored/retrieved via `utils/database.py`
5. UI ← Orchestrator
- Renders final outputs: generated JD text, screening scores & rationale, interview questions

##### Architectural Patterns & Principles
- “Separation of Concerns”: UI / Orchestration / Agents / Data-access are distinct layers
- Directed pipelines (DAG style) via LangGraph for composable workflows
- Stateless agents with side-effects (DB writes) managed centrally
- RAG integration for domain-specific knowledge
- Modular design: easily add/remove agents or new pipelines

##### Essential Labels & Notations
- Component names exactly as in code (e.g., `JDCrafterAgent`, `utils/database.py`)
- Pipelines named “JD Generation Pipeline” and “Resume Screening Pipeline”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI["Streamlit UI\nmain.py"]:::ui
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        JD_Pipeline["JD Generation Pipeline\n(graphs/jd_graph.py)"]:::orchestrator
        Screening_Pipeline["Resume Screening Pipeline\n(graphs/screening_graph.py)"]:::orchestrator
        Interview_Pipeline["Interview Prep Pipeline"]:::orchestrator
    end

    %% Agents
    subgraph "Agents"
        MR["MarketResearchAgent"]:::agent
        JD["JDCrafterAgent"]:::agent
        IN["InclusivityAgent"]:::agent
        RP["ResumeParserAgent"]:::agent
        SC["ScreeningAgent"]:::agent
        SU["SummarizerAgent"]:::agent
        IQ["InterviewQuestionAgent"]:::agent
    end

    %% Utility Layer
    subgraph "Utility Layer"
        LP["LLM Provider\n(utils/llm_provider.py)"]:::util
        OP["Output Parsers\n(utils/output_parsers.py)"]:::util
        DBUtil["Database Access\n(utils/database.py)"]:::util
    end

    %% Data Stores
    subgraph "Data Stores"
        SQL["SQLite DB\nhirecopilot.db"]:::data
        RAG["RAG Knowledge Base\ninclusivity_knowledge_base.md"]:::data
    end

    %% External Services
    subgraph "External Services"
        OA["OpenAI API"]:::external
        GA["Google API"]:::external
    end

    %% User interactions
    UI -->|"job title"| JD_Pipeline
    UI -->|"resume PDF"| Screening_Pipeline
    UI -->|"selected candidate"| Interview_Pipeline

    %% Orchestrator to Agents
    JD_Pipeline -->|"invoke"| MR
    JD_Pipeline -->|"invoke"| JD
    JD_Pipeline -->|"invoke"| IN

    Screening_Pipeline -->|"invoke"| RP
    Screening_Pipeline -->|"invoke"| SC
    Screening_Pipeline -->|"invoke"| SU

    Interview_Pipeline -->|"invoke"| IQ

    %% Agents to Utilities and Data
    MR --> LP
    JD --> LP
    IN --> LP
    RP --> LP
    SC --> LP
    SU --> LP
    IQ --> LP

    MR --> OP
    JD --> OP
    IN --> OP
    RP --> OP
    SC --> OP
    SU --> OP
    IQ --> OP

    IN --> RAG

    MR --> DBUtil
    JD --> DBUtil
    IN --> DBUtil
    RP --> DBUtil
    SC --> DBUtil
    SU --> DBUtil
    IQ --> DBUtil

    %% Utilities to External
    LP --> OA
    LP --> GA

    %% Pipelines back to UI
    JD_Pipeline -->|"JD draft"| UI
    Screening_Pipeline -->|"scores/rationale"| UI
    Interview_Pipeline -->|"interview questions"| UI

    %% Click Events
    click UI "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/main.py"
    click JD_Pipeline "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/graphs/jd_graph.py"
    click Screening_Pipeline "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/graphs/screening_graph.py"
    click MR "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/market_research_agent.py"
    click JD "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/jd_crafter_agent.py"
    click IN "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/inclusivity_agent.py"
    click RP "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/resume_parser_agent.py"
    click SC "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/screening_agent.py"
    click SU "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/summerizer_agent.py"
    click IQ "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/agents/interview_question_agent.py"
    click LP "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/utils/llm_provider.py"
    click OP "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/utils/output_parsers.py"
    click DBUtil "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/utils/database.py"
    click SQL "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/hirecopilot.db"
    click RAG "https://github.com/mr-aicoder/hirecopilot--automatic_hiring_agent/blob/main/rag_source/inclusivity_knowledge_base.md"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef orchestrator fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef agent fill:#fff3cd,stroke:#333,stroke-width:1px,rx:5,ry:5;
    classDef util fill:#f8d7da,stroke:#333,stroke-width:1px;
    classDef data fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
