doc: add student table separation and observation changes

1 files changed, 46 insertions, 17 deletions

diff --git a/doc/graduation.md b/doc/graduation.md
index 5eaaa31..16a9ab9 100644
--- a/doc/graduation.md
+++ b/doc/graduation.md
@@ -1,10 +1,31 @@
 # Graduation
 
-## Table
+## Tables
 
-The graduation table tracks all graduation changes for all students.
-A change can be submitted by any teacher.
-Changes are valid until subsequent change renders them obsolete.
+There exist three different tables to hold all graduation information per student.
+The separation is needed for the different required permissions to access the stored data.
+All tables use the following naming scheme `${StudentId}${Purpose}`.
+
+### Submit Table
+
+The submit table is writable by the student and is used to track observation requests from the student. 
+
+### Public Table
+
+The public table tracks all graduation changes known by the student.
+The included information are sufficent to render a student's profile.
+
+Changes can be submitted by any teacher.
+Each change is valid until a subsequent change renders it obsolete.
+
+Changes include points and level changes.
+
+### Shadow Table
+
+The shadow table tracks **all** graduation changes for a student.
+
+Changes can be submitted by any teacher.
+Each change is valid until a subsequent change renders it obsolete.
 
 ## Graduation Changes
 
@@ -17,24 +38,29 @@ Currently multiple changes have to be retrieved to determine their state.
 This decision allows us to write data once and not modify changes in the future.
 The assumption is that a single person does not acquire that much changes, that this would be a performance issue.
 
-### Dataformat
+### Database format
 
 Note that the database is a Moodle database activity and thus does not allow access using SQL.
 The below scheme uses a SQL like syntax.
 
 ```sql
 TABLE Change(
-	Id: INTEGER,
-	Firstname: STRING,
-	Lastname: STRING,
-	Group: STRING,
-	Change: STRING,
-	Description: TEXT,
+	Date: Date,
+	Coach: String,
 	Json: STRING,
 )
 ```
 
-The author of the change and the time it is created is tracked by Moodle and also available vis the list view of the moodle database activity.
+The author of the change and the creation time are tracked by Moodle.
+
+### Data format
+
+Each stored change is represented as JSON and has the following fields:
+(Fields marked by `-` are considered private and not stored in the public table.)
+
+* `change` - the type of the change
+* `-reason` - the type of the change
+* `context` - arbitrary data used to handle the type of change
 
 ### Changes
 
@@ -43,17 +69,20 @@ Valid changes are:
 * `Grün` - sign for wanted behavior
 * `Orange` - sign for unwanted behavior
 * `Rot` - sign for unacceptable behavior
-* `Gespräch` - pedagogical meeting with the coach
-* `Änderung` - change in the student's privileges
+* `ObservationRequest` - the student requested an observation
+* `ObservationStart` - the student's observation started
+* `ObservationEnd` - the student's observation ended
+* `LevelChange` - the student's level changed
+* `Observation` - an observation of the student
 
-### Green Mark
+#### Green Mark
 
 Green marks are collectables.
 
-### Orange Mark
+#### Orange Mark
 
 Orange marks highlight the need for a pedagogical session and are rendered archived by any subsequent `Gespräch` change.
 
-### Red Mark
+#### Red Mark
 
 Red Marks track unacceptable behavior and are only archived by consequence explicitly doing so with a `Änderung` change.