# matveykonkin/shaverma_maxbot architecture

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

- Interactive diagram: https://gitdiagram.com/matveykonkin/shaverma_maxbot
- Repository: https://github.com/matveykonkin/shaverma_maxbot

## Overview

InternCheck MAX is a MAX chat bot for a first-pass Python Backend internship self-check. The user sends a job description; the bot validates it, detects supported skills, selects a prepared test, conducts it one question at a time, then reports scores and review material. It also supports cancellation/restart, history, and user statistics. SQLite persists sessions, answers, and completed results. The runtime excerpts show the main orchestration and scoring; some test-selection and reporting details are documented in the README but their implementation was not sampled.

Main entry points: [`app/main.py`](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/main.py) (Polling and dialogue), [`app/services/analyzer.py`](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/analyzer.py) (Skill detection), [`app/services/test_engine.py`](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/test_engine.py) (Test selection), [`app/services/scoring.py`](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/scoring.py) (Scoring and thresholds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["MAX conversation"]
  node_bot["Polling and dialogue<br/>[main.py]"]
  node_input["Input parsing<br/>[parsing.py]"]
end

subgraph group_assessment["Assessment flow"]
  node_analysis["Skill detection<br/>[analyzer.py]"]
  node_selection["Test selection<br/>[test_engine.py]"]
  node_question_flow["Question validation<br/>[test_engine.py]"]
  node_scoring["Scoring and thresholds<br/>[scoring.py]"]
  node_feedback["Error explanations<br/>[feedback.py]"]
end

subgraph group_content["Assessment content"]
  node_loader["JSON loader<br/>[data_loader.py]"]
  node_skills["Skill taxonomy<br/>[skills.json]"]
  node_question_sets["Question banks"]
  node_rules["Evaluation rules"]
  node_materials["Review materials"]
end

subgraph group_persistence["User records"]
  node_database[("SQLite records<br/>[database.py]")]
  node_sqlite[("SQLite database<br/>[interncheck.db]")]
end

node_user(("MAX user"))
node_max["MAX platform"]

node_user -->|"sends messages"| node_max
node_max -->|"delivers events"| node_bot
node_bot -->|"sends replies"| node_max
node_bot -->|"validates text"| node_input
node_bot -->|"detects skills"| node_analysis
node_analysis -->|"normalizes text"| node_input
node_analysis -->|"loads taxonomy"| node_skills
node_bot -->|"chooses test"| node_selection
node_selection -->|"loads questions"| node_question_sets
node_bot -->|"validates test"| node_question_flow
node_bot -->|"calculates result"| node_scoring
node_scoring -->|"loads thresholds"| node_rules
node_bot -->|"builds review"| node_feedback
node_feedback -->|"finds resources"| node_materials
node_bot -->|"reads and writes"| node_database
node_database -->|"persists records"| node_sqlite

click node_bot "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/main.py"
click node_input "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/parsing.py"
click node_analysis "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/analyzer.py"
click node_selection "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/test_engine.py"
click node_question_flow "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/test_engine.py"
click node_scoring "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/scoring.py"
click node_feedback "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/feedback.py"
click node_loader "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/utils/data_loader.py"
click node_skills "https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/skills.json"
click node_question_sets "https://github.com/matveykonkin/shaverma_maxbot/tree/main/data/tests"
click node_rules "https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/evaluation_rules.json"
click node_materials "https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/learning_materials.json"
click node_database "https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/database.py"
click node_sqlite "https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/interncheck.db"

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_bot,node_input,node_user toneBlue
class node_analysis,node_selection,node_question_flow,node_scoring,node_feedback toneAmber
class node_loader,node_skills,node_question_sets,node_rules,node_materials toneMint
class node_database,node_sqlite toneRose
class node_max toneIndigo
```

## Components

### MAX conversation

- [Polling and dialogue](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/main.py): `app/main.py`
- [Input parsing](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/parsing.py): `app/parsing.py`

### Assessment flow

- [Skill detection](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/analyzer.py): `app/services/analyzer.py`
- [Test selection](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/test_engine.py): `app/services/test_engine.py`
- [Question validation](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/test_engine.py): `app/services/test_engine.py`
- [Scoring and thresholds](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/scoring.py): `app/services/scoring.py`
- [Error explanations](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/services/feedback.py): `app/services/feedback.py`

### Assessment content

- [JSON loader](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/utils/data_loader.py): `app/utils/data_loader.py`
- [Skill taxonomy](https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/skills.json): `data/skills.json`
- [Question banks](https://github.com/matveykonkin/shaverma_maxbot/tree/main/data/tests): `data/tests`
- [Evaluation rules](https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/evaluation_rules.json): `data/evaluation_rules.json`
- [Review materials](https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/learning_materials.json): `data/learning_materials.json`

### User records

- [SQLite records](https://github.com/matveykonkin/shaverma_maxbot/blob/main/app/database.py): `app/database.py`
- [SQLite database](https://github.com/matveykonkin/shaverma_maxbot/blob/main/data/interncheck.db): `data/interncheck.db`

### Other components

- **MAX user**
- **MAX platform**

## Connections

- MAX user → MAX platform: sends messages (evidence: `README.md`)
- MAX platform → Polling and dialogue: delivers events (evidence: `README.md`)
- Polling and dialogue → MAX platform: sends replies (evidence: `app/main.py`)
- Polling and dialogue → Input parsing: validates text (evidence: `README.md`)
- Polling and dialogue → Skill detection: detects skills (evidence: `README.md`)
- Skill detection → Input parsing: normalizes text (evidence: `app/services/analyzer.py`)
- Skill detection → Skill taxonomy: loads taxonomy (evidence: `app/services/analyzer.py`)
- Polling and dialogue → Test selection: chooses test (evidence: `README.md`)
- Test selection → Question banks: loads questions (evidence: `README.md`)
- Polling and dialogue → Question validation: validates test (evidence: `app/main.py`)
- Polling and dialogue → Scoring and thresholds: calculates result (evidence: `app/main.py`)
- Scoring and thresholds → Evaluation rules: loads thresholds (evidence: `app/services/scoring.py`)
- Polling and dialogue → Error explanations: builds review (evidence: `README.md`)
- Error explanations → Review materials: finds resources (evidence: `README.md`)
- Polling and dialogue → SQLite records: reads and writes (evidence: `app/main.py`)
- SQLite records → SQLite database: persists records (evidence: `app/database.py`)