# mindk-scrap/resumeranker architecture

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

- Interactive diagram: https://gitdiagram.com/mindk-scrap/resumeranker
- Repository: https://github.com/mindk-scrap/resumeranker

## Overview

##### Project Type and Purpose
- ResumeRanker is a backend‐only, production‐grade FastAPI service.
- It exposes REST endpoints for extracting ranking criteria from job descriptions and scoring resumes using CrewAI agents and the Groq LLM.
- No persistent database is used; results are returned directly as JSON or CSV.

##### File Structure Analysis
- Top‐level:
● app/ – FastAPI application
● requirements.txt, .env.example – dependency and configuration
- app/:
● main.py – application instantiation, middleware, router inclusion
● logger.py – centralized logging configuration
● crews/ – CrewAI agent definitions and crew configurations (YAML/JSON)
● models/ – Pydantic schema definitions for request/response models
● routes/ – three routers (criteria.py, scoring.py, pipeline.py) defining endpoints
● services/ – business logic modules: document processing, criteria extraction, resume scoring, name extraction, result formatting, crew manager
- Config:
● app/crews/config/*.yaml/.json – agent and task definitions for CrewAI
- No DB: file‐based in/out and external APIs only.

##### README Insights
- Technical stack: Python 3.11, FastAPI, Pydantic, CrewAI, Groq API, Uvicorn
- Features: PDF/DOCX ingestion, pattern matching for names, CSV export, Swagger UI
- Workflow: standalone endpoints or a combined “/rank-resumes-from-job” pipeline

a. Main Components
1. API Client (UI or HTTP client / Swagger)
2. FastAPI Application
- Routes Layer
- Services Layer
- CrewAI Manager & Agent Config
- Pydantic Models
- Logger
3. External Services
- Groq LLM Inference API
- CrewAI agent framework (runs locally/in-process)
4. Output Artifact
- JSON or CSV response served back to client
b. Relationships and Data Flows
1. Client → FastAPI Routes (POST /extract-criteria, /score-resumes, /rank-resumes-from-job)
2. Routes → Services (document_processor → criteria_extractor → crew_manager → resume_scorer → result_formatter → name_extractor)
3. Services ↔ External APIs (CrewAI, Groq)
4. Services → Response (JSON criteria list or CSV bytes) → Client
c. Architectural Patterns
- Layered architecture (Routes → Services → External integrations)
- Configuration-driven agent orchestration (CrewAI)
- Schema validation (Pydantic)
- Stateless microservice (no local DB)
d. Key Technologies & Frameworks
- FastAPI (uvicorn ASGI server)
- Pydantic schemas (app/models/schemas.py)
- CrewAI (app/crews/config & resume_ranker_crew.py)
- Groq LLM API (configured via .env)
- PDF/DOCX processing libraries in document_processor

##### Detailed Elements
- Routes Layer:
- /extract-criteria → CriteriaExtractorService
- /score-resumes → ResumeScorerService
- /rank-resumes-from-job → orchestrator combining both
- Services Layer:
- DocumentProcessorService (PDF/DOCX → text)
- CriteriaExtractorService (text → list of criteria via Groq/CrewAI)
- ResumeScorerService (criteria + resumes → scores via Groq/CrewAI)
- NameExtractorService (text → candidate name)
- ResultFormatterService (scores + names → CSV)
- CrewAI Integration:
- Configuration files (agents.yaml, tasks.yaml)
- CrewManager orchestrates agent calls
- External LLM:
- Groq API (Key via .env)
- Logging & Validation:
- Logger module capturing all service interactions
- Pydantic schemas validating request bodies and responses

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["API Client (Swagger/HTTP)"]

    subgraph "Routes Layer"
        CriteriaRoute["/extract-criteria"]:::routes
        ScoringRoute["/score-resumes"]:::routes
        PipelineRoute["/rank-resumes-from-job"]:::routes
    end

    subgraph "Services Layer"
        DocumentProcessor["DocumentProcessorService"]:::services
        CriteriaExtractor["CriteriaExtractorService"]:::services
        ResumeScorer["ResumeScorerService"]:::services
        NameExtractor["NameExtractorService"]:::services
        ResultFormatter["ResultFormatterService"]:::services
        CrewManager["CrewManagerService"]:::services
    end

    subgraph "Models & Logging"
        Schemas["Pydantic Schemas"]:::model
        Logger["Logger"]:::logger
    end

    subgraph "CrewAI Config"
        CrewEntry["resume_ranker_crew.py"]:::config
        AgentsCfg["agents.yaml\ncrews.yaml\ntasks.yaml\nllms.json"]:::config
    end

    subgraph "External Services"
        Groq["Groq LLM API"]:::external
        CrewAI["CrewAI Agent Framework"]:::external
    end

    subgraph "Infra"
        Entry["app/main.py"]:::entrypoint
        Env[".env.example"]:::config
        Req["requirements.txt"]:::config
    end

    Client --> CriteriaRoute
    Client --> ScoringRoute
    Client --> PipelineRoute

    CriteriaRoute --> CriteriaExtractor
    ScoringRoute --> ResumeScorer
    PipelineRoute --> DocumentProcessor

    DocumentProcessor --> CriteriaExtractor
    CriteriaExtractor --> CrewManager
    CrewManager -.-> CrewAI
    CrewManager -.-> Groq
    CrewManager --> ResumeScorer
    ResumeScorer -.-> Groq
    ResumeScorer --> ResultFormatter
    NameExtractor --> ResultFormatter
    ResultFormatter --> Client

    CriteriaRoute -.-> Schemas
    ScoringRoute -.-> Schemas
    PipelineRoute -.-> Schemas
    DocumentProcessor -.-> Logger
    CriteriaExtractor -.-> Logger
    ResumeScorer -.-> Logger
    NameExtractor -.-> Logger
    ResultFormatter -.-> Logger
    CrewManager -.-> Logger

    click Entry "https://github.com/mindk-scrap/resumeranker/blob/main/app/main.py"
    click Logger "https://github.com/mindk-scrap/resumeranker/blob/main/app/logger.py"
    click Schemas "https://github.com/mindk-scrap/resumeranker/blob/main/app/models/schemas.py"
    click CriteriaRoute "https://github.com/mindk-scrap/resumeranker/blob/main/app/routes/criteria.py"
    click ScoringRoute "https://github.com/mindk-scrap/resumeranker/blob/main/app/routes/scoring.py"
    click PipelineRoute "https://github.com/mindk-scrap/resumeranker/blob/main/app/routes/pipeline.py"
    click DocumentProcessor "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/document_processor.py"
    click CriteriaExtractor "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/criteria_extractor.py"
    click ResumeScorer "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/resume_scorer.py"
    click NameExtractor "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/name_extractor.py"
    click ResultFormatter "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/result_formatter.py"
    click CrewManager "https://github.com/mindk-scrap/resumeranker/blob/main/app/services/crew_manager.py"
    click CrewEntry "https://github.com/mindk-scrap/resumeranker/blob/main/app/crews/resume_ranker_crew.py"
    click AgentsCfg "https://github.com/mindk-scrap/resumeranker/blob/main/app/crews/config/agents.yaml"
    click AgentsCfg "https://github.com/mindk-scrap/resumeranker/blob/main/app/crews/config/crews.yaml"
    click AgentsCfg "https://github.com/mindk-scrap/resumeranker/blob/main/app/crews/config/tasks.yaml"
    click AgentsCfg "https://github.com/mindk-scrap/resumeranker/blob/main/app/crews/config/llms.json"
    click Env "https://github.com/mindk-scrap/resumeranker/blob/main/.env.example"
    click Req "https://github.com/mindk-scrap/resumeranker/blob/main/requirements.txt"

    classDef routes fill:#D6E9FE,stroke:#0666,stroke-width:1px
    classDef services fill:#DFF2BF,stroke:#0a0,stroke-width:1px
    classDef external fill:#FEEFB3,stroke:#e68a00,stroke-width:1px
    classDef config fill:#FEF2C0,stroke:#c59e00,stroke-width:1px
    classDef model fill:#E0E0E0,stroke:#999,stroke-width:1px
    classDef logger fill:#F4F4F8,stroke:#888,stroke-width:1px
    classDef entrypoint fill:#DAD,stroke:#a00,stroke-width:1px
```
