# akashp18/ai901-exam-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/akashp18/ai901-exam-simulator
- Repository: https://github.com/akashp18/ai901-exam-simulator
- Video tour (about a minute): https://gitdiagram.com/akashp18/ai901-exam-simulator/video

## Overview

AI-901 Ultimate Exam Simulator is a browser-based practice exam backed by a Python standard-library HTTP/API server and SQLite. The main workflow is to start a blueprint-aligned session, answer and autosave varied question types, submit for grading, and review diagnostics; users can also resume sessions and inspect past attempts. The graph reflects the sampled source and README capabilities; some backend endpoint wiring and unsampled implementation details are documented but not independently verified.

Main entry points: [`server.py`](https://github.com/akashp18/ai901-exam-simulator/blob/main/server.py) (HTTP and API server), [`js/api.js`](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/api.js) (REST client), [`js/main.js`](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/main.js) (App initialization), [`database.py`](https://github.com/akashp18/ai901-exam-simulator/blob/main/database.py) (Schema and seeding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser exam app"]
  node_page["Simulator page<br/>[index.html]"]
  node_init["App initialization<br/>[main.js]"]
  node_state["Session state<br/>[state.js]"]
  node_api["REST client<br/>[api.js]"]
  node_examui["Exam interaction<br/>[ui.js]"]
  node_timer["Exam timer<br/>[timer.js]"]
  node_reportui["Report display<br/>[report.js]"]
  node_core["Review and resume<br/>[core.js]"]
end

subgraph group_backend["Exam service"]
  node_server["HTTP and API server<br/>[server.py]"]
  node_dbsetup["Schema and seeding<br/>[database.py]"]
  node_db[("Exam database")]
end

subgraph group_content["Question content"]
  node_questions["Question bank<br/>[questions.json]"]
  node_blueprint["Exam blueprint<br/>[blueprint.json]"]
end

subgraph group_insight["Scoring and analytics"]
  node_grader["Grading and diagnostics<br/>[grader.py]"]
  node_report["Analytics report<br/>[report.js]"]
end

node_user(("Learner"))

node_user -->|"uses"| node_page
node_page -->|"loads"| node_init
node_init -->|"requests stats"| node_api
node_init -->|"loads history"| node_api
node_init -->|"restores session"| node_core
node_api -->|"calls API"| node_server
node_server -->|"serves files"| node_page
node_user -->|"answers questions"| node_examui
node_examui -->|"updates"| node_state
node_examui -->|"autosaves answers"| node_api
node_timer -->|"tracks time"| node_state
node_api -->|"starts session"| node_server
node_server -->|"reads and writes"| node_db
node_server -->|"requests grading"| node_grader
node_grader -->|"returns diagnostics"| node_server
node_server -->|"returns report"| node_reportui
node_reportui -->|"presents results"| node_user
node_dbsetup -->|"creates schema"| node_db
node_dbsetup -.->|"seeds questions"| node_questions
node_dbsetup -.->|"uses blueprint"| node_blueprint
node_core -->|"loads past report"| node_api
node_reportui -->|"exports study guide"| node_core

click node_page "https://github.com/akashp18/ai901-exam-simulator/blob/main/index.html"
click node_init "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/main.js"
click node_state "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/state.js"
click node_api "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/api.js"
click node_examui "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/ui.js"
click node_timer "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/timer.js"
click node_reportui "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/report.js"
click node_core "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/core.js"
click node_server "https://github.com/akashp18/ai901-exam-simulator/blob/main/server.py"
click node_dbsetup "https://github.com/akashp18/ai901-exam-simulator/blob/main/database.py"
click node_questions "https://github.com/akashp18/ai901-exam-simulator/blob/main/data/questions.json"
click node_blueprint "https://github.com/akashp18/ai901-exam-simulator/blob/main/data/blueprint.json"
click node_grader "https://github.com/akashp18/ai901-exam-simulator/blob/main/grader.py"
click node_report "https://github.com/akashp18/ai901-exam-simulator/blob/main/js/report.js"

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_page,node_init,node_state,node_api,node_examui,node_timer,node_reportui,node_core toneBlue
class node_server,node_dbsetup,node_db toneAmber
class node_questions,node_blueprint toneMint
class node_grader,node_report toneRose
class node_user toneIndigo
```

## Components

### Browser exam app

- [Simulator page](https://github.com/akashp18/ai901-exam-simulator/blob/main/index.html): `index.html`
- [App initialization](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/main.js): `js/main.js`
- [Session state](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/state.js): `js/state.js`
- [REST client](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/api.js): `js/api.js`
- [Exam interaction](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/ui.js): `js/ui.js`
- [Exam timer](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/timer.js): `js/timer.js`
- [Report display](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/report.js): `js/report.js`
- [Review and resume](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/core.js): `js/core.js`

### Exam service

- [HTTP and API server](https://github.com/akashp18/ai901-exam-simulator/blob/main/server.py): `server.py`
- [Schema and seeding](https://github.com/akashp18/ai901-exam-simulator/blob/main/database.py): `database.py`
- **Exam database**

### Question content

- [Question bank](https://github.com/akashp18/ai901-exam-simulator/blob/main/data/questions.json): `data/questions.json`
- [Exam blueprint](https://github.com/akashp18/ai901-exam-simulator/blob/main/data/blueprint.json): `data/blueprint.json`

### Scoring and analytics

- [Grading and diagnostics](https://github.com/akashp18/ai901-exam-simulator/blob/main/grader.py): `grader.py`
- [Analytics report](https://github.com/akashp18/ai901-exam-simulator/blob/main/js/report.js): `js/report.js`

### Other components

- **Learner**

## Connections

- Learner → Simulator page: uses
- Simulator page → App initialization: loads
- App initialization → REST client: requests stats
- App initialization → REST client: loads history
- App initialization → Review and resume: restores session
- REST client → HTTP and API server: calls API
- HTTP and API server → Simulator page: serves files
- Learner → Exam interaction: answers questions
- Exam interaction → Session state: updates
- Exam interaction → REST client: autosaves answers
- Exam timer → Session state: tracks time
- REST client → HTTP and API server: starts session
- HTTP and API server → Exam database: reads and writes
- HTTP and API server → Grading and diagnostics: requests grading
- Grading and diagnostics → HTTP and API server: returns diagnostics
- HTTP and API server → Report display: returns report
- Report display → Learner: presents results
- Schema and seeding → Exam database: creates schema
- Schema and seeding → Question bank: seeds questions
- Schema and seeding → Exam blueprint: uses blueprint
- Review and resume → REST client: loads past report
- Report display → Review and resume: exports study guide