# shhhivamm/studyready architecture

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

- Interactive diagram: https://gitdiagram.com/shhhivamm/studyready
- Repository: https://github.com/shhhivamm/studyready

## Overview

StudyReady is a CBSE question-paper generator. Its main workflows are paper ingestion (admin request → CBSE discovery and download → vision extraction and embeddings → stored questions) and paper generation (request → question selection → LLM formatting → persisted paper → PDF/DOCX download). The graph includes API search and administration alongside these workflows. Edges reflect the sampled source, its indexed references, or README documentation; unsampled subsystem details are not inferred.

Main entry points: [`Backend/app/api/routes/papers.py`](https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/papers.py) (Paper routes), [`Backend/app/services/extraction/paper_extraction.py`](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/extraction/paper_extraction.py) (Extraction workflow), [`Backend/app/database/models.py`](https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/models.py) (PostgreSQL / pgvector), [`Backend/app/main.py`](https://github.com/shhhivamm/studyready/blob/main/Backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_deps["Request dependencies<br/>[deps.py]"]
  node_admin["Admin routes<br/>[admin.py]"]
  node_paper_routes["Paper routes<br/>[papers.py]"]
  node_question_routes["Question routes<br/>[questions.py]"]
  node_legacy_api["Legacy paper API<br/>[api.py]"]
  node_legacy_paper["Legacy paper lookup<br/>[get_paper.py]"]
end

subgraph group_ingestion["Paper ingestion"]
  node_extraction_flow["Extraction workflow"]
  node_scraper["CBSE scraper<br/>[cbse_scraper.py]"]
  node_downloader["PDF downloader<br/>[downloader.py]"]
  node_vision["Vision extraction<br/>[gemini_vision.py]"]
end

subgraph group_generation["Retrieval and generation"]
  node_embeddings["Embedding service"]
  node_search["Question search<br/>[search.py]"]
  node_selector["Question selection<br/>[selector.py]"]
  node_strategies["Selection strategies<br/>[strategies.py]"]
  node_generator["Paper generation<br/>[paper_generator.py]"]
  node_blueprint["Blueprint extraction"]
end

subgraph group_data["Data and export"]
  node_database[("PostgreSQL / pgvector<br/>[models.py]")]
  node_connection["Database sessions<br/>[connection.py]"]
  node_repository["Data repository<br/>[repository.py]"]
  node_pdf_export["PDF export<br/>[pdf.py]"]
  node_docx_export["DOCX export<br/>[docx.py]"]
  node_legacy_files["Legacy file handling<br/>[files.py]"]
end

node_user(("API client"))
node_cbse["CBSE website"]
node_llm["OpenRouter models"]

node_user -->|"sends requests"| node_app
node_app -->|"registers routes"| node_admin
node_app -->|"registers routes"| node_paper_routes
node_app -->|"registers routes"| node_question_routes
node_admin -->|"starts extraction"| node_extraction_flow
node_paper_routes -->|"selects questions"| node_selector
node_paper_routes -->|"applies strategies"| node_strategies
node_paper_routes -->|"formats paper"| node_generator
node_paper_routes -->|"extracts blueprint"| node_blueprint
node_paper_routes -->|"creates PDF"| node_pdf_export
node_paper_routes -.->|"exports DOCX"| node_docx_export
node_question_routes -->|"searches questions"| node_search
node_extraction_flow -->|"finds source papers"| node_scraper
node_extraction_flow -->|"downloads PDFs"| node_downloader
node_extraction_flow -->|"extracts questions"| node_vision
node_extraction_flow -->|"embeds questions"| node_embeddings
node_extraction_flow -->|"stores questions"| node_database
node_scraper -.->|"scrapes papers"| node_cbse
node_downloader -.->|"downloads PDFs"| node_cbse
node_vision -.->|"requests extraction"| node_llm
node_generator -.->|"requests formatting"| node_llm
node_search -->|"embeds query"| node_embeddings
node_search -->|"queries vectors"| node_database
node_selector -.->|"uses question records"| node_database
node_strategies -.->|"uses question records"| node_database
node_generator -.->|"uses paper records"| node_database
node_paper_routes -->|"reads and saves papers"| node_database
node_deps -->|"provides sessions"| node_connection
node_connection -->|"configures ORM"| node_database
node_legacy_api -->|"looks up papers"| node_legacy_paper
node_legacy_api -->|"serves files"| node_legacy_files
node_legacy_paper -->|"uses file handling"| node_legacy_files

click node_app "https://github.com/shhhivamm/studyready/blob/main/Backend/app/main.py"
click node_deps "https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/deps.py"
click node_admin "https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/admin.py"
click node_paper_routes "https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/papers.py"
click node_question_routes "https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/questions.py"
click node_extraction_flow "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/extraction/paper_extraction.py"
click node_scraper "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/cbse_scraper.py"
click node_downloader "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/downloader.py"
click node_vision "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/extraction/gemini_vision.py"
click node_embeddings "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/embeddings/gemini_embeddings.py"
click node_search "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/search.py"
click node_selector "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/selector.py"
click node_strategies "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/strategies.py"
click node_generator "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/generation/paper_generator.py"
click node_blueprint "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/blueprint_extractor.py"
click node_database "https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/models.py"
click node_connection "https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/connection.py"
click node_repository "https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/repository.py"
click node_pdf_export "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/export/pdf.py"
click node_docx_export "https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/export/docx.py"
click node_legacy_api "https://github.com/shhhivamm/studyready/blob/main/Backend/services/api.py"
click node_legacy_files "https://github.com/shhhivamm/studyready/blob/main/Backend/services/files.py"
click node_legacy_paper "https://github.com/shhhivamm/studyready/blob/main/Backend/services/get_paper.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_deps,node_admin,node_paper_routes,node_question_routes,node_legacy_api,node_legacy_paper,node_user toneBlue
class node_extraction_flow,node_scraper,node_downloader,node_vision toneAmber
class node_embeddings,node_search,node_selector,node_strategies,node_generator,node_blueprint,node_llm toneMint
class node_database,node_connection,node_repository,node_pdf_export,node_docx_export,node_legacy_files toneRose
class node_cbse toneIndigo
```

## Components

### API

- [FastAPI app](https://github.com/shhhivamm/studyready/blob/main/Backend/app/main.py): `Backend/app/main.py`
- [Request dependencies](https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/deps.py): `Backend/app/api/deps.py`
- [Admin routes](https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/admin.py): `Backend/app/api/routes/admin.py`
- [Paper routes](https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/papers.py): `Backend/app/api/routes/papers.py`
- [Question routes](https://github.com/shhhivamm/studyready/blob/main/Backend/app/api/routes/questions.py): `Backend/app/api/routes/questions.py`
- [Legacy paper API](https://github.com/shhhivamm/studyready/blob/main/Backend/services/api.py): `Backend/services/api.py`
- [Legacy paper lookup](https://github.com/shhhivamm/studyready/blob/main/Backend/services/get_paper.py): `Backend/services/get_paper.py`

### Paper ingestion

- [Extraction workflow](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/extraction/paper_extraction.py): `Backend/app/services/extraction/paper_extraction.py`
- [CBSE scraper](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/cbse_scraper.py): `Backend/app/services/papers/cbse_scraper.py`
- [PDF downloader](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/downloader.py): `Backend/app/services/papers/downloader.py`
- [Vision extraction](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/extraction/gemini_vision.py): `Backend/app/services/extraction/gemini_vision.py`

### Retrieval and generation

- [Embedding service](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/embeddings/gemini_embeddings.py): `Backend/app/services/embeddings/gemini_embeddings.py`
- [Question search](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/search.py): `Backend/app/services/retrieval/search.py`
- [Question selection](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/selector.py): `Backend/app/services/retrieval/selector.py`
- [Selection strategies](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/retrieval/strategies.py): `Backend/app/services/retrieval/strategies.py`
- [Paper generation](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/generation/paper_generator.py): `Backend/app/services/generation/paper_generator.py`
- [Blueprint extraction](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/papers/blueprint_extractor.py): `Backend/app/services/papers/blueprint_extractor.py`

### Data and export

- [PostgreSQL / pgvector](https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/models.py): `Backend/app/database/models.py`
- [Database sessions](https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/connection.py): `Backend/app/database/connection.py`
- [Data repository](https://github.com/shhhivamm/studyready/blob/main/Backend/app/database/repository.py): `Backend/app/database/repository.py`
- [PDF export](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/export/pdf.py): `Backend/app/services/export/pdf.py`
- [DOCX export](https://github.com/shhhivamm/studyready/blob/main/Backend/app/services/export/docx.py): `Backend/app/services/export/docx.py`
- [Legacy file handling](https://github.com/shhhivamm/studyready/blob/main/Backend/services/files.py): `Backend/services/files.py`

### Other components

- **API client**
- **CBSE website**
- **OpenRouter models**

## Connections

- API client → FastAPI app: sends requests (evidence: `Backend/app/main.py`)
- FastAPI app → Admin routes: registers routes (evidence: `Backend/app/main.py`)
- FastAPI app → Paper routes: registers routes (evidence: `Backend/app/main.py`)
- FastAPI app → Question routes: registers routes (evidence: `Backend/app/main.py`)
- Admin routes → Extraction workflow: starts extraction (evidence: `Backend/app/api/routes/admin.py`)
- Paper routes → Question selection: selects questions (evidence: `Backend/app/api/routes/papers.py`)
- Paper routes → Selection strategies: applies strategies (evidence: `Backend/app/api/routes/papers.py`)
- Paper routes → Paper generation: formats paper (evidence: `Backend/app/api/routes/papers.py`)
- Paper routes → Blueprint extraction: extracts blueprint (evidence: `Backend/app/api/routes/papers.py`)
- Paper routes → PDF export: creates PDF (evidence: `Backend/app/api/routes/papers.py`)
- Paper routes → DOCX export: exports DOCX (evidence: `README.md`)
- Question routes → Question search: searches questions (evidence: `Backend/app/api/routes/questions.py`)
- Extraction workflow → CBSE scraper: finds source papers (evidence: `Backend/app/services/extraction/paper_extraction.py`)
- Extraction workflow → PDF downloader: downloads PDFs (evidence: `Backend/app/services/extraction/paper_extraction.py`)
- Extraction workflow → Vision extraction: extracts questions (evidence: `Backend/app/services/extraction/paper_extraction.py`)
- Extraction workflow → Embedding service: embeds questions (evidence: `Backend/app/services/extraction/paper_extraction.py`)
- Extraction workflow → PostgreSQL / pgvector: stores questions (evidence: `Backend/app/services/extraction/paper_extraction.py`)
- CBSE scraper → CBSE website: scrapes papers (evidence: `README.md`)
- PDF downloader → CBSE website: downloads PDFs (evidence: `README.md`)
- Vision extraction → OpenRouter models: requests extraction (evidence: `README.md`)
- Paper generation → OpenRouter models: requests formatting (evidence: `README.md`)
- Question search → Embedding service: embeds query (evidence: `Backend/app/services/retrieval/search.py`)
- Question search → PostgreSQL / pgvector: queries vectors (evidence: `Backend/app/services/retrieval/search.py`)
- Question selection → PostgreSQL / pgvector: uses question records (evidence: `Backend/app/services/retrieval/selector.py`)
- Selection strategies → PostgreSQL / pgvector: uses question records (evidence: `Backend/app/services/retrieval/strategies.py`)
- Paper generation → PostgreSQL / pgvector: uses paper records (evidence: `Backend/app/services/generation/paper_generator.py`)
- Paper routes → PostgreSQL / pgvector: reads and saves papers (evidence: `Backend/app/api/routes/papers.py`)
- Request dependencies → Database sessions: provides sessions (evidence: `Backend/app/api/deps.py`)
- Database sessions → PostgreSQL / pgvector: configures ORM (evidence: `Backend/app/database/models.py`)
- Legacy paper API → Legacy paper lookup: looks up papers (evidence: `Backend/services/api.py`)
- Legacy paper API → Legacy file handling: serves files (evidence: `Backend/services/api.py`)
- Legacy paper lookup → Legacy file handling: uses file handling (evidence: `Backend/services/get_paper.py`)
