Another update

Database.md

@@ -162,38 +162,39 @@ ReferenceExerciseSolution contains additional data for reference solution than n
 
 ## ReferenceSolutionEvaluation
 
-- _referenceSolution_ -- solution to which this evaluation belongs to
+ReferenceSolutionEvaluation contains additional data for reference solution evalution than normal evaluation created on student solution evaluation.
+
+- _referenceSolution_ -- key to solution which this evaluation belongs to
 - _hwGroup_ -- hardware group which was used during execution on worker
-- _resultsUrl_ -- filserver address from which results of reference evaluation can be internally accessed
+- _resultsUrl_ -- filserver address from where results of reference evaluation can be internally accessed
-- _evaluation_ -- associated general evaluation
+- _evaluation_ -- associated general evaluation key
 
 ## ReportedErrors
 
-All errors which were reported to api from backend are sent to administrator of system and also stored in this table.
+All errors which were reported to api from backend are sent as emails to administrator of system and also stored in this entity.
 
 - _type_ -- textual description of error type
-- _recipients_ -- list of email addresses to which error was sent
+- _recipients_ -- list of comma separated email addresses to which error was sent
 - _subject_ -- subject as it was sent in email
-- _sentAt_ -- datetime when email with error report was sent
+- _sentAt_ -- date and time when email with error report was sent
 - _description_ -- message as it was sent in email
 
 ## Resource
 
-- _id_ -- textual identification of resource
+Resource entity represent different resources used in ReCodEx system. These resources can be used in presenter actions for access restrictions. Resource contain list of permissions in one-to-many relation, but from database perspective this table has only one column with the resource name.
-- _permissions_ -- permissions associated with this resource
 
 ## Role
 
-Roles serves for distinction of what user can do or cannot do. Thus every user has to have assigned some particular role from which decisions about access rights are made.
+Roles serves for distinction of what user can or cannot do. Thus every user has to have assigned some particular role from which decisions about access rights are made.
 
-- _id_ -- role textual identification
+- _id_ -- textual identification of the role
 - _parentRole_ -- reference to parent role
-- _childRoles_ -- array of roles which have this one as parent
+- _childRoles_ -- array of roles which have this one as parent; not actual database column, relation stored as _parentRole_ column
-- _permissions_ -- permissions which are connected to this role
+- _permissions_ -- permissions which are connected to this role; not actual database column, many-to-one relation stored in Permission entity
 
 ## RuntimeEnvironment
 
-Stores information about supported environments which can be used for evaluation on workers.
+Stores information about supported environments which can be used for evaluation on workers. On student submit the correct environment is determined by extensions of uploaded files.
 
 - _name_ -- human readable name of runtime environment
 - _language_ -- language which can be used in this environment
@@ -203,45 +204,50 @@ Stores information about supported environments which can be used for evaluation
 
 ## Solution
 
-- _user_ -- user to whom this solution belongs to
+Solution is general entity which is used for all types of evaluations, including students and reference submissions. This entity can be shared between multiple submissions (for example resubmit by supervisor).
-- _files_ -- exercise solution files which user uploaded and are associated with solution
+
-- _solutionRuntimeConfig_ -- runtime configuration which was used during execution on worker
+- _user_ -- user key to whom this solution belongs to
+- _files_ -- exercise solution files which user uploaded and are associated with solution; not actual database column, one-to-many relation is stored by each file
+- _solutionRuntimeConfig_ -- runtime configuration key which was used during execution on worker
 - _evaluated_ -- true if solution was evaluated and results were processed
 
 
 ## SolutionEvaluation
 
-- _evaluatedAt_ -- datetime of evaluation creation
+SolutionEvaluation entity represents evaluation of student or reference solution. It contains parsed and processed data received from backend.
+
+- _evaluatedAt_ -- date and time of evaluation creation
 - _initFailed_ -- if true then one of the initiation tasks failed thus solution cannot be even compiled
-- _score_ -- overall score of user solution
+- _score_ -- overall score of user solution (percentual correctness from 0 to 1)
 - _points_ -- points which were assigned to user for this solution
-- _bonusPoints_ -- bonus points assigned by some of the supervisors
+- _bonusPoints_ -- bonus points assigned by one of the supervisors
 - _isValid_ -- can be used to ban user solution of exercise due to various reasons
 - _evaluationFailed_ -- true if whole evaluation failed on worker
-- _resultYml_ -- whole YAML file with evaluation results acquired indirectly from worker
+- _resultYml_ -- whole yaml file with evaluation results acquired from backend
-- _testResults_ -- results of all tests associated with user solution
+- _testResults_ -- results of all tests associated with user solution; not actual database table, one-to-many relation is stored by TestResult entities
 
 ## SolutionFile
 
-Parent of this entity is `UploadedFile`, only added field is solution to which this file is associated.
+SolutionFile entity is extension of UploadedFile entity, so they share one database table. Solution file has one additional column of associated solution key.
-
-- _solution_ -- associated solution to which file belongs to
 
 ## SolutionRuntimeConfig
 
+SolutionRuntimeConfig entity connects job configuration to runtime environment. This entity is backed up on every update, old version is set as _createdFrom_ key in the new version. On student submission one runtime config is chosen based on files extensions and corresponding job configuration is used for evaluation in the backend.
+
 - _name_ -- human readable identificator of runtime configuration
 - _runtimeEnvironment_ -- corresponding runtime environment
 - _jobConfigFilePath_ -- path to job configuration which is stored at api server
