# dakshrjain737/ragnarok architecture

> Architecture diagram of the GitHub repository dakshrjain737/ragnarok, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dakshrjain737/ragnarok
- Repository: https://github.com/dakshrjain737/ragnarok

## Overview

RAGnarok turns a job description and candidate profiles into a ranked candidate submission: it parses both inputs, retrieves candidates through five complementary paths, fuses and scores them, then produces adversarially grounded reasoning. Offline indexing supports ranking with reusable search and feature data. The README documents the end-to-end stages; sampled source excerpts were partial, so links among components follow documented responsibilities rather than unverified implementation details.

Main entry points: [`pipeline/runner.py`](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/runner.py) (Pipeline runner), [`pipeline/candidate_parser.py`](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/candidate_parser.py) (Candidate parser), [`pipeline/jd_parser.py`](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/jd_parser.py) (JD parser), [`retrieval/rrf_fusion.py`](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/rrf_fusion.py) (RRF fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Parsing and indexes"]
  node_runner["Pipeline runner<br/>[runner.py]"]
  node_candidate_parser["Candidate parser"]
  node_jd_parser["JD parser<br/>[jd_parser.py]"]
  node_faiss[("FAISS index<br/>[faiss_builder.py]")]
  node_bm25[("BM25 index<br/>[bm25_builder.py]")]
  node_feature_store[("Feature store<br/>[feature_store.py]")]
  node_trajectory_db[("Trajectory index")]
  node_honeypot_registry[("Honeypot registry")]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_ontology["Skill ontology<br/>[skill_map.json]"]
  node_query_expander["Query expander<br/>[query_expander.py]"]
  node_semantic["Semantic retrieval<br/>[semantic_path.py]"]
  node_keyword["Keyword retrieval<br/>[keyword_path.py]"]
  node_ontology_path["Ontology traversal<br/>[ontology_path.py]"]
  node_trajectory_path["Trajectory retrieval<br/>[trajectory_path.py]"]
  node_signal_path["Signal retrieval<br/>[signal_path.py]"]
  node_fusion["RRF fusion<br/>[rrf_fusion.py]"]
end

subgraph group_scoring["Ranking and scoring"]
  node_honeypot_filter["Honeypot filter<br/>[honeypot_filter.py]"]
  node_cross_encoder["Cross-encoder reranker<br/>[cross_encoder.py]"]
  node_skill_match["Skill matching<br/>[skill_match.py]"]
  node_career_quality["Career quality<br/>[career_quality.py]"]
  node_behavioral["Behavioral scoring<br/>[behavioral.py]"]
  node_trajectory_score["Trajectory scoring<br/>[trajectory.py]"]
  node_composite["Composite scorer<br/>[composite.py]"]
end

subgraph group_trust["Trust and explanation"]
  node_advocate["Advocate analysis<br/>[advocate.py]"]
  node_skeptic["Skeptic analysis<br/>[skeptic.py]"]
  node_verdict["Trust verdict<br/>[verdict.py]"]
  node_reasoning["Reasoning generator"]
  node_llm_reranker["Local LLM reranker<br/>[llm_reranker.py]"]
end

node_operator(("Recruiter / operator"))
node_profiles["Candidate profiles"]
node_jd["Job description"]
node_submission["Ranked submission<br/>[submission.csv]"]

node_operator -->|"provides profiles"| node_profiles
node_operator -->|"provides target JD"| node_jd
node_operator -->|"starts ranking"| node_runner
node_profiles -->|"parsed into features"| node_candidate_parser
node_jd -->|"parsed into intent"| node_jd_parser
node_runner -->|"invokes"| node_candidate_parser
node_runner -->|"invokes"| node_jd_parser
node_runner -->|"loads index"| node_faiss
node_runner -->|"loads index"| node_bm25
node_runner -->|"loads features"| node_feature_store
node_runner -->|"loads index"| node_trajectory_db
node_runner -->|"checks candidates"| node_honeypot_registry
node_candidate_parser -->|"builds vectors"| node_faiss
node_candidate_parser -->|"builds corpus"| node_bm25
node_candidate_parser -->|"builds features"| node_feature_store
node_candidate_parser -->|"builds patterns"| node_trajectory_db
node_candidate_parser -->|"registers profiles"| node_honeypot_registry
node_runner -->|"dispatches query"| node_semantic
node_runner -->|"dispatches query"| node_keyword
node_runner -->|"dispatches query"| node_ontology_path
node_runner -->|"dispatches query"| node_trajectory_path
node_runner -->|"dispatches query"| node_signal_path
node_jd_parser -->|"supplies intent"| node_semantic
node_jd_parser -->|"supplies intent"| node_keyword
node_jd_parser -->|"supplies intent"| node_ontology_path
node_jd_parser -->|"supplies intent"| node_trajectory_path
node_jd_parser -->|"supplies intent"| node_signal_path
node_semantic -->|"searches vectors"| node_faiss
node_keyword -->|"searches terms"| node_bm25
node_keyword -->|"expands query"| node_query_expander
node_query_expander -->|"reads skill map"| node_ontology
node_ontology_path -->|"traverses skills"| node_ontology
node_trajectory_path -->|"scores patterns"| node_trajectory_db
node_signal_path -->|"reads signals"| node_feature_store
node_semantic -->|"returns ranked set"| node_fusion
node_keyword -->|"returns ranked set"| node_fusion
node_ontology_path -->|"returns ranked set"| node_fusion
node_trajectory_path -->|"returns ranked set"| node_fusion
node_signal_path -->|"returns ranked set"| node_fusion
node_runner -->|"fuses results"| node_fusion
node_runner -->|"filters candidates"| node_honeypot_filter
node_honeypot_filter -->|"checks registry"| node_honeypot_registry
node_runner -->|"reranks survivors"| node_cross_encoder
node_runner -->|"scores skills"| node_skill_match
node_runner -->|"scores career"| node_career_quality
node_runner -->|"scores behavior"| node_behavioral
node_runner -->|"scores trajectory"| node_trajectory_score
node_runner -->|"combines scores"| node_composite

click node_runner "https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/runner.py"
click node_candidate_parser "https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/candidate_parser.py"
click node_jd_parser "https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/jd_parser.py"
click node_faiss "https://github.com/dakshrjain737/ragnarok/blob/master/indexing/faiss_builder.py"
click node_bm25 "https://github.com/dakshrjain737/ragnarok/blob/master/indexing/bm25_builder.py"
click node_feature_store "https://github.com/dakshrjain737/ragnarok/blob/master/indexing/feature_store.py"
click node_trajectory_db "https://github.com/dakshrjain737/ragnarok/blob/master/indexing/trajectory_builder.py"
click node_honeypot_registry "https://github.com/dakshrjain737/ragnarok/blob/master/indexing/honeypot_registry.py"
click node_ontology "https://github.com/dakshrjain737/ragnarok/blob/master/ontology/skill_map.json"
click node_query_expander "https://github.com/dakshrjain737/ragnarok/blob/master/ontology/query_expander.py"
click node_semantic "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/semantic_path.py"
click node_keyword "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/keyword_path.py"
click node_ontology_path "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/ontology_path.py"
click node_trajectory_path "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/trajectory_path.py"
click node_signal_path "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/signal_path.py"
click node_fusion "https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/rrf_fusion.py"
click node_honeypot_filter "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/honeypot_filter.py"
click node_cross_encoder "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/cross_encoder.py"
click node_skill_match "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/skill_match.py"
click node_career_quality "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/career_quality.py"
click node_behavioral "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/behavioral.py"
click node_trajectory_score "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/trajectory.py"
click node_composite "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/composite.py"
click node_advocate "https://github.com/dakshrjain737/ragnarok/blob/master/trust/advocate.py"
click node_skeptic "https://github.com/dakshrjain737/ragnarok/blob/master/trust/skeptic.py"
click node_verdict "https://github.com/dakshrjain737/ragnarok/blob/master/trust/verdict.py"
click node_reasoning "https://github.com/dakshrjain737/ragnarok/blob/master/trust/reasoning_generator.py"
click node_llm_reranker "https://github.com/dakshrjain737/ragnarok/blob/master/scoring/llm_reranker.py"
click node_submission "https://github.com/dakshrjain737/ragnarok/blob/master/output/submission.csv"

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_runner,node_candidate_parser,node_jd_parser,node_faiss,node_bm25,node_feature_store,node_trajectory_db,node_honeypot_registry toneBlue
class node_ontology,node_query_expander,node_semantic,node_keyword,node_ontology_path,node_trajectory_path,node_signal_path,node_fusion toneAmber
class node_honeypot_filter,node_cross_encoder,node_skill_match,node_career_quality,node_behavioral,node_trajectory_score,node_composite toneMint
class node_advocate,node_skeptic,node_verdict,node_reasoning,node_llm_reranker toneRose
class node_operator,node_profiles,node_jd toneIndigo
class node_submission toneTeal
```

## Components

### Parsing and indexes

- [Pipeline runner](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/runner.py): `pipeline/runner.py`
- [Candidate parser](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/candidate_parser.py): `pipeline/candidate_parser.py`
- [JD parser](https://github.com/dakshrjain737/ragnarok/blob/master/pipeline/jd_parser.py): `pipeline/jd_parser.py`
- [FAISS index](https://github.com/dakshrjain737/ragnarok/blob/master/indexing/faiss_builder.py): `indexing/faiss_builder.py`
- [BM25 index](https://github.com/dakshrjain737/ragnarok/blob/master/indexing/bm25_builder.py): `indexing/bm25_builder.py`
- [Feature store](https://github.com/dakshrjain737/ragnarok/blob/master/indexing/feature_store.py): `indexing/feature_store.py`
- [Trajectory index](https://github.com/dakshrjain737/ragnarok/blob/master/indexing/trajectory_builder.py): `indexing/trajectory_builder.py`
- [Honeypot registry](https://github.com/dakshrjain737/ragnarok/blob/master/indexing/honeypot_registry.py): `indexing/honeypot_registry.py`

### Hybrid retrieval

- [Skill ontology](https://github.com/dakshrjain737/ragnarok/blob/master/ontology/skill_map.json): `ontology/skill_map.json`
- [Query expander](https://github.com/dakshrjain737/ragnarok/blob/master/ontology/query_expander.py): `ontology/query_expander.py`
- [Semantic retrieval](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/semantic_path.py): `retrieval/semantic_path.py`
- [Keyword retrieval](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/keyword_path.py): `retrieval/keyword_path.py`
- [Ontology traversal](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/ontology_path.py): `retrieval/ontology_path.py`
- [Trajectory retrieval](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/trajectory_path.py): `retrieval/trajectory_path.py`
- [Signal retrieval](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/signal_path.py): `retrieval/signal_path.py`
- [RRF fusion](https://github.com/dakshrjain737/ragnarok/blob/master/retrieval/rrf_fusion.py): `retrieval/rrf_fusion.py`

### Ranking and scoring

- [Honeypot filter](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/honeypot_filter.py): `scoring/honeypot_filter.py`
- [Cross-encoder reranker](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/cross_encoder.py): `scoring/cross_encoder.py`
- [Skill matching](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/skill_match.py): `scoring/skill_match.py`
- [Career quality](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/career_quality.py): `scoring/career_quality.py`
- [Behavioral scoring](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/behavioral.py): `scoring/behavioral.py`
- [Trajectory scoring](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/trajectory.py): `scoring/trajectory.py`
- [Composite scorer](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/composite.py): `scoring/composite.py`

### Trust and explanation

- [Advocate analysis](https://github.com/dakshrjain737/ragnarok/blob/master/trust/advocate.py): `trust/advocate.py`
- [Skeptic analysis](https://github.com/dakshrjain737/ragnarok/blob/master/trust/skeptic.py): `trust/skeptic.py`
- [Trust verdict](https://github.com/dakshrjain737/ragnarok/blob/master/trust/verdict.py): `trust/verdict.py`
- [Reasoning generator](https://github.com/dakshrjain737/ragnarok/blob/master/trust/reasoning_generator.py): `trust/reasoning_generator.py`
- [Local LLM reranker](https://github.com/dakshrjain737/ragnarok/blob/master/scoring/llm_reranker.py): `scoring/llm_reranker.py`

### Other components

- **Recruiter / operator**
- **Candidate profiles**
- **Job description**
- [Ranked submission](https://github.com/dakshrjain737/ragnarok/blob/master/output/submission.csv): `output/submission.csv`

## Connections

- Recruiter / operator → Candidate profiles: provides profiles
- Recruiter / operator → Job description: provides target JD
- Recruiter / operator → Pipeline runner: starts ranking
- Candidate profiles → Candidate parser: parsed into features
- Job description → JD parser: parsed into intent
- Pipeline runner → Candidate parser: invokes
- Pipeline runner → JD parser: invokes
- Pipeline runner → FAISS index: loads index
- Pipeline runner → BM25 index: loads index
- Pipeline runner → Feature store: loads features
- Pipeline runner → Trajectory index: loads index
- Pipeline runner → Honeypot registry: checks candidates
- Candidate parser → FAISS index: builds vectors
- Candidate parser → BM25 index: builds corpus
- Candidate parser → Feature store: builds features
- Candidate parser → Trajectory index: builds patterns
- Candidate parser → Honeypot registry: registers profiles
- Pipeline runner → Semantic retrieval: dispatches query
- Pipeline runner → Keyword retrieval: dispatches query
- Pipeline runner → Ontology traversal: dispatches query
- Pipeline runner → Trajectory retrieval: dispatches query
- Pipeline runner → Signal retrieval: dispatches query
- JD parser → Semantic retrieval: supplies intent
- JD parser → Keyword retrieval: supplies intent
- JD parser → Ontology traversal: supplies intent
- JD parser → Trajectory retrieval: supplies intent
- JD parser → Signal retrieval: supplies intent
- Semantic retrieval → FAISS index: searches vectors
- Keyword retrieval → BM25 index: searches terms
- Keyword retrieval → Query expander: expands query
- Query expander → Skill ontology: reads skill map
- Ontology traversal → Skill ontology: traverses skills
- Trajectory retrieval → Trajectory index: scores patterns
- Signal retrieval → Feature store: reads signals
- Semantic retrieval → RRF fusion: returns ranked set
- Keyword retrieval → RRF fusion: returns ranked set
- Ontology traversal → RRF fusion: returns ranked set
- Trajectory retrieval → RRF fusion: returns ranked set
- Signal retrieval → RRF fusion: returns ranked set
- Pipeline runner → RRF fusion: fuses results
- Pipeline runner → Honeypot filter: filters candidates
- Honeypot filter → Honeypot registry: checks registry
- Pipeline runner → Cross-encoder reranker: reranks survivors
- Pipeline runner → Skill matching: scores skills
- Pipeline runner → Career quality: scores career
- Pipeline runner → Behavioral scoring: scores behavior
- Pipeline runner → Trajectory scoring: scores trajectory
- Pipeline runner → Composite scorer: combines scores