# manhpp/malsec-public architecture

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

- Interactive diagram: https://gitdiagram.com/manhpp/malsec-public
- Repository: https://github.com/manhpp/malsec-public

## Overview

MalSec LMS supports a browser-based course workflow: users sign in, students work through labs and submit reports, and instructors review submissions and manage grades. Lab sessions can provision isolated VMs and deliver browser-based access; submissions pass through security inspection before storage. Admins manage users, classes, and semesters. The graph combines documented capabilities with sampled wiring; several routers and monitoring configurations are represented at their exact enclosing paths because their runtime internals were not sampled.

Main entry points: [`backend/app/main.py`](https://github.com/manhpp/malsec-public/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database.py`](https://github.com/manhpp/malsec-public/blob/main/backend/app/database.py) (PostgreSQL), [`frontend/src/main.jsx`](https://github.com/manhpp/malsec-public/blob/main/frontend/src/main.jsx) (React application), [`monitoring`](https://github.com/manhpp/malsec-public/tree/main/monitoring) (Monitoring configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_frontend["React application<br/>[main.jsx]"]
  node_auth_ui["Login &amp; roles<br/>[App.jsx]"]
  node_student_ui["Student workspace"]
  node_instructor_ui["Instructor tools"]
  node_admin_ui["Admin portal<br/>[AdminDashboard.jsx]"]
end

subgraph group_api["LMS API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_security["Access control<br/>[security.py]"]
  node_user_routes["User management<br/>[users.py]"]
  node_admin_routes["Administration<br/>[admin.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_models["LMS data models<br/>[models.py]"]
end

subgraph group_learning["Learning workflow"]
  node_class_routes["Classes &amp; gradebook<br/>[classes.py]"]
  node_lab_routes["Lab management<br/>[labs.py]"]
  node_semester_routes["Semester management<br/>[semesters.py]"]
  node_submission_routes["Submission workflow<br/>[submissions.py]"]
  node_file_service["File inspection<br/>[file_service.py]"]
  node_plagiarism["Similarity analysis<br/>[plagiarism.py]"]
  node_uploads[("Uploaded files")]
end

subgraph group_sandbox["VM sandbox"]
  node_vm_service["VM lifecycle &amp; VDI tokens<br/>[vm_service.py]"]
  node_proxmox["Proxmox VE"]
  node_guacamole["Apache Guacamole"]
  node_sandbox_vms["Isolated lab VMs"]
end

subgraph group_observability["Observability"]
  node_monitoring_config["Monitoring configuration"]
  node_prometheus["Prometheus"]
  node_grafana["Grafana dashboards"]
  node_loki["Loki log aggregation"]
  node_promtail["Promtail log shipping"]
end

node_users(("Students &amp; staff"))

node_users -->|"use"| node_frontend
node_frontend -->|"route to"| node_auth_ui
node_frontend -->|"route to"| node_student_ui
node_frontend -->|"route to"| node_instructor_ui
node_frontend -->|"route to"| node_admin_ui
node_auth_ui -->|"request API"| node_api_app
node_student_ui -->|"request API"| node_api_app
node_instructor_ui -->|"request API"| node_api_app
node_admin_ui -->|"request API"| node_api_app
node_api_app -->|"dispatch"| node_auth
node_api_app -->|"dispatch"| node_user_routes
node_api_app -->|"dispatch"| node_class_routes
node_api_app -->|"dispatch"| node_lab_routes
node_api_app -->|"dispatch"| node_semester_routes
node_api_app -->|"dispatch"| node_submission_routes
node_api_app -->|"dispatch"| node_admin_routes
node_auth -->|"verify credentials"| node_security
node_auth -->|"read/write accounts"| node_database
node_user_routes -->|"read/write users"| node_database
node_class_routes -->|"read/write classes"| node_database
node_class_routes -->|"manage class VMs"| node_vm_service
node_lab_routes -->|"read/write labs"| node_database
node_semester_routes -->|"read/write terms"| node_database
node_submission_routes -->|"read/write submissions"| node_database
node_submission_routes -->|"inspect uploads"| node_file_service
node_submission_routes -->|"analyze similarity"| node_plagiarism
node_file_service -->|"save inspected files"| node_uploads
node_admin_routes -->|"manage records"| node_database
node_api_app -->|"initialize data"| node_database
node_database -->|"map records"| node_models
node_student_ui -->|"request VM session"| node_api_app
node_vm_service -->|"provision &amp; reset"| node_proxmox
node_vm_service -->|"build session token"| node_guacamole
node_proxmox -->|"run isolated VMs"| node_sandbox_vms
node_guacamole -->|"connect sessions"| node_sandbox_vms
node_monitoring_config -->|"configure metrics"| node_prometheus
node_monitoring_config -->|"configure dashboards"| node_grafana
node_monitoring_config -->|"configure logs"| node_loki
node_monitoring_config -->|"configure shipping"| node_promtail
node_promtail -->|"ship logs"| node_loki
node_prometheus -->|"provide metrics"| node_grafana

click node_frontend "https://github.com/manhpp/malsec-public/blob/main/frontend/src/main.jsx"
click node_auth_ui "https://github.com/manhpp/malsec-public/blob/main/frontend/src/App.jsx"
click node_student_ui "https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/StudentDashboard.jsx"
click node_instructor_ui "https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/InstructorDashboard.jsx"
click node_admin_ui "https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_api_app "https://github.com/manhpp/malsec-public/blob/main/backend/app/main.py"
click node_auth "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/auth.py"
click node_security "https://github.com/manhpp/malsec-public/blob/main/backend/app/security.py"
click node_user_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/users.py"
click node_class_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/classes.py"
click node_lab_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/labs.py"
click node_semester_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/semesters.py"
click node_submission_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/submissions.py"
click node_admin_routes "https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/admin.py"
click node_file_service "https://github.com/manhpp/malsec-public/blob/main/backend/app/services/file_service.py"
click node_plagiarism "https://github.com/manhpp/malsec-public/blob/main/backend/app/services/plagiarism.py"
click node_uploads "https://github.com/manhpp/malsec-public/tree/main/backend/app/uploads"
click node_database "https://github.com/manhpp/malsec-public/blob/main/backend/app/database.py"
click node_models "https://github.com/manhpp/malsec-public/blob/main/backend/app/models.py"
click node_vm_service "https://github.com/manhpp/malsec-public/blob/main/backend/app/services/vm_service.py"
click node_monitoring_config "https://github.com/manhpp/malsec-public/tree/main/monitoring"
click node_grafana "https://github.com/manhpp/malsec-public/tree/main/monitoring/grafana"
click node_loki "https://github.com/manhpp/malsec-public/tree/main/monitoring/loki"
click node_promtail "https://github.com/manhpp/malsec-public/tree/main/monitoring/promtail"

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_frontend,node_auth_ui,node_student_ui,node_instructor_ui,node_admin_ui toneBlue
class node_api_app,node_auth,node_security,node_user_routes,node_admin_routes,node_database,node_models toneAmber
class node_class_routes,node_lab_routes,node_semester_routes,node_submission_routes,node_file_service,node_plagiarism,node_uploads toneMint
class node_vm_service,node_proxmox,node_guacamole,node_sandbox_vms toneRose
class node_monitoring_config,node_prometheus,node_grafana,node_loki,node_promtail,node_users toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/manhpp/malsec-public/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Login & roles](https://github.com/manhpp/malsec-public/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Student workspace](https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/StudentDashboard.jsx): `frontend/src/pages/StudentDashboard.jsx`
- [Instructor tools](https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/InstructorDashboard.jsx): `frontend/src/pages/InstructorDashboard.jsx`
- [Admin portal](https://github.com/manhpp/malsec-public/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`

### LMS API

- [FastAPI application](https://github.com/manhpp/malsec-public/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Access control](https://github.com/manhpp/malsec-public/blob/main/backend/app/security.py): `backend/app/security.py`
- [User management](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/users.py): `backend/app/routers/users.py`
- [Administration](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [PostgreSQL](https://github.com/manhpp/malsec-public/blob/main/backend/app/database.py): `backend/app/database.py`
- [LMS data models](https://github.com/manhpp/malsec-public/blob/main/backend/app/models.py): `backend/app/models.py`

### Learning workflow

- [Classes & gradebook](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/classes.py): `backend/app/routers/classes.py`
- [Lab management](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/labs.py): `backend/app/routers/labs.py`
- [Semester management](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/semesters.py): `backend/app/routers/semesters.py`
- [Submission workflow](https://github.com/manhpp/malsec-public/blob/main/backend/app/routers/submissions.py): `backend/app/routers/submissions.py`
- [File inspection](https://github.com/manhpp/malsec-public/blob/main/backend/app/services/file_service.py): `backend/app/services/file_service.py`
- [Similarity analysis](https://github.com/manhpp/malsec-public/blob/main/backend/app/services/plagiarism.py): `backend/app/services/plagiarism.py`
- [Uploaded files](https://github.com/manhpp/malsec-public/tree/main/backend/app/uploads): `backend/app/uploads`

### VM sandbox

- [VM lifecycle & VDI tokens](https://github.com/manhpp/malsec-public/blob/main/backend/app/services/vm_service.py): `backend/app/services/vm_service.py`
- **Proxmox VE**
- **Apache Guacamole**
- **Isolated lab VMs**

### Observability

- [Monitoring configuration](https://github.com/manhpp/malsec-public/tree/main/monitoring): `monitoring`
- **Prometheus**
- [Grafana dashboards](https://github.com/manhpp/malsec-public/tree/main/monitoring/grafana): `monitoring/grafana`
- [Loki log aggregation](https://github.com/manhpp/malsec-public/tree/main/monitoring/loki): `monitoring/loki`
- [Promtail log shipping](https://github.com/manhpp/malsec-public/tree/main/monitoring/promtail): `monitoring/promtail`

### Other components

- **Students & staff**

## Connections

- Students & staff → React application: use
- React application → Login & roles: route to
- React application → Student workspace: route to
- React application → Instructor tools: route to
- React application → Admin portal: route to
- Login & roles → FastAPI application: request API
- Student workspace → FastAPI application: request API
- Instructor tools → FastAPI application: request API
- Admin portal → FastAPI application: request API
- FastAPI application → Authentication: dispatch
- FastAPI application → User management: dispatch
- FastAPI application → Classes & gradebook: dispatch
- FastAPI application → Lab management: dispatch
- FastAPI application → Semester management: dispatch
- FastAPI application → Submission workflow: dispatch
- FastAPI application → Administration: dispatch
- Authentication → Access control: verify credentials
- Authentication → PostgreSQL: read/write accounts
- User management → PostgreSQL: read/write users
- Classes & gradebook → PostgreSQL: read/write classes
- Classes & gradebook → VM lifecycle & VDI tokens: manage class VMs
- Lab management → PostgreSQL: read/write labs
- Semester management → PostgreSQL: read/write terms
- Submission workflow → PostgreSQL: read/write submissions
- Submission workflow → File inspection: inspect uploads
- Submission workflow → Similarity analysis: analyze similarity
- File inspection → Uploaded files: save inspected files
- Administration → PostgreSQL: manage records
- FastAPI application → PostgreSQL: initialize data
- PostgreSQL → LMS data models: map records
- Student workspace → FastAPI application: request VM session
- VM lifecycle & VDI tokens → Proxmox VE: provision & reset
- VM lifecycle & VDI tokens → Apache Guacamole: build session token
- Proxmox VE → Isolated lab VMs: run isolated VMs
- Apache Guacamole → Isolated lab VMs: connect sessions
- Monitoring configuration → Prometheus: configure metrics
- Monitoring configuration → Grafana dashboards: configure dashboards
- Monitoring configuration → Loki log aggregation: configure logs
- Monitoring configuration → Promtail log shipping: configure shipping
- Promtail log shipping → Loki log aggregation: ship logs
- Prometheus → Grafana dashboards: provide metrics