# cyberrisk-assessment-system/cyberrisk-assessment architecture

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

- Interactive diagram: https://gitdiagram.com/cyberrisk-assessment-system/cyberrisk-assessment
- Repository: https://github.com/cyberrisk-assessment-system/cyberrisk-assessment

## Overview

CyberRisk Assessment is a multi-module participant study backed by a FastAPI service and presented through a Next.js web app. The documented participant journey is registration, a forced-choice questionnaire, visual scenarios, then the Digital Shadows game; a shared participant ID ties module responses together. The backend stores sessions and responses, computes questionnaire and game results, and supports cross-module researcher reports and CSV exports. README-described frontend capabilities are included, but the supplied tree does not expose the image page or game runtime source. Some backend links are therefore omitted where excerpts do not show the call.

Main entry points: [`frontends/web/app/page.tsx`](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/page.tsx) (Study journey UI), [`backend/app/modules/forced_choice/routes.py`](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/forced_choice/routes.py) (Forced-choice API), [`backend/app/modules/game/routes.py`](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/game/routes.py) (Game API), [`backend/app/core/sessions.py`](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/sessions.py) (Participants and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Participant and web"]
  node_web_journey["Study journey UI<br/>[page.tsx]"]
  node_web_proxy["API proxy<br/>[route.ts]"]
  node_registration["Participant registration<br/>[UserForm.tsx]"]
  node_questionnaire_ui["Questionnaire UI<br/>[QuestionScreen.tsx]"]
  node_image_experience["Visual scenarios"]
  node_game_experience["Digital Shadows game"]
end

subgraph group_modules["Assessment modules"]
  node_forced_choice["Forced-choice API<br/>[routes.py]"]
  node_image_module["Image assessment API<br/>[routes.py]"]
  node_game_module["Game API<br/>[routes.py]"]
end

subgraph group_storage["Participant records"]
  node_participants_sessions["Participants and sessions<br/>[sessions.py]"]
  node_persistence["Response persistence<br/>[persistence.py]"]
  node_database[("Study database<br/>[db.py]")]
end

subgraph group_scoring["Scoring engine"]
  node_latent_inference["Bayesian inference<br/>[inference.py]"]
  node_explanations["Score explanations<br/>[explainability.py]"]
  node_game_scoring["Game scoring<br/>[scoring.py]"]
  node_combined_scoring["Combined risk score<br/>[service.py]"]
end

subgraph group_research["Research administration"]
  node_admin_console["Researcher console<br/>[AdminDashboard.tsx]"]
  node_admin_api["Admin reports and exports<br/>[routes.py]"]
  node_admin_auth["Admin session login<br/>[route.ts]"]
end

node_participant(("Participant"))

node_participant -->|"uses"| node_web_journey
node_web_journey -->|"registers"| node_registration
node_web_journey -->|"starts with"| node_questionnaire_ui
node_questionnaire_ui -.->|"submits through"| node_web_proxy
node_web_proxy -->|"proxies requests"| node_forced_choice
node_web_journey -->|"continues to"| node_image_experience
node_image_experience -.->|"submits answers"| node_image_module
node_web_journey -->|"continues to"| node_game_experience
node_game_experience -->|"logs choices"| node_game_module
node_forced_choice -->|"runs inference"| node_latent_inference
node_forced_choice -->|"builds narrative"| node_explanations
node_forced_choice -->|"opens session"| node_participants_sessions
node_forced_choice -->|"stores answers"| node_persistence
node_image_module -->|"opens session"| node_participants_sessions
node_image_module -->|"upserts responses"| node_persistence
node_game_module -->|"opens session"| node_participants_sessions
node_game_module -->|"upserts responses"| node_persistence
node_game_module -->|"evaluates answers"| node_game_scoring
node_participants_sessions -.->|"stores records"| node_database
node_persistence -.->|"writes records"| node_database
node_participant -->|"progress reviewed by"| node_admin_console
node_admin_console -.->|"logs in through"| node_admin_auth
node_admin_console -.->|"requests reports"| node_admin_api
node_admin_api -->|"computes summaries"| node_combined_scoring
node_admin_api -->|"queries records"| node_database

click node_web_journey "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/page.tsx"
click node_web_proxy "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/api/%5B...proxy%5D/route.ts"
click node_registration "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/UserForm.tsx"
click node_questionnaire_ui "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/QuestionScreen.tsx"
click node_game_experience "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/tree/main/frontends/game"
click node_forced_choice "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/forced_choice/routes.py"
click node_image_module "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/image/routes.py"
click node_game_module "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/game/routes.py"
click node_participants_sessions "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/sessions.py"
click node_persistence "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/persistence.py"
click node_database "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/db.py"
click node_latent_inference "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/scoring/inference.py"
click node_explanations "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/scoring/explainability.py"
click node_game_scoring "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/game/scoring.py"
click node_combined_scoring "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/combined/service.py"
click node_admin_console "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/admin/AdminDashboard.tsx"
click node_admin_api "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/admin/routes.py"
click node_admin_auth "https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/api/admin/login/route.ts"

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_web_journey,node_web_proxy,node_registration,node_questionnaire_ui,node_image_experience,node_game_experience toneBlue
class node_forced_choice,node_image_module,node_game_module toneAmber
class node_participants_sessions,node_persistence,node_database toneMint
class node_latent_inference,node_explanations,node_game_scoring,node_combined_scoring toneRose
class node_admin_console,node_admin_api,node_admin_auth,node_participant toneIndigo
```

## Components

### Participant and web

- [Study journey UI](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/page.tsx): `frontends/web/app/page.tsx`
- [API proxy](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/api/%5B...proxy%5D/route.ts): `frontends/web/app/api/[...proxy]/route.ts`
- [Participant registration](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/UserForm.tsx): `frontends/web/components/UserForm.tsx`
- [Questionnaire UI](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/QuestionScreen.tsx): `frontends/web/components/QuestionScreen.tsx`
- **Visual scenarios**
- [Digital Shadows game](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/tree/main/frontends/game): `frontends/game`

### Assessment modules

- [Forced-choice API](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/forced_choice/routes.py): `backend/app/modules/forced_choice/routes.py`
- [Image assessment API](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/image/routes.py): `backend/app/modules/image/routes.py`
- [Game API](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/game/routes.py): `backend/app/modules/game/routes.py`

### Participant records

- [Participants and sessions](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/sessions.py): `backend/app/core/sessions.py`
- [Response persistence](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/persistence.py): `backend/app/core/persistence.py`
- [Study database](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/core/db.py): `backend/app/core/db.py`

### Scoring engine

- [Bayesian inference](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/scoring/inference.py): `backend/app/scoring/inference.py`
- [Score explanations](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/scoring/explainability.py): `backend/app/scoring/explainability.py`
- [Game scoring](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/modules/game/scoring.py): `backend/app/modules/game/scoring.py`
- [Combined risk score](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/combined/service.py): `backend/app/combined/service.py`

### Research administration

- [Researcher console](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/components/admin/AdminDashboard.tsx): `frontends/web/components/admin/AdminDashboard.tsx`
- [Admin reports and exports](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/backend/app/admin/routes.py): `backend/app/admin/routes.py`
- [Admin session login](https://github.com/cyberrisk-assessment-system/cyberrisk-assessment/blob/main/frontends/web/app/api/admin/login/route.ts): `frontends/web/app/api/admin/login/route.ts`

### Other components

- **Participant**

## Connections

- Participant → Study journey UI: uses
- Study journey UI → Participant registration: registers
- Study journey UI → Questionnaire UI: starts with
- Questionnaire UI → API proxy: submits through
- API proxy → Forced-choice API: proxies requests (evidence: `frontends/web/app/api/[...proxy]/route.ts`)
- Study journey UI → Visual scenarios: continues to
- Visual scenarios → Image assessment API: submits answers
- Study journey UI → Digital Shadows game: continues to
- Digital Shadows game → Game API: logs choices
- Forced-choice API → Bayesian inference: runs inference (evidence: `backend/app/modules/forced_choice/routes.py`)
- Forced-choice API → Score explanations: builds narrative (evidence: `backend/app/modules/forced_choice/routes.py`)
- Forced-choice API → Participants and sessions: opens session (evidence: `backend/app/modules/forced_choice/routes.py`)
- Forced-choice API → Response persistence: stores answers (evidence: `backend/app/modules/forced_choice/routes.py`)
- Image assessment API → Participants and sessions: opens session (evidence: `backend/app/modules/image/routes.py`)
- Image assessment API → Response persistence: upserts responses (evidence: `backend/app/modules/image/routes.py`)
- Game API → Participants and sessions: opens session (evidence: `backend/app/modules/game/routes.py`)
- Game API → Response persistence: upserts responses (evidence: `backend/app/modules/game/routes.py`)
- Game API → Game scoring: evaluates answers (evidence: `backend/app/modules/game/routes.py`)
- Participants and sessions → Study database: stores records
- Response persistence → Study database: writes records
- Participant → Researcher console: progress reviewed by
- Researcher console → Admin session login: logs in through
- Researcher console → Admin reports and exports: requests reports
- Admin reports and exports → Combined risk score: computes summaries (evidence: `backend/app/admin/routes.py`)
- Admin reports and exports → Study database: queries records (evidence: `backend/app/admin/routes.py`)