docs: update and restructure docs for LangDev 2023

docs/global/modules/samples/pages/index.adoc

@@ -1,33 +1,35 @@
-= Welcome to the modelix samples!
-:navtitle: Welcome
+= Introduction
+:navtitle: Introduction
 
-IMPORTANT: The examples are currently work in progress and are develop alongside the modelix platform development.
-
-== Introduction
-
-include::samples:partial$short-description.adoc[]
+include::partial$short-description.adoc[]
 
 None of the examples try to reuse editors defined in MPS.
-If your goal is to reuse MPS editors as is then modelix itself ships with a https://lp.jetbrains.com/projector/[Projector] integration to achieve this.
+If your goal is to reuse MPS editors as is, then modelix itself ships with a https://lp.jetbrains.com/projector/[Projector] integration to achieve this.
 
 While all the examples use the same language defined in MPS they are not meant as one complete example but rather as individual parts.
-The purpose of the examples is to give inspiration of what is possible with modelix and make you think and envision your own use-cases.
-
+The purpose of the examples is to give inspiration for what is possible with modelix and make you think about and envision your own use cases.
 
-== Getting Started
 
-include::modelix:ROOT:tutorial/build-component.adoc[leveloffset=+2]
+== Technical prerequisites
 
-=== Entry Points
+To work with the samples, you need the following software installed.:
 
-Once the initial build has completes you can dive in with the following:
+* MPS `2021.2.6`
+* Java 11
+* Docker and https://docs.docker.com/compose/[Docker Compose]
++
+Alternatives like https://podman.io/[Podman] might work, but have not been tested.
 
-a. Read explanations in the xref:samples:explanation/courses-domain.adoc[]
-b. Read the use-cases these samples cover in the xref:samples:explanation/usecases.adoc[]
-c. Understand the repository in the xref:samples:explanation/structure.adoc[]
-d. Inspect and edit the project with the code editor of your choice.
-* The top folder in the repository provides `IntelliJ` configurations,
-* the `mps` folder is a sub-project can be opened using `MPS 2021.2.6`, and
-* the `spa-dashboard-angular` folder is a `WebStorm` project.
-e. Start sample components which realize use case xref:samples:tutorial/startup-usecases.adoc[]
+== Getting started
 
+* Clone https://github.com/modelix/modelix.samples[samples repository]
+* Start building all components with `./gradlew build` inside the repository
++
+NOTE: Building everything in the beginning is not strictly necessary, but it enables you to let the build run, while you explore the documentation further.
++
+* Explore the documentation
+** Start with the xref:overview.adoc[overview]
+** Or go directly to one of the samples
+*** xref:use_case_1.adoc[]
+*** xref:use_case_2.adoc[]
+*** xref:use_case_3.adoc[]

docs/global/modules/samples/pages/metamodel.adoc

@@ -0,0 +1,134 @@
+= Metamodel for the samples
+:navtitle: Metamodel
+
+The MPS language (aka. metamodel) used in all examples is the same.
+It is fairly small as describes a simplified lecture schedule.
+
+NOTE: The language intentionally does not use expressions.
+Creating editors for expressions manually is tedious,
+and modelix has no support yet for generating these editors for you.
+// TODO https://issues.modelix.org/issue/MODELIX-609
+
+The main concepts of the language are:
+
+- `RoomList`
++
+Root node that contains rooms.
++
+- `Room`
+- `LectureList`
++
+Root node that contains lectures.
++
+- `Lecture`
++
+Lectures are held in rooms.
+- `Schedule`
++
+A lecture is scheduled.
++
+** `OnetimeSchedule`
++
+A lecture can be scheduled once.
+** `WeeklyRecurringSchedule`
++
+Or a lecture can be scheduled weekly until an end date
++
+
+NOTE: You will find more concepts in the language like `SemesterPlan`,
+`Tutor` and `Equipment` they are not used in the samples as of now.
+
+image::metamodel.svg[Static,1920]
+
+
+// classDiagram
+//      class INamedConcept {
+//         <<Interface>>
+//         name: string
+//    }
+//
+//     class RoomList {
+//         <<root>>
+//         rooms: Room[0..n]
+//     }
+//
+//     class LectureList {
+//         <<root>>
+//         lectures: Lecture[0..n]
+//     }
+//
+//     class TutorList {
+//         <<root>>
+//         tutors: Tutor[0..n]
+//     }
+//
+//     class Room {
+//         roomNumber: string
+//         maximumCapacity: integer
+//         equipment: Equipment[0..n]
+//     }
+//
+//     class Lecture {
+//         isInRoom: Room[0..1]
+//         description: string
+//         maximumCapacity: integer
+//         schedule: Schedule
+//         requiredEquipment: Equipment[0..n]
+//     }
+//
+//     class Person {
+//         dateOfBirth: Date
+//     }
+//
+//     class Tutor {
+//         offersLecture: LectureReference[1..n]
+//     }
+//
+//     class LectureReference {
+//         lecture: Lecture
+//     }
+//
+//     class Schedule {
+//         time: Time
+//     }
+//
+//     class OnetimeSchedule {
+//         date: Date
+//     }
+//
+//     class WeeklyRecurringSchedule {
+//         startDate: Date
+//         endDate: Date
+//     }
+//
+//     class Time {
+//         time: string
+//     }
+//
+//     class Date {
+//         date: string
+//     }
+//
+//     class Equipment {
+//         <<enum>>
+//     }
+//
+//     Person <|-- Tutor
+//     Person <-- Date
+//     RoomList *-- Room
+//     LectureList *-- Lecture
+//     Tutor *-- LectureReference
+//     LectureReference <-- Lecture
+//     TutorList *-- Tutor
+//     Lecture <-- Room
+//     INamedConcept <|-- Room
+//     INamedConcept <|-- Lecture
+//     INamedConcept <|-- Tutor
+//     Lecture <-- Schedule
+//     Schedule <|-- OnetimeSchedule
+//     Schedule <|-- WeeklyRecurringSchedule
+//     Schedule <-- Time
+//     OnetimeSchedule <-- Date
+//     WeeklyRecurringSchedule <-- Date
+//     Room <-- Equipment
+//     Lecture <-- Equipment

