From 590a5070e90f98a7ecf1c457d362bc5552c382d8 Mon Sep 17 00:00:00 2001 From: pb Date: Fri, 29 Mar 2024 17:55:38 +0100 Subject: [PATCH] improved UML documentation --- README.md | 35 +- .../plantuml/diagram_object_controllers.puml | 77 ++++ docs/UML/plantuml/diagram_object_models.puml | 347 ++++++++++++++++++ 3 files changed, 458 insertions(+), 1 deletion(-) create mode 100644 docs/UML/plantuml/diagram_object_controllers.puml create mode 100644 docs/UML/plantuml/diagram_object_models.puml diff --git a/README.md b/README.md index b626da2..b4771ab 100644 --- a/README.md +++ b/README.md @@ -63,4 +63,37 @@ This script should be updated to be ran from anywhere. # More documentation -[Visit the docs/ directory](/docs/) \ No newline at end of file +[Visit the docs/ directory](/docs/) + +## UML + +We are currently using [goplantuml](https://github.com/jfeliu007/goplantuml/) to generate the oject diagrams directly from the go files. This tools creates `.plums` files directly from the directory where the go files are located. These UML files can then be visualized using plantuml and the VS Code extensions plantuml. + +**Setting up the plantuml environment** : + +``` +# Downloading the go tool goplantuml +go get github.com/jfeliu007/goplantuml/parser +go install github.com/jfeliu007/goplantuml/cmd/goplantuml@latest + +# Install the plantuml environment +sudo apt install default-jre +sudo apt install plantuml + +``` +**Rich PlantUML extension Link**: https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml or search it in the marketplace panel of VS Code + +**Generate and view an UML diagram** + +``` +goplantuml path/to/code/directory > path/to/dest/file.puml +``` + +- open the .puml file generated +- alt + d to have the extension preview the plantUML code +- right click inside the .puml and select 'Export Current Diagram' to create an image file +- the output will be generated in a `out/` directory in the current path + +### Note + +Only `.puml` files ought to be commited to the git repository, because their nature allows to track changes, while image file do not fit the purpose of versioning. \ No newline at end of file diff --git a/docs/UML/plantuml/diagram_object_controllers.puml b/docs/UML/plantuml/diagram_object_controllers.puml new file mode 100644 index 0000000..1355311 --- /dev/null +++ b/docs/UML/plantuml/diagram_object_controllers.puml @@ -0,0 +1,77 @@ +@startuml +namespace controllers { + class ComputingController << (S,Aquamarine) >> { + + GetOneComputing(ID string) + + PostComputing(body models.ComputingNEWModel) + + GetMultipleComputing(IDs []string) + + } + class DataController << (S,Aquamarine) >> { + + GetOneData(ID string) + + GetMultipleData(IDs []string) + + PostData(body models.DataNEWModel) + + } + class DatacenterController << (S,Aquamarine) >> { + + GetMultipleDatacenter(IDs []string) + + GetOneDatacenter(ID string) + + PostDatacenter(body models.DatacenterNEWModel) + + } + class ScheduleController << (S,Aquamarine) >> { + + CreateSchedule(dcName string, workflowName string, cron string, duration uint, startDate time.Time, stopDate time.Time, requirements models.ExecutionRequirementsModel) + + CheckSchedule(cron string, duration uint, startDate time.Time, stopDate time.Time, requirements models.ExecutionRequirementsModel) + + GetSchedules(startDate time.Time, stopDate time.Time) + + GetNextSchedules(baseDate time.Time) + + GetPreviousSchedules(baseDate time.Time) + + } + class SearchController << (S,Aquamarine) >> { + + FindByWord(word string) + + } + class StorageController << (S,Aquamarine) >> { + + GetOneStorage(ID string) + + GetMultipleStorage(IDs []string) + + PostStorage(body models.StorageNEWModel) + + } + class UserController << (S,Aquamarine) >> { + + Login() + + Logout() + + } + class WorkflowController << (S,Aquamarine) >> { + + CreateWorkflow(workflowName string) + + ListWorkflows() + + GetWorkflow(workflowName string) + + AddElementWorkflow(workflowName string, rID string) + + MxGraphParser(workflowName string, xmlData string) + + MxGraphParserConsume(workflowName string) + + LinkElementsWorkflow(workflowName string, rObjIDsource string, rObjIDtarger string, isInput bool) + + GetWorkflowSchedule(workflowName string) + + SetWorkflowSchedule(workflowName string, cronString string, events string, isService bool, startDate time.Time, stopDate time.Time, duration uint) + + CheckWorkflowSchedule(workflowName string) + + BookWorkflowSchedule(workflowName string) + + } + class WorkspaceController << (S,Aquamarine) >> { + + AddModel(id string, rtype string) + + ListWorkspace() + + ListWorkspaceModel() + + DeleteElement(id string, rtype string) + + } +} +"web.Controller" *-- "controllers.ComputingController" +"web.Controller" *-- "controllers.DataController" +"web.Controller" *-- "controllers.DatacenterController" +"web.Controller" *-- "controllers.ScheduleController" +"web.Controller" *-- "controllers.SearchController" +"web.Controller" *-- "controllers.StorageController" +"web.Controller" *-- "controllers.UserController" +"web.Controller" *-- "controllers.WorkflowController" +"web.Controller" *-- "controllers.WorkspaceController" + + +@enduml diff --git a/docs/UML/plantuml/diagram_object_models.puml b/docs/UML/plantuml/diagram_object_models.puml new file mode 100644 index 0000000..983ac5b --- /dev/null +++ b/docs/UML/plantuml/diagram_object_models.puml @@ -0,0 +1,347 @@ +@startuml +namespace models { + class ComputingModel << (S,Aquamarine) >> { + + ID string + + - getRtype() rtype.Rtype + - getName() string + + + AddUserInput(inputs map[string]interface{}) + + } + class ComputingNEWModel << (S,Aquamarine) >> { + + Name string + + Description string + + ShortDescription string + + Logo string + + Type string + + Owner string + + License string + + Price uint + + ExecutionRequirements ExecutionRequirementsModel + + Dinputs []string + + Doutputs []string + + Image string + + Command string + + Arguments []string + + Environment []string + + Ports []string + + } + class ComputingObject << (S,Aquamarine) >> { + + ReferenceID primitive.ObjectID + + Inputs []string + + Outputs []string + + DataCenterID string + + - getHost() *string + - setReference(rID primitive.ObjectID) + - getReference() primitive.ObjectID + - getRtype() rtype.Rtype + - getModel() (ResourceModel, error) + - getName() *string + - isLinked(rObjID string) LinkingState + - addLink(direction LinkingState, rID string) + + } + class DCstatus << (S,Aquamarine) >> { + + DCname string + + DCobjID string + + IsReachable bool + + IsAvailable bool + + Booked *ScheduleInfo + + ErrorMessage string + + } + class DataIO << (S,Aquamarine) >> { + + Counter uint + + } + class DataModel << (S,Aquamarine) >> { + + ID string + + - getRtype() rtype.Rtype + - getName() string + + } + class DataNEWModel << (S,Aquamarine) >> { + + Name string + + Description string + + ShortDescription string + + Logo string + + Dtype string + + Type string + + Example string + + Protocol []string + + Location string + + } + class DataObject << (S,Aquamarine) >> { + + ReferenceID primitive.ObjectID + + - getHost() *string + - getModel() (ResourceModel, error) + - setReference(rID primitive.ObjectID) + - getReference() primitive.ObjectID + - getRtype() rtype.Rtype + - getName() *string + - isLinked(rID string) LinkingState + - addLink(direction LinkingState, rObjID string) + + } + class DatacenterCpuModel << (S,Aquamarine) >> { + + Cores uint + + Architecture string + + Shared bool + + MinimumMemory uint + + Platform string + + } + class DatacenterGpuModel << (S,Aquamarine) >> { + + CudaCores uint + + Model string + + Memory uint + + TensorCores uint + + } + class DatacenterMemoryModel << (S,Aquamarine) >> { + + Size uint + + Ecc bool + + } + class DatacenterModel << (S,Aquamarine) >> { + + ID string + + - getRtype() rtype.Rtype + - getName() string + + + GetTotalCPUs() uint + + GetTotalGPUs() uint + + GetTotalRAM() uint + + } + class DatacenterNEWModel << (S,Aquamarine) >> { + + Name string + + Type string + + Acronym string + + Hosts []string + + Description string + + ShortDescription string + + Logo string + + CPU DatacenterCpuModel + + RAM DatacenterMemoryModel + + GPU []DatacenterGpuModel + + Owner string + + BookingPrice int + + } + class DatacenterObject << (S,Aquamarine) >> { + + ReferenceID primitive.ObjectID + + - setReference(rID primitive.ObjectID) + - getModel() (ResourceModel, error) + - getReference() primitive.ObjectID + - getHost() *string + - getRtype() rtype.Rtype + - getName() *string + - isLinked(rID string) LinkingState + - addLink(direction LinkingState, rObjID string) + + } + class ExecutionRequirementsModel << (S,Aquamarine) >> { + + CPUs uint + + GPUs uint + + RAM uint + + Parallel bool + + ScalingModel uint + + DiskIO string + + } + class MxCell << (S,Aquamarine) >> { + + XMLName xml.Name + + ID string + + Parent *string + + RID *string + + Source *string + + Target *string + + } + class MxGraphModel << (S,Aquamarine) >> { + + XMLName xml.Name + + Root struct{xml.Name, []MxCell, *[]Object} + + } + class Object << (S,Aquamarine) >> { + + XMLName xml.Name + + ID string + + Command *string + + Args *string + + Env *string + + MxCell MxCell + + } + class RepositoryModel << (S,Aquamarine) >> { + + Credentials string + + Url string + + } + interface ResourceModel { + - getRtype() rtype.Rtype + - getName() string + + } + interface ResourceObject { + - getHost() *string + - getName() *string + - getModel() (ResourceModel, error) + - getRtype() rtype.Rtype + - setReference(rObjID primitive.ObjectID) + - getReference() primitive.ObjectID + - isLinked(rObjID string) LinkingState + - addLink(direction LinkingState, rObjID string) + + } + class ScheduleDB << (S,Aquamarine) >> { + + StartDate time.Time + + StopDate time.Time + + Workflow string + + ResourceQty ExecutionRequirementsModel + + } + class ScheduleInfo << (S,Aquamarine) >> { + + Total int + + NextExecutions []string + + } + class SearchResult << (S,Aquamarine) >> { + + Computing []ComputingModel + + Datacenter []DatacenterModel + + Storage []StorageModel + + Data []DataModel + + } + class StorageModel << (S,Aquamarine) >> { + + ID string + + - getRtype() rtype.Rtype + - getName() string + + + AddUserInput(inputs map[string]interface{}) + + } + class StorageNEWModel << (S,Aquamarine) >> { + + Name string + + Description string + + ShortDescription string + + Logo string + + Type string + + DCacronym string + + URL string + + Size uint + + Encryption bool + + Redundancy string + + Throughput string + + BookingPrice uint + + } + class StorageObject << (S,Aquamarine) >> { + + ReferenceID primitive.ObjectID + + Inputs []string + + Outputs []string + + - getHost() *string + - getModel() (ResourceModel, error) + - setReference(rID primitive.ObjectID) + - getReference() primitive.ObjectID + - getRtype() rtype.Rtype + - getName() *string + - isLinked(rObjID string) LinkingState + - addLink(direction LinkingState, rObjID string) + + } + class UserModel << (S,Aquamarine) >> { + + ID string + + Username string + + Password string + + Email string + + } + class Workflow << (S,Aquamarine) >> { + + Data map[string]DataObject + + Computing map[string]ComputingObject + + Storage map[string]StorageObject + + Datacenter map[string]DatacenterObject + + Schedules WorkflowSchedule + + MxgraphXML string + + + GetExecutionRequirements(dcIDobj string) (ExecutionRequirementsModel, error) + + GetResource(rObjID *string) ResourceObject + + GetResourceMapByRtype(rt rtype.Rtype) interface{} + + CreateResourceObject(rt rtype.Rtype) ResourceObject + + AddObj(robj ResourceObject) *primitive.ObjectID + + UpdateDB(userID string, workflowName string) error + + UpdateObj(robj ResourceObject, objID string) + + } + class WorkflowSchedule << (S,Aquamarine) >> { + + IsService bool + + StartDate time.Time + + StopDate time.Time + + Cron string + + Duration uint + + Events string + + IsBooked bool + + } + class Workspace << (S,Aquamarine) >> { + + UserID string + + Workflows map[string]Workflow + + Data []string + + Computing []string + + Datacenter []string + + Storage []string + + - getRtype(rID string) rtype.Rtype + - updateDB() error + + + ConsumeMxGraphModel(xmlmodel MxGraphModel) (*Workflow, error, []error) + + GetResources() map[rtype.Rtype][]string + + GetWorkflow(workflowName string) *Workflow + + GetWorkflows() []string + + NewResource(rID string, rType string) error + + GetAllWorkspacesProjects() chan *Workflow + + } + class WorkspaceModel << (S,Aquamarine) >> { + + UserID string + + Data []DataModel + + Computing []ComputingModel + + Datacenter []DatacenterModel + + Storage []StorageModel + + } + class models.LinkingState << (T, #FF7700) >> { + } + class mxissue << (S,Aquamarine) >> { + - msg string + + + Error() string + + } +} +"models.ComputingNEWModel" *-- "models.ComputingModel" +"models.DataNEWModel" *-- "models.DataModel" +"models.DatacenterNEWModel" *-- "models.DatacenterModel" +"models.StorageNEWModel" *-- "models.StorageModel" + +"models.ResourceModel" <|-- "models.ComputingModel" +"models.ResourceObject" <|-- "models.ComputingObject" +"models.ResourceModel" <|-- "models.DataModel" +"models.ResourceObject" <|-- "models.DataObject" +"models.ResourceModel" <|-- "models.DatacenterModel" +"models.ResourceObject" <|-- "models.DatacenterObject" +"models.ResourceModel" <|-- "models.StorageModel" +"models.ResourceObject" <|-- "models.StorageObject" + +"__builtin__.uint" #.. "models.LinkingState" +@enduml