schema.graphql

schema {
    query: Query
    mutation: Mutation
}

type Query {
    session(id: ID!): Session
}

type Mutation {
    finishSessionByUser(input: FinishSessionByUserInput!): Session
    @aws_cognito_user_pools(cognito_groups: ["user_group"])

    finishSessionByTutor(input: FinishSessionByTutorInput!): Session
    @aws_cognito_user_pools(cognito_groups: ["tutor_group"])

    # "rate session by user"
    # includes reporting the tutor
    rateSession(input: RateSessionInput!): Session
    @aws_cognito_user_pools(cognito_groups: ["user_group"])

    # "report session by tutor"
    # in fact, it's more about reporting the user, not the session
    reportSession(input: ReportSessionInput!): Session
    @aws_cognito_user_pools(cognito_groups: ["tutor_group"])

    # the tutor disconnection process is handled with the internal API + broadcastSessionUpdate
}

type Session {
    id: ID!
    # ...
    state: SessionState!
    stateLog: [SessionStateEntry!]

    # the first option is to leave closure reason as a simple value:
    closureReason: SessionClosureReason @aws_cognito_user_pools(cognito_groups: ["tutor_qa_group", "tutor_group_admin", "supervisor_group", "admin_group"])
    # second is changing it to a complex, more descriptive type:
    closureReason: SessionClosureReasonDescriptor @aws_cognito_user_pools(cognito_groups: ["tutor_qa_group", "tutor_group_admin", "supervisor_group", "admin_group"])
    # third is to promote "closedBy" from the type above to the session itself:
    closedBy: Actor

    # closure case should be used for client integration
    # is doesn't have to be persisted and can be inferred based on other persisted session fields
    # this is a single value field, so a priority needs to be specified in case of multiple possible values (i.e. disconnected and later reported by tutor)
    closureCase: SessionClosureCase @aws_cognito_user_pools(cognito_groups: ["user_group"])

    # should rating or report be accessible by tutor or user?
    userRating: UserRating @aws_cognito_user_pools(cognito_groups: ["tutor_qa_group", "tutor_group_admin", "supervisor_group", "admin_group"])
    tutorReport: TutorReport @aws_cognito_user_pools(cognito_groups: ["tutor_qa_group", "tutor_group_admin", "supervisor_group", "admin_group"])
}

enum SessionState {
    CREATED
    STARTED
    CLOSED
    REJECTED
}

enum SessionClosureReason {
    ANSWERED
    NOT_ANSWERED
    TUTOR_DISCONNECTED
    LANGUAGE_NOT_SUPPORTED
}

type SessionClosureReasonDescriptor {
    closedBy: Actor!
    closureReason: SessionClosureReason!
}

# name is to be decided (case, scenario, etc.)
enum SessionClosureCase {
    NORMAL
    CONNECTION_ISSUES
    TUTOR_REPORTED_USER
}

enum UserClosureReason {
    FINISHED
    # possibly, more values in the future
}

input FinishSessionByUserInput {
    id: ID!
    closureReason: UserClosureReason!
}

enum TutorClosureReason {
    ANSWERED
    NOT_ANSWERED
    LANGUAGE_NOT_SUPPORTED
}

input FinishSessionByTutorInput {
    id: ID!
    closureReason: TutorClosureReason!
}

type SessionStateEntry @aws_cognito_user_pools {
    state: SessionState
    createdAt: AWSDateTime
    createdBy: Actor
}

type UserRating @aws_iam @aws_cognito_user_pools {
    session: Session!
    score: UserRatingScore!
    tags: [UserRatingTag!]!
    comment: String
    user: Actor!
    createdAt: AWSDateTime!
}

type TutorReport @aws_iam @aws_cognito_user_pools {
    session: Session!
    tags: [TutorReportTag!]!
    comment: String
    tutor: Actor!
    createdAt: AWSDateTime!
}

@pmbanka 🔝

There is no way for the tutor different than the one assigned to the session to close it. The same goes for the user. Therefore I don't see a point in much sense introducing the complex closure types.

I thought about it, then I remembered the looming threat of session redirection feature 😅 The design as proposed by me would allow us to add data to the closure types without breaking the client. If we went for a simpler option:

enum SystemClosureReason {
    TUTOR_DISCONNECTED
    # possibly, more values in the future
}


union SessionClosureReason = TutorClosureReason | UserClosureReason | SystemClosureReason

type Session {
	    closureReason: SessionClosureReason @aws_cognito_user_pools(cognito_groups: ["tutor_qa_group", "tutor_group_admin", "supervisor_group", "admin_group"])
}

we lose that future-proofness but API is much simpler. YAGNI or not? I don't really know.

Yes, we do 🙂 There is a plan to display the state log in the UI for supervisors and QAs.

I would not make it a part of this refinement, it will require a refinement on its own. There is a difference between "we do" and "There is a plan" :D

@mmierzwa 🆙

Yes, we do 🙂 There is a plan to display the state log in the UI for supervisors and QAs.

I would not make it a part of this refinement, it will require a refinement on its own. There is a difference between "we do" and "There is a plan" :D

There is a thin line between being well prepared and being overprepared 🙈 But that's ok for me right now.