Add design section for App Server

guidelines/MONAI-App-Server.md

@@ -3,6 +3,28 @@
 ## Description
 This is a proposal for the MONAI Deploy Working Group for the MONAI Deploy Application Server.
 
+- [Overview](#overview)
+- [Goal](#goal)
+- [Standard Language](#standard-language)
+- [Success Criteria](#success-criteria)
+- [Requirements](#requirements)
+  - [Support for Specific MONAI workloads](#support-for-specific-monai-workloads)
+  - [Deployable on MONAI Operating Environments](#deployable-on-monai-operating-environments)
+  - [Register and unregister MONAI applications](#register-and-unregister-monai-applications)
+  - [Maintain associations between input datasets and MONAI applications](#maintain-associations-between-input-datasets-and-monai-applications)
+  - [Run MONAI applications with associated datasets](#run-monai-applications-with-associated-datasets)
+  - [Provision resources for applications](#provision-resources-for-applications)
+  - [Monitor and report MONAI application job progress, completion and failures](#monitor-and-report-monai-application-job-progress--completion-and-failures)
+  - [Notify registered job handler about job completion](#notify-registered-job-handler-about-job-completion)
+  - [Provide results of completed jobs](#provide-results-of-completed-jobs)
+- [Design and Architecture](#design-and-architecture)
+  - [Job Service](#job-service)
+  - [MAP Service](#map-service)
+  - [Payload Service](#payload-service)
+  - [MAP Registration](#map-registration)
+  - [Uploading Job Inputs](#uploading-job-inputs)
+  - [Job Creation](#job-creation)
+
 ## Overview
 As data scientists & app developers build AI models they need a way to deploy these apps in production. MONAI Deploy Application Server will be used to deploy multiple  MONAI applications. This proposal documents the requirements for MONAI Deploy Application Server.
 
@@ -49,60 +71,36 @@ Application Server SHALL provide results of completed jobs.
 
 ## Design and Architecture
 
-### API Spec
-App Server SHALL expose the following APIs
-
-#### Register MAP
-This API SHALL allow users to register a MAP with the App Server.
-
-#### Unregister MAP
-This API SHALL allow users to unregister a MAP with the App Server. When a MAP is unregistered, users SHALL not be able to run a job for that MAP.
-
-#### List MAPs
-This API SHALL allow users to list available MAPs.
-Unregistered MAPs SHALL not appear in the list of MAPs.
+Application Server is composed of three GRPC microservices.
+- Job Service
+- MAP Service
+- Payload Service
 
-#### Describe MAP
-This API SHALL allow users to get all the information pertaining to a MAP.
+### Job Service
+Clients will interact Job Service to create, list, get status for and cleanup jobs.
 
-#### Upload Dataset
-This API SHALL allow users to upload a dataset to the Application Server.
+### MAP Service
+Clients will interact MAP Service to create, list, delete and get status of MAPs.
 
-#### Run a Job for Dataset and MAP combination
-This API SHALL allow users to run a job corresponding to a registered MAP and uploaded dataset.
+### Payload Service
+Clients will interact Payload Service to create, copy, delete, list, upload files to and download files from MAPs.
 
-#### Get Job Status
-This API SHALL allow users to get the status of a job.
+We list the main interactions of the clients with the Appplication Server.
 
-#### Download results for Job
-This API SHALL allow users to download the results of a job.
+### MAP Registration
 
-#### Register Notification Handler
-This API SHALL allow users to register a notification handler. Application Server SHALL post job completion events to registered notification handlers.
+![MAP Registration](./MAP-Registration.png)
 
-#### Unregister Notification Handler
-This API SHALL allow users to unregister a notification handler. Once a notification handler has been unregistered, Application Server SHALL NOT post job completion events to notification handlers.
+When a client makes a request with the App Server to register a MAP, MAP Service invokes the MAP Provider. The MAP Provider requests the MAP Controller to deploy an instance of the MAP. The MAP Controller checks with Resource Provider if there are sufficient resources to launch a MAP Container. If sufficient resources are unavailable, the MAP registration is rejected and an error is returned to the client. If sufficient resources are available, the MAP Controller launches a MAP Container and returns a UUID to the client. The MAP Controller monitors the running container. Once the container finishes execution, the MAP Controller reads the config from the output directory of the MAP and requests the MAP Provider to store the MAP config in the database.
 
-#### Cleaning up results for completed job
-This API SHALL allow users to delete the results of a completed job.
+### Uploading Job Inputs
 
-#### List jobs
-This API SHALL allow users to list all jobs.
+![Uploading Job Inputs](./Upload-Payload.png)
 
-#### Finalize job
-This API SHALL allow users to finalize a job, allowing the Application Server to then cleanup the outputs for the job.
+When a client wants to submit a payload for a running a job with a MAP, the client requests the Server to create a payload. The Server requests the Payload Provider to create a payload and returns a UUID after the payload has created. The client then uses the UUID to upload input files to that payload by sending a file upload request to the Server. The Server invokes the Payload Provider to copy the file contents over to the payload storage allocated for the payload.
 
-### Job Lifecycle in Production
+### Job Creation
 
-- User registers MAP with Server.
-- Server extracts manifest from MAP.
-- PACs uploads data to Router.
-- Router determines which MAP to run with dataset.
-- Router requests Server to run a job with given dataset and chosen MAP.
-- Server provisions resources for job.
-- Server launches job.
-- Server monitors job.
-- Server detects job completion.
-- Server releases resources held by job.
-- Server notifies handler of job completion.
+![Job Creation](./Job-Creation.png)
 
+When a client requests the Server to run a job for a given MAP and payload input, Job Service requests the Job Provider to run a job for the MAP image.  Job Provider retrieves the MAP config from the MAP Provider for the given MAP UUID. Job Provider then requests the Job Controller to launch a job for the MAP selected by the client. Job Controller checks with the Resource Provider if sufficient reosurces are available. If resources are unavailable, job creation is rejected by the Server and an error code is returned back to the client. If sufficient resources are available, Job Controller deploys the job and provides the uploaded inputs to the deployed container. Job Provider then stores a record for the newly launched job and the job UUID is returned back to the client. Job Controller monitors the job, detects changes in job status and requests the Job Provider to set the updated status for the job.