Officially documented release

models/formatter.go

@@ -2,6 +2,25 @@ package models
 
 import "time"
 
+/*
+All structs/models within this file are used by the gcq-formatter queue.
+Specific definitions as to what each model is used for should be found in the gcq-formatter documentation.
+The following file contains just a brief overview, and any documentation on gorm_models itself should reference that the specifics are also stored in gcq-formatter docs.
+*/
+
+// BaseCall is used to store data on a client's attempt to create a billable record.
+//
+// This struct is part of the three primary components used for creating billable records:
+//   - BaseCall
+//   - InterpreterAttempt
+//   - InterpreterConnection
+//
+// It is eventually merged with the other two to create a 'full' billing record that we can derive a $ amount from.
+//
+// Table Schema:
+//
+//	Primary Key: ClientConversationId
+//	Indexes: ClientConversationId, CallType, ClientId, P1ConnectTime, P1DisconnectTime, BookingRequestNumber
 type BaseCall struct {
 	ClientConversationId string `gorm:"primaryKey;index"`
 	CallType             string `gorm:"index"`
@@ -26,6 +45,21 @@ func (BaseCall) TableName() string {
 	return "gc_base_calls"
 }
 
+// InterpreterAttempt is used to store data on the system's attempt to find an interpreter for a client's base call.
+// An interpreter attempt call involves the system dialling an interpreter, and providing them with the option to 'respond' in which they specify if they are available to take the call or not.
+// ClientConversationId is a reference to the client BaseCall which the system is attempting to connect the interpreter to.
+//
+// This struct is part of the three primary components used for creating billable records:
+//   - BaseCall
+//   - InterpreterAttempt
+//   - InterpreterConnection
+//
+// It is eventually merged with the other two to create a 'full' billing record that we can derive a $ amount from.
+//
+// Table Schema:
+//
+//	Primary Key: InterpreterConversationId
+//	Indexes: InterpreterConversationId, InterpreterId, ClientConversationId
 type InterpreterAttempt struct {
 	InterpreterConversationId string `gorm:"primaryKey;index"`
 	InterpreterResponseTime   time.Time
@@ -44,6 +78,22 @@ func (InterpreterAttempt) TableName() string {
 	return "gc_interpreter_attempts"
 }
 
+// InterpreterConnection is used to store data on an interpreter's connection to a BaseCall.
+// An interpreter connection is not its own call, it's a summation of data related to an interpreter's time spent on a base call.
+// ClientConversationId is a reference to the client BaseCall, which is the call this data is derived from.
+// InterpreterConversationId is a reference to the interpreter's acceptance call, which is a unique identifier for the interpreter's time on the call.
+//
+// This struct is part of the three primary components used for creating billable records:
+//   - BaseCall
+//   - InterpreterAttempt
+//   - InterpreterConnection
+//
+// It is eventually merged with the other two to create a 'full' billing record that we can derive a $ amount from.
+//
+// Table Schema:
+//
+//	Primary Key: InterpreterConversationId
+//	Indexes: InterpreterConversationId, InterpreterId, ClientConversationId
 type InterpreterConnection struct {
 	InterpreterConversationId string `gorm:"primaryKey;index"`
 	InterpreterAccepted       bool
@@ -61,6 +111,14 @@ func (InterpreterConnection) TableName() string {
 	return "gc_interpreter_connections"
 }
 
+// CallStat stored statistics & metrics on a client's attempt to create a billable record by finding an interpreter (BaseCall).
+// The stats collected are important for billing data as the CallStat object indicates whether or not the call was successfully serviced.
+// The stats are also used extensively for reporting purposes, and measure the company's defined SLAs, including UTS (unable to service) duration and the time taken to find & connect to an interpreter..
+//
+// Table Schema:
+//
+//	Primary Key: ClientConversationId
+//	Indexes: ClientConversationId, CallType, ClientId, ConversationStart, ConversationEnd, P1ConnectTime, P1DisconnectTime, BookingRequestNumber
 type CallStat struct {
 	ClientConversationId      string `gorm:"primaryKey;index"`
 	CallType                  string `gorm:"index"`
@@ -92,6 +150,16 @@ func (CallStat) TableName() string {
 	return "gc_call_stats"
 }
 
+// Breakdown is used to store data relating to the call in a segment-by-segment basis.
+// The Breakdown is a translation of the technical data into domain specific language that non-technical members of the company can understand.
+// Not every segment is translated into a breakdown, only key events.
+// The breakdowns are also used extensively in terms of reporting, as they provide a very fine-grain overview of what happened on a given call.
+//
+// Table Schema:
+//
+//	Primary Key: ClientConversationId, Timestamp, Task
+//	Indexes: ClientConversationId, InterpreterConversationId, Timestamp, Task
+//	JSON Fields: Metadata
 type Breakdown struct {
 	ClientConversationId      string    `gorm:"primaryKey;index"`
 	InterpreterConversationId string    `gorm:"index"`
@@ -106,6 +174,15 @@ func (Breakdown) TableName() string {
 	return "gc_call_breakdown"
 }
 
+// CallMetrics store data relating to the call, specifically to do with duration/timing metadata.
+// The CallMetrics give an overview as to how the duration of any given call was spent, in terms of non-technical domain specific language.
+//
+// Table Schema:
+//
+//	Primary Key: ClientConversationId
+//	Indexes: ClientConversationId
+//	JSON Fields: Metadata
+
 type CallMetrics struct {
 	ClientConversationId string `gorm:"primaryKey;index"`
 	//