# soumadipta-konar/fitrank-ai architecture

> Architecture diagram of the GitHub repository soumadipta-konar/fitrank-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soumadipta-konar/fitrank-ai
- Repository: https://github.com/soumadipta-konar/fitrank-ai

## Overview

1. **Overall shape**
   - FitRank AI is an **offline candidate-ranking pipeline** for a hiring challenge, not an interactive app.
   - The architecture is centered on taking a job description plus candidate data and producing a **ranked top-100 shortlist**.

2. **Orchestration layer**
   - `rank.py` appears to be the main entry point that ties the system together.
   - It likely coordinates loading data, building features, running the ranking stages, and producing the final output.

3. **Data ingestion boundary**
   - `src/data_loader.py` is the input boundary for the system.
   - This module likely normalizes raw challenge data into internal structures for jobs, candidates, skills, career history, and any recruiter-behavior signals.

4. **Candidate reduction / prefiltering**
   - `src/prefilter.py` is a first-pass narrowing stage.
   - Its role is probably to eliminate obviously irrelevant candidates before heavier semantic or scoring logic runs, which matters for performance and shortlist quality.

5. **Feature engineering layer**
   - `src/features.py` is the main signal-construction module.
   - Based on the README, this is where candidate/job attributes are turned into features such as skills overlap, experience alignment, career history patterns, and risk indicators.

6. **Semantic matching subsystem**
   - `src/semantic_ranker.py` handles the “meaning-based” match between job description and candidate profile.
   - This is the part of the system that goes beyond keyword overlap and supports the repo’s stated goal of semantic job-candidate matching.

7. **Lexical matching subsystem**
   - `src/lexical_ranker.py` likely provides a more direct text/surface-form ranking signal.
   - In the overall architecture, it complements semantic matching by capturing exact or near-exact keyword and phrase matches.

8. **Scoring and fusion**
   - `src/scoring.py` appears to combine multiple signals into a final ranking score.
   - The README suggests this fused score includes skill and experience matching, recruiter-behavior signals, and penalties for risk/honeypot cases.

9. **Final output generation**
   - `src/submission.py` is the output boundary.
   - It likely formats the ranked candidate list into the challenge-required submission structure, enforcing the top-100 shortlist requirement.

10. **Experimentation and analysis**
   - `notebooks/fitrank_ai.ipynb` is the exploratory workspace.
   - It likely contains model experimentation, feature validation, ranking analysis, and tuning that informed the production pipeline in `src/`.

11. **Key architectural boundary**
   - The important design boundary is between **candidate retrieval/filtering** and **multi-signal ranking**.
   - The system first reduces the search space, then applies lexical, semantic, and heuristic scoring to produce a trustworthy shortlist.

12. **What to show in an architecture diagram**
   - A good diagram should show: **raw challenge data → data loading → prefiltering → feature extraction → lexical/semantic rankers → scoring/fusion → submission output**.
   - The diagram should also show the notebook as a sidecar for offline experimentation, not part of the core runtime path.