docs/global/modules/samples/pages/overview.adoc

@@ -0,0 +1,78 @@
+= Overview of the samples
+:navtitle: Overview
+// Temporary redirect to no break links in modelix.docs documentation.
+:page-aliases: reference/architecture.adoc
+
+The samples are structured into use cases.
+Each use case uses different components from the modelix platform
+to create custom solutions.
+
+On this page, you can get an overview of all use cases,
+and see how they are related and what their essential differences are.
+
+image::system-diagram-full.svg[]
+
+[#use_case_1]
+== Use case 1
+
+In the first use case, an MPS project is synchronized to a repository on a xref:core:reference/component-model-server.adoc[model server]
+by utilizing the https://artifacts.itemis.cloud/service/rest/repository/browse/maven-mps/org/modelix/mps/model-server-sync-plugin/[model-server-sync-plugin].
+
+It shows how to make model data, previously accessible only in a running MPS or via files, available through a server.
+
+In itself, this use case has little value, but the next use cases build in part on it.
+
+[#use_case_2]
+== Use case 2
+
+In this use case, we connect web frontends to a xref:core:reference/component-model-server.adoc[model server].
+The web frontends read from and write model data to the model server.
+
+One web frontend can be used to edit model data and is implemented with https://vuejs.org/[Vue.js].
+The other one serves as an overview and is implemented with https://angular.io/[Angular].
+
+You can see
+how changes made in one connected application are instantly reflected in another connected application.
+You can also connect an MPS to the model server
+and see how changes made in the application are synced to MPS and vice versa.
+
+The frontend applications directly use the https://artifacts.itemis.cloud/service/rest/repository/browse/npm-open/%40modelix/model-client/[model-client] JavaScript library
+that connects to the model server.
+They also use a TypeScript API
+generated by the xref:core:reference/component-model-api-gen-gradle.adoc[Model API generator] from the xref:metamodel.adoc[metamodel]
+to enable type-safe access to data structures provided by the model client.
+
+[#use_case_3]
+=== Use case 3
+
+In this use case, a web frontend connects to a web backend,
+which in turn communicates with a xref:core:reference/component-model-server.adoc[model server].
+
+Like in xref:use_case_2[use case 2] model data is synced automatically between the model server, the application and MPS.
+
+A backend is needed if you need to control what data a client might read and write.
+It is also useful to translate data from modelix data structures into a data structure that is suitable for your web applications.
+
+The web backend is implemented with https://quarkus.io/[Quarkus].
+It uses the https://artifacts.itemis.cloud/service/rest/repository/browse/maven-mps/org/modelix/model-client/[model-client]
+to connect to a model server.
+It also uses a Kotlin API
+generated by the xref:core:reference/component-model-api-gen-gradle.adoc[Model API generator] from the xref:metamodel.adoc[metamodel]
+to enable type-safe access to data structures provided by the model client.
+
+For the web frontend, the web backend provides a custom HTTP-
+and websocket-based API.
+
+// === Use case 4
+//
+// WARNING: asdf
+//
+// The web backend in this variant is implemented with https://ktor.io[Ktor].
+// It uses the xref:core:reference/component-light-model-client.adoc[light-model-client] to connect to a running MPS
+// that exposes its data through the xref:core:reference/component-mps-model-server-plugin.adoc[model-server-plugin].
+//
+
+
+
+
+