# saptarshi-bandopadhyay/axiom architecture

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

- Interactive diagram: https://gitdiagram.com/saptarshi-bandopadhyay/axiom
- Repository: https://github.com/saptarshi-bandopadhyay/axiom

## Overview

ReproCheck is a full-stack research-methodology reviewer. A researcher submits a PDF or pasted text through the UI; the backend validates and prepares the paper, then runs a staged review with a reviewer-approved checklist before returning findings, contradictions, and an assessment. The UI also supports grounded Q&A. The README documents the review lifecycle; sampled files and the SOURCE INDEX support key wiring, but several route and workflow-node implementations were not inspected, so uncertain links are omitted.

Main entry points: [`backend/app/workflows/graph.py`](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/graph.py) (Workflow Graph), [`backend/app/services/workflow_service.py`](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/workflow_service.py) (Workflow Service), [`frontend/src/App.tsx`](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/App.tsx) (Review App), [`frontend/src/api/client.ts`](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/api/client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Reviewer UI"]
  node_app["Review App<br/>[App.tsx]"]
  node_submission["Submission Form<br/>[SubmissionForm.tsx]"]
  node_paradigm["Paradigm Selector"]
  node_api_client["API Client<br/>[client.ts]"]
  node_checklist_ui["Checklist Editor"]
  node_report_ui["Report View"]
  node_qna_ui["Grounded Q&amp;A"]
end

subgraph group_backend["API and Ingestion"]
  node_session_api["Session Routes<br/>[sessions.py]"]
  node_checklist_api["Checklist Routes<br/>[checklists.py]"]
  node_review_api["Review Routes<br/>[reviews.py]"]
  node_qna_api["Q&amp;A Route<br/>[qna.py]"]
  node_guardrails["Input Guardrails<br/>[guardrails.py]"]
  node_pdf_extractor["PDF Extraction"]
  node_file_storage["File Storage<br/>[local_storage.py]"]
end

subgraph group_workflow["Review Workflow"]
  node_workflow_service["Workflow Service"]
  node_graph["Workflow Graph<br/>[graph.py]"]
  node_classification["Paradigm Classification<br/>[classify.py]"]
  node_checklist_stage["Checklist Generation<br/>[checklist.py]"]
  node_approval["Human Approval<br/>[approval.py]"]
  node_review_stage["Methodology Review<br/>[review.py]"]
  node_consistency["Consistency Check<br/>[consistency.py]"]
  node_assessment["Assessment Synthesis<br/>[assessment.py]"]
  node_qna_stage["Grounded Answers<br/>[qna.py]"]
  node_llm["LLM Gateway<br/>[llm_gateway.py]"]
end

subgraph group_infra["State and Models"]
  node_state["Workflow State<br/>[state.py]"]
  node_sessions[("Review Sessions<br/>[session.py]")]
end

node_researcher(("Researcher"))
node_database[("PostgreSQL")]

node_researcher -->|"submits paper"| node_submission
node_submission -->|"selects paradigm"| node_paradigm
node_app -->|"renders"| node_submission
node_app -->|"requests data"| node_api_client
node_api_client -->|"sends submissions"| node_session_api
node_api_client -->|"approves checklist"| node_checklist_api
node_api_client -->|"fetches report"| node_review_api
node_api_client -->|"asks questions"| node_qna_api
node_app -->|"renders"| node_checklist_ui
node_app -->|"renders"| node_report_ui
node_app -->|"renders"| node_qna_ui
node_session_api -->|"validates input"| node_guardrails
node_session_api -->|"extracts PDF"| node_pdf_extractor
node_session_api -->|"stores upload"| node_file_storage
node_session_api -->|"starts workflow"| node_workflow_service
node_workflow_service -->|"creates and runs"| node_graph
node_workflow_service -->|"updates status"| node_sessions
node_sessions -->|"persists records"| node_database
node_graph -->|"dispatches"| node_classification
node_graph -->|"dispatches"| node_checklist_stage
node_graph -->|"dispatches"| node_approval
node_graph -->|"dispatches"| node_review_stage
node_graph -->|"dispatches"| node_consistency
node_graph -->|"dispatches"| node_assessment
node_classification -->|"precedes"| node_checklist_stage
node_checklist_stage -->|"pauses for review"| node_approval
node_approval -->|"resumes after approval"| node_review_stage
node_review_stage -->|"precedes"| node_consistency
node_consistency -->|"precedes"| node_assessment
node_checklist_stage -->|"generates criteria"| node_llm
node_review_stage -->|"evaluates paper"| node_llm
node_qna_stage -->|"answers question"| node_llm
node_workflow_service -->|"delegates answers"| node_qna_stage
node_review_api -->|"reads snapshot"| node_workflow_service
node_qna_api -.->|"requests answer"| node_workflow_service
node_checklist_api -.->|"resumes review"| node_workflow_service

click node_app "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/App.tsx"
click node_submission "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/SubmissionForm.tsx"
click node_paradigm "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ParadigmSelector.tsx"
click node_api_client "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/api/client.ts"
click node_checklist_ui "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ChecklistEditor.tsx"
click node_report_ui "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ReviewReportView.tsx"
click node_qna_ui "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/GroundedQnADrawer.tsx"
click node_session_api "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/sessions.py"
click node_checklist_api "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/checklists.py"
click node_review_api "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/reviews.py"
click node_qna_api "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/qna.py"
click node_guardrails "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/core/guardrails.py"
click node_pdf_extractor "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/pymupdf_extractor.py"
click node_file_storage "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/local_storage.py"
click node_workflow_service "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/workflow_service.py"
click node_graph "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/graph.py"
click node_classification "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/classify.py"
click node_checklist_stage "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/checklist.py"
click node_approval "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/approval.py"
click node_review_stage "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/review.py"
click node_consistency "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/consistency.py"
click node_assessment "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/assessment.py"
click node_qna_stage "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/qna.py"
click node_llm "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/core/llm_gateway.py"
click node_state "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/state.py"
click node_sessions "https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/models/session.py"

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_app,node_submission,node_paradigm,node_api_client,node_checklist_ui,node_report_ui,node_qna_ui toneBlue
class node_session_api,node_checklist_api,node_review_api,node_qna_api,node_guardrails,node_pdf_extractor,node_file_storage,node_database toneAmber
class node_workflow_service,node_graph,node_classification,node_checklist_stage,node_approval,node_review_stage,node_consistency,node_assessment,node_qna_stage,node_llm toneMint
class node_state,node_sessions toneRose
class node_researcher toneIndigo
```

## Components

### Reviewer UI

- [Review App](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Submission Form](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/SubmissionForm.tsx): `frontend/src/components/SubmissionForm.tsx`
- [Paradigm Selector](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ParadigmSelector.tsx): `frontend/src/components/ParadigmSelector.tsx`
- [API Client](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Checklist Editor](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ChecklistEditor.tsx): `frontend/src/components/ChecklistEditor.tsx`
- [Report View](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/ReviewReportView.tsx): `frontend/src/components/ReviewReportView.tsx`
- [Grounded Q&A](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/frontend/src/components/GroundedQnADrawer.tsx): `frontend/src/components/GroundedQnADrawer.tsx`

### API and Ingestion

- [Session Routes](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/sessions.py): `backend/app/api/sessions.py`
- [Checklist Routes](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/checklists.py): `backend/app/api/checklists.py`
- [Review Routes](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/reviews.py): `backend/app/api/reviews.py`
- [Q&A Route](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/api/qna.py): `backend/app/api/qna.py`
- [Input Guardrails](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/core/guardrails.py): `backend/app/core/guardrails.py`
- [PDF Extraction](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/pymupdf_extractor.py): `backend/app/services/pymupdf_extractor.py`
- [File Storage](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/local_storage.py): `backend/app/services/local_storage.py`

### Review Workflow

- [Workflow Service](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/services/workflow_service.py): `backend/app/services/workflow_service.py`
- [Workflow Graph](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/graph.py): `backend/app/workflows/graph.py`
- [Paradigm Classification](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/classify.py): `backend/app/workflows/nodes/classify.py`
- [Checklist Generation](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/checklist.py): `backend/app/workflows/nodes/checklist.py`
- [Human Approval](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/approval.py): `backend/app/workflows/nodes/approval.py`
- [Methodology Review](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/review.py): `backend/app/workflows/nodes/review.py`
- [Consistency Check](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/consistency.py): `backend/app/workflows/nodes/consistency.py`
- [Assessment Synthesis](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/assessment.py): `backend/app/workflows/nodes/assessment.py`
- [Grounded Answers](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/nodes/qna.py): `backend/app/workflows/nodes/qna.py`
- [LLM Gateway](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/core/llm_gateway.py): `backend/app/core/llm_gateway.py`

### State and Models

- [Workflow State](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/workflows/state.py): `backend/app/workflows/state.py`
- [Review Sessions](https://github.com/saptarshi-bandopadhyay/axiom/blob/main/backend/app/models/session.py): `backend/app/models/session.py`

### Other components

- **Researcher**
- **PostgreSQL**

## Connections

- Researcher → Submission Form: submits paper (evidence: `README.md`)
- Submission Form → Paradigm Selector: selects paradigm (evidence: `frontend/src/components/SubmissionForm.tsx`)
- Review App → Submission Form: renders (evidence: `frontend/src/App.tsx`)
- Review App → API Client: requests data (evidence: `frontend/src/App.tsx`)
- API Client → Session Routes: sends submissions (evidence: `frontend/src/api/client.ts`)
- API Client → Checklist Routes: approves checklist (evidence: `frontend/src/api/client.ts`)
- API Client → Review Routes: fetches report (evidence: `frontend/src/api/client.ts`)
- API Client → Q&A Route: asks questions (evidence: `frontend/src/api/client.ts`)
- Review App → Checklist Editor: renders (evidence: `frontend/src/App.tsx`)
- Review App → Report View: renders (evidence: `frontend/src/App.tsx`)
- Review App → Grounded Q&A: renders (evidence: `frontend/src/App.tsx`)
- Session Routes → Input Guardrails: validates input (evidence: `backend/app/api/sessions.py`)
- Session Routes → PDF Extraction: extracts PDF (evidence: `backend/app/api/sessions.py`)
- Session Routes → File Storage: stores upload (evidence: `backend/app/api/sessions.py`)
- Session Routes → Workflow Service: starts workflow (evidence: `backend/app/api/sessions.py`)
- Workflow Service → Workflow Graph: creates and runs (evidence: `backend/app/services/workflow_service.py`)
- Workflow Service → Review Sessions: updates status (evidence: `backend/app/services/workflow_service.py`)
- Review Sessions → PostgreSQL: persists records
- Workflow Graph → Paradigm Classification: dispatches (evidence: `backend/app/workflows/graph.py`)
- Workflow Graph → Checklist Generation: dispatches (evidence: `backend/app/workflows/graph.py`)
- Workflow Graph → Human Approval: dispatches (evidence: `backend/app/workflows/graph.py`)
- Workflow Graph → Methodology Review: dispatches (evidence: `backend/app/workflows/graph.py`)
- Workflow Graph → Consistency Check: dispatches (evidence: `backend/app/workflows/graph.py`)
- Workflow Graph → Assessment Synthesis: dispatches (evidence: `backend/app/workflows/graph.py`)
- Paradigm Classification → Checklist Generation: precedes (evidence: `README.md`)
- Checklist Generation → Human Approval: pauses for review (evidence: `README.md`)
- Human Approval → Methodology Review: resumes after approval (evidence: `README.md`)
- Methodology Review → Consistency Check: precedes (evidence: `README.md`)
- Consistency Check → Assessment Synthesis: precedes (evidence: `README.md`)
- Checklist Generation → LLM Gateway: generates criteria (evidence: `backend/app/workflows/nodes/checklist.py`)
- Methodology Review → LLM Gateway: evaluates paper (evidence: `backend/app/workflows/nodes/review.py`)
- Grounded Answers → LLM Gateway: answers question (evidence: `backend/app/workflows/nodes/qna.py`)
- Workflow Service → Grounded Answers: delegates answers (evidence: `backend/app/services/workflow_service.py`)
- Review Routes → Workflow Service: reads snapshot (evidence: `backend/app/api/reviews.py`)
- Q&A Route → Workflow Service: requests answer
- Checklist Routes → Workflow Service: resumes review