# prepvector/self-assessment architecture

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

- Interactive diagram: https://gitdiagram.com/prepvector/self-assessment
- Repository: https://github.com/prepvector/self-assessment

## Overview

PrepVector is a candidate-facing Data Science assessment platform. A candidate enters their name, takes a dynamically sampled quiz, submits answers for weighted scoring and AI-assisted analysis, then receives a generated PDF report that can be downloaded and emailed. The README also describes CSV and Google Sheets persistence and benchmark-based reporting. The graph preserves these documented capabilities; some submission, report, and download wiring is described by the README because the corresponding source excerpts are partial.

Main entry points: [`frontend/src/components/QuizComponent.jsx`](https://github.com/prepvector/self-assessment/blob/main/frontend/src/components/QuizComponent.jsx) (Quiz experience), [`backend/app/api/submit_answers.py`](https://github.com/prepvector/self-assessment/blob/main/backend/app/api/submit_answers.py) (Submission and scoring), [`backend/app/agents/report_writer.py`](https://github.com/prepvector/self-assessment/blob/main/backend/app/agents/report_writer.py) (Report analysis and PDF), [`frontend/src/App.jsx`](https://github.com/prepvector/self-assessment/blob/main/frontend/src/App.jsx) (Frontend app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_candidate_ui["Candidate experience"]
  node_app["Frontend app<br/>[App.jsx]"]
  node_intake["Name intake<br/>[AuthModal.jsx]"]
  node_quiz_ui["Quiz experience<br/>[QuizComponent.jsx]"]
end

subgraph group_assessment["Quiz and scoring"]
  node_api["FastAPI app<br/>[main.py]"]
  node_quiz_api["Quiz generation<br/>[generate_quiz.py]"]
  node_bank["Question bank<br/>[question_bank.json]"]
  node_submission["Submission and scoring<br/>[submit_answers.py]"]
end

subgraph group_reporting["Analysis and reports"]
  node_report_agent["Report analysis and PDF<br/>[report_writer.py]"]
  node_defaults["Benchmarks and ratings<br/>[report_defaults.py]"]
  node_charts["Score charts<br/>[chart_generator.py]"]
  node_download["Report download<br/>[download_report.py]"]
  node_email["Report email<br/>[email_service.py]"]
end

subgraph group_persistence["Result persistence"]
  node_csv[("Assessment log")]
  node_sheets["Sheets sync<br/>[google_sheets.py]"]
end

subgraph group_integrations["External services"]
  node_gemini["Gemini"]
  node_groq["Groq fallback"]
  node_google_sheets[("Google Sheets")]
  node_smtp["Hostinger SMTP"]
end

node_candidate(("Candidate"))

node_candidate -->|"uses"| node_app
node_app -->|"opens"| node_intake
node_intake -->|"returns name"| node_app
node_app -->|"shows quiz"| node_quiz_ui
node_quiz_ui -->|"requests quiz"| node_api
node_api -->|"routes"| node_quiz_api
node_quiz_api -->|"samples questions"| node_bank
node_quiz_api -->|"returns quiz"| node_quiz_ui
node_quiz_ui -->|"submits answers"| node_api
node_api -->|"routes"| node_submission
node_submission -->|"logs results"| node_csv
node_submission -->|"syncs results"| node_sheets
node_sheets -->|"updates rows"| node_google_sheets
node_submission -->|"builds report"| node_report_agent
node_report_agent -->|"requests analysis"| node_gemini
node_report_agent -.->|"fallback analysis"| node_groq
node_report_agent -->|"uses benchmarks"| node_defaults
node_report_agent -->|"generates charts"| node_charts
node_submission -->|"dispatches report"| node_email
node_email -->|"sends attachment"| node_smtp
node_quiz_ui -->|"requests report"| node_download
node_download -->|"returns PDF"| node_quiz_ui

click node_app "https://github.com/prepvector/self-assessment/blob/main/frontend/src/App.jsx"
click node_intake "https://github.com/prepvector/self-assessment/blob/main/frontend/src/components/AuthModal.jsx"
click node_quiz_ui "https://github.com/prepvector/self-assessment/blob/main/frontend/src/components/QuizComponent.jsx"
click node_api "https://github.com/prepvector/self-assessment/blob/main/backend/app/main.py"
click node_quiz_api "https://github.com/prepvector/self-assessment/blob/main/backend/app/api/generate_quiz.py"
click node_bank "https://github.com/prepvector/self-assessment/blob/main/backend/data/question_bank.json"
click node_submission "https://github.com/prepvector/self-assessment/blob/main/backend/app/api/submit_answers.py"
click node_report_agent "https://github.com/prepvector/self-assessment/blob/main/backend/app/agents/report_writer.py"
click node_defaults "https://github.com/prepvector/self-assessment/blob/main/backend/app/config/report_defaults.py"
click node_charts "https://github.com/prepvector/self-assessment/blob/main/backend/app/utils/chart_generator.py"
click node_download "https://github.com/prepvector/self-assessment/blob/main/backend/app/api/download_report.py"
click node_email "https://github.com/prepvector/self-assessment/blob/main/backend/app/services/email_service.py"
click node_csv "https://github.com/prepvector/self-assessment/tree/main/backend/data"
click node_sheets "https://github.com/prepvector/self-assessment/blob/main/backend/app/services/google_sheets.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_intake,node_quiz_ui toneBlue
class node_api,node_quiz_api,node_bank,node_submission toneAmber
class node_report_agent,node_defaults,node_charts,node_download,node_email toneMint
class node_csv,node_sheets toneRose
class node_gemini,node_groq,node_google_sheets,node_smtp,node_candidate toneIndigo
```

## Components

### Candidate experience

- [Frontend app](https://github.com/prepvector/self-assessment/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Name intake](https://github.com/prepvector/self-assessment/blob/main/frontend/src/components/AuthModal.jsx): `frontend/src/components/AuthModal.jsx`
- [Quiz experience](https://github.com/prepvector/self-assessment/blob/main/frontend/src/components/QuizComponent.jsx): `frontend/src/components/QuizComponent.jsx`

### Quiz and scoring

- [FastAPI app](https://github.com/prepvector/self-assessment/blob/main/backend/app/main.py): `backend/app/main.py`
- [Quiz generation](https://github.com/prepvector/self-assessment/blob/main/backend/app/api/generate_quiz.py): `backend/app/api/generate_quiz.py`
- [Question bank](https://github.com/prepvector/self-assessment/blob/main/backend/data/question_bank.json): `backend/data/question_bank.json`
- [Submission and scoring](https://github.com/prepvector/self-assessment/blob/main/backend/app/api/submit_answers.py): `backend/app/api/submit_answers.py`

### Analysis and reports

- [Report analysis and PDF](https://github.com/prepvector/self-assessment/blob/main/backend/app/agents/report_writer.py): `backend/app/agents/report_writer.py`
- [Benchmarks and ratings](https://github.com/prepvector/self-assessment/blob/main/backend/app/config/report_defaults.py): `backend/app/config/report_defaults.py`
- [Score charts](https://github.com/prepvector/self-assessment/blob/main/backend/app/utils/chart_generator.py): `backend/app/utils/chart_generator.py`
- [Report download](https://github.com/prepvector/self-assessment/blob/main/backend/app/api/download_report.py): `backend/app/api/download_report.py`
- [Report email](https://github.com/prepvector/self-assessment/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`

### Result persistence

- [Assessment log](https://github.com/prepvector/self-assessment/tree/main/backend/data): `backend/data`
- [Sheets sync](https://github.com/prepvector/self-assessment/blob/main/backend/app/services/google_sheets.py): `backend/app/services/google_sheets.py`

### External services

- **Gemini**
- **Groq fallback**
- **Google Sheets**
- **Hostinger SMTP**

### Other components

- **Candidate**

## Connections

- Candidate → Frontend app: uses
- Frontend app → Name intake: opens
- Name intake → Frontend app: returns name
- Frontend app → Quiz experience: shows quiz
- Quiz experience → FastAPI app: requests quiz
- FastAPI app → Quiz generation: routes
- Quiz generation → Question bank: samples questions
- Quiz generation → Quiz experience: returns quiz
- Quiz experience → FastAPI app: submits answers
- FastAPI app → Submission and scoring: routes
- Submission and scoring → Assessment log: logs results
- Submission and scoring → Sheets sync: syncs results
- Sheets sync → Google Sheets: updates rows
- Submission and scoring → Report analysis and PDF: builds report
- Report analysis and PDF → Gemini: requests analysis
- Report analysis and PDF → Groq fallback: fallback analysis
- Report analysis and PDF → Benchmarks and ratings: uses benchmarks
- Report analysis and PDF → Score charts: generates charts
- Submission and scoring → Report email: dispatches report
- Report email → Hostinger SMTP: sends attachment
- Quiz experience → Report download: requests report
- Report download → Quiz experience: returns PDF