-- _createdAt_ -- datetime of entity creation
+- _createdAt_ -- date and time of entity creation
-- _createdFrom_ -- parent solution runtime configuration from which this one was created
 
 ## Submission
 
-- _submittedAt_ -- datetime of submission creation
+Submission entity corresponds to student submit of assignment. It stores both information about submission and about subsequent evaluation.
-- _note_ -- user can provide note to his/hers exercise solution
+
+- _submittedAt_ -- date and time of submission creation
+- _note_ -- user can provide note to exercise solution
 - _resultsUrl_ -- URL pointed to fileserver from which results of submission can be internally downloaded
-- _assignment_ -- corresponding assignment to which submission belongs to
+- _assignment_ -- corresponding assignment key to which submission belongs to
-- _user_ -- user to whom submission belongs to
+- _user_ -- key of user to whom submission belongs to
 - _submittedBy_ -- user who submitted solution of exercise, can be supervisor for instance
 - _solution_ -- corresponding solution
 - _asynchronous_ -- exercise solution was submitted asynchronously, this happens when supervisor or superadmin submit solution for particular user
@@ -254,22 +260,22 @@ Logically queue of failed submissions which deserves further attention from admi
 - _type_ -- type of failure, can be for example _broker_reject_ or _evaluation_failure_
 - _description_ -- description of failure which was provided by backend
 - _submission_ -- associated submission which failed
-- _createdAt_ -- datetime of entity creation
+- _createdAt_ -- date and time of entity creation
-- _resolvedAt_ -- datetime when failure was resolved
+- _resolvedAt_ -- date and time when failure was resolved
 - _resolutionNote_ -- user can provide description when failure is resolved
 
 ## TestResult
 
-Represents result of one logical test from job configuration.
+TestResult entity represents result of one logical test from job configuration.
 
 - _testName_ -- name of test which was stated in job configuration
 - _status_ -- overall status of test
 - _solutionEvaluation_ -- evaluation to which test result belongs
 - _score_ -- score which was assigned to test evaluation by judge
 - _memoryExceeded_ -- true if memory limit was exceeded
-- _usedMemoryRatio_ -- float number from 0.0 to 1.0 which represents percentage of user solution memory usage against memory limit from configuration
+- _usedMemoryRatio_ -- float number from 0 to 1 which represents percentage of user solution memory usage against memory limit from configuration
 - _timeExceeded_ -- true if time limit was exceeded
-- _usedTimeRatio_ -- float number from 0.0 to 1.0 which represents percentage of user solution time usage against time limit from configuration
+- _usedTimeRatio_ -- float number from 0 to 1 which represents percentage of user solution time usage against time limit from configuration
 - _exitCode_ -- exit code which whole test returns
 - _message_ -- provided only on non-zero exit code
 - _stats_ -- textual representation of whole information about evaluation of test which arrived from worker
@@ -277,11 +283,11 @@ Represents result of one logical test from job configuration.
 
 ## UploadedFile
 
-Entity which represents one file which was uploaded to api server. This entity uses _Single Table Inheritance_ and its children are `ExerciseFile` and `SolutionFile` entities.
+Entity which represents one file which was uploaded to api server. This entity uses _Single Table Inheritance_ and its children are ExerciseFile and SolutionFile entities.
 
 - _name_ -- original name of file uploaded to api
 - _localFilePath_ -- destination where file is stored on api server
-- _uploadedAt_ -- datetime of file upload
+- _uploadedAt_ -- date and time of file upload
 - _fileSize_ -- size of uploaded file in bytes
 - _user_ -- user which uploaded particular file
 
@@ -295,9 +301,9 @@ Keeps information about all users which are registered in ReCodEx.
 - _degreesAfterName_ -- degrees after name
 - _email_ -- email address which is used for sending email notifications
 - _avatarUrl_ -- url of profile picture
-- _isVerified_ -- user verified his/hers email address (not used at the moment)
+- _isVerified_ -- user verified his email address (not used at the moment)
 - _isAllowed_ -- if this field is set to false user cannot sign in to application
-- _createdAt_ -- datetime of user registration
+- _createdAt_ -- date and time of user registration
 - _instance_ -- instance to which user belongs to
 - _settings_ -- settings which are connected to this user
 - _memberships_ -- array of groups in which is user assigned
@@ -306,10 +312,10 @@ Keeps information about all users which are registered in ReCodEx.
 
 ## UserAction
 
-Stores information about what routes on api user visited and some additional information about it. This datas should be collected only from logged users.
+Stores information about what routes on api user visited and some additional information about it. This data should be collected only from logged users.
 
 - _user_ -- which user performed api request
-- _loggedAt_ -- time when action was performed
+- _loggedAt_ -- date and time when action was performed
 - _action_ -- action which was requested on api
 - _params_ -- GET or POST parameters given by user
 - _code_ -- return code which was sent back by api
@@ -317,9 +323,9 @@ Stores information about what routes on api user visited and some additional inf
 
 ## UserSettings
 
-User settings belong to some particular user and contains settings mostly for web application.
+User settings belong to some user and contains settings mostly for web application.
 
 - _darkTheme_ -- dark mode will be used in text editor in web application
-- _vimMode_ -- turn vim mode on in text editor used by web application
+- _vimMode_ -- turn vim mode keybinding on in text editor used by web application
 - _defaultLanguage_ -- default language which will be used in web application