Main entry points: [`rank.py`](https://github.com/soumadipta-konar/fitrank-ai/blob/main/rank.py) (rank.py), [`src/features.py`](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/features.py) (Features), [`src/scoring.py`](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/scoring.py) (Scoring), [`src/data_loader.py`](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/data_loader.py) (Data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core pipeline"]
  node_rank_py["rank.py<br/>orchestrator<br/>[rank.py]"]
  node_data_loader["Data loader<br/>input normalization<br/>[data_loader.py]"]
  node_prefilter["Prefilter<br/>candidate filter<br/>[prefilter.py]"]
  node_features["Features<br/>signal engineering<br/>[features.py]"]
  node_lexical_ranker["Lexical ranker<br/>text matching<br/>[lexical_ranker.py]"]
  node_semantic_ranker["Semantic ranker<br/>meaning matching<br/>[semantic_ranker.py]"]
  node_scoring["Scoring<br/>score fusion<br/>[scoring.py]"]
  node_submission["Submission<br/>output formatter<br/>[submission.py]"]
end

subgraph group_offline["Offline analysis"]
  node_notebook["Notebook<br/>exploration<br/>[fitrank_ai.ipynb]"]
end

node_challenge_data[("Challenge data<br/>external input")]
node_ranked_shortlist["Top-100 shortlist<br/>output"]

node_challenge_data -->|"load"| node_data_loader
node_data_loader -->|"candidates"| node_prefilter
node_data_loader -->|"job/candidate data"| node_features
node_prefilter -->|"filtered set"| node_features
node_features -->|"text signals"| node_lexical_ranker
node_features -->|"profile signals"| node_semantic_ranker
node_lexical_ranker -->|"lexical score"| node_scoring
node_semantic_ranker -->|"semantic score"| node_scoring
node_prefilter -->|"candidate gate"| node_scoring
node_scoring -->|"ranked list"| node_submission
node_submission -->|"emit"| node_ranked_shortlist
node_rank_py -.->|"orchestrate"| node_data_loader
node_rank_py -.->|"orchestrate"| node_prefilter
node_rank_py -.->|"orchestrate"| node_features
node_rank_py -.->|"orchestrate"| node_lexical_ranker
node_rank_py -.->|"orchestrate"| node_semantic_ranker
node_rank_py -.->|"orchestrate"| node_scoring
node_rank_py -.->|"orchestrate"| node_submission
node_notebook -.->|"explore"| node_features
node_notebook -.->|"analyze"| node_scoring

click node_rank_py "https://github.com/soumadipta-konar/fitrank-ai/blob/main/rank.py"
click node_data_loader "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/data_loader.py"
click node_prefilter "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/prefilter.py"
click node_features "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/features.py"
click node_lexical_ranker "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/lexical_ranker.py"
click node_semantic_ranker "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/semantic_ranker.py"
click node_scoring "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/scoring.py"
click node_submission "https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/submission.py"
click node_notebook "https://github.com/soumadipta-konar/fitrank-ai/blob/main/notebooks/fitrank_ai.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rank_py,node_data_loader,node_prefilter,node_features,node_lexical_ranker,node_semantic_ranker,node_scoring,node_submission toneBlue
class node_notebook toneAmber
class node_challenge_data,node_ranked_shortlist toneNeutral
```

## Components

### Core pipeline

Offline candidate-ranking runtime from input loading to submission output.

- [rank.py](https://github.com/soumadipta-konar/fitrank-ai/blob/main/rank.py): orchestrator · Main entry point that coordinates the ranking pipeline. · `rank.py`
- [Data loader](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/data_loader.py): input normalization · Loads and normalizes challenge job and candidate data. · `src/data_loader.py`
- [Prefilter](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/prefilter.py): candidate filter · First-pass narrowing stage that removes obviously weak candidates. · `src/prefilter.py`
- [Features](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/features.py): signal engineering · Builds structured signals from job and candidate attributes. · `src/features.py`
- [Lexical ranker](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/lexical_ranker.py): text matching · Scores direct keyword and phrase overlap between job and candidate text. · `src/lexical_ranker.py`
- [Semantic ranker](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/semantic_ranker.py): meaning matching · Computes deeper semantic similarity between job requirements and candidate profiles. · `src/semantic_ranker.py`
- [Scoring](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/scoring.py): score fusion · Combines ranking signals and penalties into the final score. · `src/scoring.py`
- [Submission](https://github.com/soumadipta-konar/fitrank-ai/blob/main/src/submission.py): output formatter · Formats the ranked shortlist into the required challenge submission. · `src/submission.py`

### Offline analysis

Notebook used for experimentation and tuning outside the main runtime path.

- [Notebook](https://github.com/soumadipta-konar/fitrank-ai/blob/main/notebooks/fitrank_ai.ipynb): exploration · Offline experimentation and analysis workspace. · `notebooks/fitrank_ai.ipynb`

### Other components

- **Challenge data**: external input · Raw hiring-challenge job and candidate data consumed by the pipeline.
- **Top-100 shortlist**: output · Final ranked candidate list produced by the system.

## Connections

- Challenge data → Data loader: load · Raw input is ingested and normalized.
- Data loader → Prefilter: candidates · Loaded records feed the narrowing stage.
- Data loader → Features: job/candidate data · Normalized entities are converted into features.
- Prefilter → Features: filtered set · Reduced candidate pool proceeds to feature construction.
- Features → Lexical ranker: text signals · Feature layer supplies surface-form matching inputs.
- Features → Semantic ranker: profile signals · Feature layer supplies semantic matching inputs.
- Lexical ranker → Scoring: lexical score · Surface-form match contributes to the fused score.
- Semantic ranker → Scoring: semantic score · Meaning-based match contributes to the fused score.
- Prefilter → Scoring: candidate gate · Prefiltering constrains the pool scored downstream.
- Scoring → Submission: ranked list · Final scores are converted into the required output format.
- Submission → Top-100 shortlist: emit · Top-100 shortlist is produced for delivery.
- rank.py → Data loader: orchestrate · Main script coordinates loading.
- rank.py → Prefilter: orchestrate · Main script coordinates candidate reduction.
- rank.py → Features: orchestrate · Main script coordinates feature construction.
- rank.py → Lexical ranker: orchestrate · Main script coordinates lexical scoring.
- rank.py → Semantic ranker: orchestrate · Main script coordinates semantic scoring.
- rank.py → Scoring: orchestrate · Main script coordinates score fusion.
- rank.py → Submission: orchestrate · Main script coordinates final output generation.
- Notebook → Features: explore · Notebook informs feature design and tuning.
- Notebook → Scoring: analyze · Notebook supports experimentation with weighting and ranking behavior.
