# northstar-vdwrx/evalbackend architecture

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

- Interactive diagram: https://gitdiagram.com/northstar-vdwrx/evalbackend
- Repository: https://github.com/northstar-vdwrx/evalbackend

## Overview

EvalBackend is a FastAPI assessment API. Its central workflow is quiz and question authoring, scheduling an exam session, accepting student attempts, and grading answers; administration, identity, groups, institutes, and analytics are additional product areas. The app factory registers the route families, while route handlers use the shared database dependency and domain models. Several route families are represented from the file tree and source index rather than inspected excerpts, so their internal connections are not inferred.

Main entry points: [`app/__init__.py`](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/__init__.py) (FastAPI app), [`db.py`](https://github.com/northstar-vdwrx/evalbackend/blob/main/db.py) (DB connection pool), [`app/routes/quiz/questions.py`](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/questions.py) (Question authoring), [`app/routes/exams/attempts.py`](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/attempts.py) (Exam attempts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_factory["FastAPI app<br/>[__init__.py]"]
  node_home["Home routes<br/>[home.py]"]
  node_database_access["DB connection pool<br/>[db.py]"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_identity["Identity and administration"]
  node_auth["Authentication"]
  node_admin_users["Admin users<br/>[users.py]"]
  node_admin_settings["Admin settings<br/>[settings.py]"]
end

subgraph group_authoring["Assessment authoring"]
  node_quiz_banks["Quiz banks<br/>[banks.py]"]
  node_quiz_crud["Quiz management<br/>[crud.py]"]
  node_question_authoring["Question authoring<br/>[questions.py]"]
  node_question_storage["Question storage"]
  node_quiz_structure["Quiz structure<br/>[structure.py]"]
  node_quiz_import["Quiz import/export<br/>[import_export.py]"]
  node_parameterization["Question parameterization"]
end

subgraph group_delivery["Exam delivery"]
  node_exam_sessions["Exam sessions<br/>[scheduled.py]"]
  node_attempts["Exam attempts<br/>[attempts.py]"]
  node_grading["Grading<br/>[grading.py]"]
  node_analytics["Student analytics"]
  node_practice["Practice<br/>[practice.py]"]
end

subgraph group_community["User and institution management"]
  node_profiles["Extended profiles<br/>[extended_users.py]"]
  node_institutes["Institutes<br/>[router.py]"]
  node_groups["Groups<br/>[router.py]"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]

node_client -.->|"sends API requests"| node_factory
node_factory -->|"registers routes"| node_home
node_factory -->|"registers routes"| node_auth
node_factory -->|"registers routes"| node_admin_users
node_factory -->|"registers routes"| node_admin_settings
node_factory -->|"registers routes"| node_profiles
node_factory -->|"registers routes"| node_institutes
node_factory -->|"registers routes"| node_groups
node_factory -->|"registers routes"| node_quiz_banks
node_factory -->|"registers routes"| node_quiz_crud
node_factory -->|"registers routes"| node_question_authoring
node_factory -->|"registers routes"| node_quiz_structure
node_factory -->|"registers routes"| node_quiz_import
node_factory -->|"registers routes"| node_exam_sessions
node_factory -->|"registers routes"| node_analytics
node_factory -->|"registers routes"| node_practice
node_factory -->|"registers routes"| node_attempts
node_question_authoring -->|"stores questions"| node_question_storage
node_attempts -->|"auto-grades answers"| node_grading
node_attempts -->|"materializes questions"| node_parameterization
node_question_authoring -->|"regrades attempts"| node_grading
node_auth -->|"gets connections"| node_database_access
node_groups -->|"gets connections"| node_database_access
node_institutes -->|"gets connections"| node_database_access
node_profiles -->|"gets connections"| node_database_access
node_admin_users -->|"gets connections"| node_database_access
node_quiz_banks -->|"gets connections"| node_database_access
node_question_authoring -->|"gets connections"| node_database_access
node_question_storage -->|"writes questions"| node_postgres
node_database_access -->|"pools connections"| node_postgres

click node_factory "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/__init__.py"
click node_home "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/home.py"
click node_database_access "https://github.com/northstar-vdwrx/evalbackend/blob/main/db.py"
click node_auth "https://github.com/northstar-vdwrx/evalbackend/tree/main/app/routes/auth"
click node_admin_users "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/admin/users.py"
click node_admin_settings "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/admin/settings.py"
click node_profiles "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/profiles/extended_users.py"
click node_institutes "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/institutes/router.py"
click node_groups "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/groups/router.py"
click node_quiz_banks "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/banks.py"
click node_quiz_crud "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/crud.py"
click node_question_authoring "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/questions.py"
click node_question_storage "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/question_storage.py"
click node_quiz_structure "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/structure.py"
click node_quiz_import "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/import_export.py"
click node_parameterization "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/parameterization.py"
click node_exam_sessions "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/scheduled.py"
click node_attempts "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/attempts.py"
click node_grading "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/grading.py"
click node_analytics "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/student_analytics.py"
click node_practice "https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/practice.py"
click node_models "https://github.com/northstar-vdwrx/evalbackend/blob/main/models.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_factory,node_home,node_database_access,node_models,node_client toneBlue
class node_auth,node_admin_users,node_admin_settings,node_postgres toneAmber
class node_quiz_banks,node_quiz_crud,node_question_authoring,node_question_storage,node_quiz_structure,node_quiz_import,node_parameterization toneMint
class node_exam_sessions,node_attempts,node_grading,node_analytics,node_practice toneRose
class node_profiles,node_institutes,node_groups toneIndigo
```

## Components

### API entry

- [FastAPI app](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/__init__.py): `app/__init__.py`
- [Home routes](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/home.py): `app/routes/home.py`
- [DB connection pool](https://github.com/northstar-vdwrx/evalbackend/blob/main/db.py): `db.py`
- [Domain models](https://github.com/northstar-vdwrx/evalbackend/blob/main/models.py): `models.py`

### Identity and administration

- [Authentication](https://github.com/northstar-vdwrx/evalbackend/tree/main/app/routes/auth): `app/routes/auth`
- [Admin users](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/admin/users.py): `app/routes/admin/users.py`
- [Admin settings](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/admin/settings.py): `app/routes/admin/settings.py`

### Assessment authoring

- [Quiz banks](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/banks.py): `app/routes/quiz/banks.py`
- [Quiz management](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/crud.py): `app/routes/quiz/crud.py`
- [Question authoring](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/questions.py): `app/routes/quiz/questions.py`
- [Question storage](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/question_storage.py): `app/routes/quiz/question_storage.py`
- [Quiz structure](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/structure.py): `app/routes/quiz/structure.py`
- [Quiz import/export](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/import_export.py): `app/routes/quiz/import_export.py`
- [Question parameterization](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/quiz/parameterization.py): `app/routes/quiz/parameterization.py`

### Exam delivery

- [Exam sessions](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/scheduled.py): `app/routes/exams/scheduled.py`
- [Exam attempts](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/attempts.py): `app/routes/exams/attempts.py`
- [Grading](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/grading.py): `app/routes/exams/grading.py`
- [Student analytics](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/exams/student_analytics.py): `app/routes/exams/student_analytics.py`
- [Practice](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/practice.py): `app/routes/practice.py`

### User and institution management

- [Extended profiles](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/profiles/extended_users.py): `app/routes/profiles/extended_users.py`
- [Institutes](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/institutes/router.py): `app/routes/institutes/router.py`
- [Groups](https://github.com/northstar-vdwrx/evalbackend/blob/main/app/routes/groups/router.py): `app/routes/groups/router.py`

### Other components

- **API client**
- **PostgreSQL**

## Connections

- API client → FastAPI app: sends API requests
- FastAPI app → Home routes: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Authentication: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Admin users: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Admin settings: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Extended profiles: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Institutes: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Groups: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Quiz banks: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Quiz management: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Question authoring: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Quiz structure: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Quiz import/export: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Exam sessions: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Student analytics: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Practice: registers routes (evidence: `app/__init__.py`)
- FastAPI app → Exam attempts: registers routes (evidence: `app/__init__.py`)
- Question authoring → Question storage: stores questions (evidence: `app/routes/quiz/questions.py`)
- Exam attempts → Grading: auto-grades answers (evidence: `app/routes/exams/attempts.py`)
- Exam attempts → Question parameterization: materializes questions (evidence: `app/routes/exams/attempts.py`)
- Question authoring → Grading: regrades attempts (evidence: `app/routes/quiz/questions.py`)
- Authentication → DB connection pool: gets connections (evidence: `app/routes/auth/security.py`)
- Groups → DB connection pool: gets connections (evidence: `app/routes/groups/router.py`)
- Institutes → DB connection pool: gets connections (evidence: `app/routes/institutes/router.py`)
- Extended profiles → DB connection pool: gets connections (evidence: `app/routes/profiles/extended_users.py`)
- Admin users → DB connection pool: gets connections (evidence: `app/routes/admin/users.py`)
- Quiz banks → DB connection pool: gets connections (evidence: `app/routes/quiz/banks.py`)
- Question authoring → DB connection pool: gets connections (evidence: `app/routes/quiz/questions.py`)
- Question storage → PostgreSQL: writes questions (evidence: `app/routes/quiz/question_storage.py`)
- DB connection pool → PostgreSQL: pools connections (evidence: `db.py`)
