# kvj-harsha/smarthire architecture

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

- Interactive diagram: https://gitdiagram.com/kvj-harsha/smarthire
- Repository: https://github.com/kvj-harsha/smarthire

## Overview

##### Project Type and Purpose
- This is a full-stack AI-powered data pipeline application with two primary facets:
- A backend “orchestrator” pipeline that ingests candidate and job data, invokes AI modules (agents), and produces Talent Intelligence Reports (TIRs).
- A Streamlit-based frontend dashboard for visualizing profiles, match analyses, behavioral insights, and market intelligence.

##### File Structure
- Top-level entries:
- agents/ – four AI modules (candidate_profiler, assessment_designer, behavioral_analyzer, market_optimizer)
- app/orchestrator.py – main pipeline runner
- app.py and pages/ – Streamlit dashboard entry point and multipage views (assessment, behaviour, data-viewer, market, profile)
- data/ – raw input JSONs (resume, LinkedIn, GitHub, LeetCode, JD, textual evidence)
- talent-intelligence-report/ – generated JSON outputs (orchestrated data and final TIRs)
- requirements.txt and .env – dependencies and environment variables (e.g., GROQ_API_KEY)

##### Extract Insights from README
- Backend flow: load data → run profiling, behavioral analysis, assessment design, market intelligence → save both “_orchestrated” and final “TIR_” outputs.
- Frontend: streamlit run app.py uses pages/ to display results.
- Technologies: Python, Groq LLM API, python-dotenv, Streamlit.

##### Main Components
a. Data Sources Layer
- Local JSON data files (data/, representing resume, LinkedIn, GitHub, LeetCode, JD, candidate_text)
- Environment variables store API keys
b. Orchestrator Pipeline
- app/orchestrator.py
- Invokes agent modules sequentially or in parallel:
- Candidate Profiler (agents/candidate_profiler.py)
- Behavioral Analyzer (agents/behavioral_analyzer.py)
- Assessment Designer (agents/assessment_designer.py)
- Market Optimizer (agents/market_optimizer.py)
- Calls external Groq LLM API for AI processing
- Outputs saved to talent-intelligence-report/
c. Storage Layer
- talent-intelligence-report/ (orchestrated and TIR outputs)
d. Visualization Layer (Streamlit Dashboard)
- app.py (Streamlit entry)
- pages/… (five pages for each functional area)
- Reads from talent-intelligence-report/ or data/ for live rendering
e. External Service
- Groq LLM API (AI inference engine)

##### Relationships and Data Flow
- User interacts with Dashboard, which triggers page logic to fetch stored outputs

##### Architectural Patterns and Principles
- Pipeline orchestration pattern: sequential/parallel execution of discrete “agent” components
- Clear separation of concerns: data ingestion, AI modules, reporting storage, visualization
- Config via environment (.env) and requirements.txt for dependency management
- Modular code layout to enable easy extension (add new agents or pages)

##### Technologies and Frameworks to Label
- Python 3.x, python-dotenv
- Streamlit (frontend)
- Local filesystem for JSON storage

##### Specific Elements
- Clear labels for each module (with file paths or names)
- Blue for backend components
- Green for data stores
- Orange for external services
- Purple for frontend/UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources Layer
    subgraph "Data Sources Layer"
        DS["Local JSON Data\n(data/)"]:::storage
    end

    %% Orchestrator Pipeline
    subgraph "Orchestrator Pipeline"
        OR["Orchestrator\napp/orchestrator.py"]:::backend
        ENV["Environment Variables\n(.env)"]:::backend
        subgraph "Agents"
            CP["Candidate Profiler\nagents/candidate_profiler.py"]:::backend
            BA["Behavioral Analyzer\nagents/behavioral_analyzer.py"]:::backend
            AD["Assessment Designer\nagents/assessment_designer.py"]:::backend
            MO["Market Optimizer\nagents/market_optimizer.py"]:::backend
        end
    end

    %% External Service
    GROQ["Groq LLM API"]:::external

    %% Storage Layer
    subgraph "Storage Layer"
        REP["Talent Intelligence Reports\n(talent-intelligence-report/)"]:::storage
    end

    %% Visualization Layer
    subgraph "Streamlit Dashboard"
        APP["Streamlit App\napp.py"]:::ui
        PAG1["assessment.py"]:::ui
        PAG2["behaviour.py"]:::ui
        PAG3["data-viewer.py"]:::ui
        PAG4["market.py"]:::ui
        PAG5["profile.py"]:::ui
    end

    %% Connections
    DS -->|"load data"| OR
    ENV -->|"config for API"| OR

    OR -->|"invoke"| CP
    OR -->|"invoke"| BA
    OR -->|"invoke"| AD
    OR -->|"invoke"| MO

    CP -->|"invoke AI inference"| GROQ
    BA -->|"invoke AI inference"| GROQ
    AD -->|"invoke AI inference"| GROQ
    MO -->|"invoke AI inference"| GROQ

    GROQ -->|"AI response"| CP
    GROQ -->|"AI response"| BA
    GROQ -->|"AI response"| AD
    GROQ -->|"AI response"| MO

    CP -->|"write JSON report"| REP
    BA -->|"write JSON report"| REP
    AD -->|"write JSON report"| REP
    MO -->|"write JSON report"| REP

    REP -->|"read report for UI"| APP
    REP -->|"read report for UI"| PAG1
    REP -->|"read report for UI"| PAG2
    REP -->|"read report for UI"| PAG3
    REP -->|"read report for UI"| PAG4
    REP -->|"read report for UI"| PAG5

    APP -->|"loads pages"| PAG1
    APP -->|"loads pages"| PAG2
    APP -->|"loads pages"| PAG3
    APP -->|"loads pages"| PAG4
    APP -->|"loads pages"| PAG5

    %% Click Events
    click DS "https://github.com/kvj-harsha/smarthire/tree/master/data/"
    click OR "https://github.com/kvj-harsha/smarthire/blob/master/app/orchestrator.py"
    click CP "https://github.com/kvj-harsha/smarthire/blob/master/agents/candidate_profiler.py"
    click BA "https://github.com/kvj-harsha/smarthire/blob/master/agents/behavioral_analyzer.py"
    click AD "https://github.com/kvj-harsha/smarthire/blob/master/agents/assessment_designer.py"
    click MO "https://github.com/kvj-harsha/smarthire/blob/master/agents/market_optimizer.py"
    click REP "https://github.com/kvj-harsha/smarthire/tree/master/talent-intelligence-report/"
    click APP "https://github.com/kvj-harsha/smarthire/blob/master/app.py"
    click PAG1 "https://github.com/kvj-harsha/smarthire/blob/master/pages/assessment.py"
    click PAG2 "https://github.com/kvj-harsha/smarthire/blob/master/pages/behaviour.py"
    click PAG3 "https://github.com/kvj-harsha/smarthire/blob/master/pages/data-viewer.py"
    click PAG4 "https://github.com/kvj-harsha/smarthire/blob/master/pages/market.py"
    click PAG5 "https://github.com/kvj-harsha/smarthire/blob/master/pages/profile.py"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ui fill:#DDA0DD,stroke:#333,stroke-width:1px
```
