Bring the concepts section up to date
@@ -56,33 +56,47 @@ compute services, storage services, and even more logical domain-specific servic
## Concepts
-The core top-level architectural abstractions in Mu are:
-
-* **Stack**: A static blueprint describing some specific topology of cloud resources.
-* **Service**: An instantiation of a Stack, grouping zero to many services, each with an optional API, together.
-* **Cluster**: A dynamic collection of zero to many Stacks deployed together into a shared hosting environment.
-* **Workspace**: A static collection of zero to many Stacks managed together in a single source repository.
-
-In an analogy with object-oriented systems, a Stack is akin to a class and Service is akin to an object.
-
-Although a Cluster and Workspace both can contain many Stacks (dynamically and statically, respectively), there isn't
-necessarily a one-to-one mapping between them. Of course, management from the Marapongo console is easier if there is.
-
-Many concepts that are "distinct" in other systems, like the notion of Gateways, Controllers, Functions, Triggers, and
-so on, are expressed as Stacks and Services in the Mu system. They are essentially "subclasses" -- or specializations
+The primary concepts in Mu are:
+
+* **Stack**: A stack is a static description of a topology cloud services with optional APIs.
+* **Package**: A package exports stacks for consumption by others.
+* **Service**: An instantiation of a stack, grouping zero to many services, together.
+* **Cluster**: A hosting environment that stacks can be deployed into, reifying them as services.
+* **Workspace**: A static collection of zero to many stacks managed together in a single source repository.
+
+In an analogy with programming languages, a stack is like a *class* and service is like an *object*. In fact, the way
+these appear in the programming model is exactly this way; for example, in Mu's flavor of JavaScript, MuJS:
+
+ export class Registry extends mu.Stack {
+ private table: mu.Table;
+ constructor() {
+ this.table = new mu.Table("names");
+ }
+ public register(name: string): Promise<number> {
+ return this.table.insert({ name: name });
+ }
+ }
+
+This `Registry` stack instantiates a `Table` service, a cloud database table. This actually represents a cloud resource
+provisioned and managed by Mu. It then offers a single RPC API, `register`, that triggers insertion of a new name
+record into that table. Notice how Mu is letting us mix what would have been classically expressed using a combination
+of configuration and real programming languages in one consistent and idiomatic programming model.
+
+Many concepts that are "distinct" in other systems, like the notion of gateways, controllers, functions, triggers, and
+so on, are expressed as stacks and services in the Mu system. They are essentially "subclasses" -- or specializations
-- of this more general concept, unifying the configuration, provisioning, discovery, and overall management of them.
In addition to those core abstractions, there are some supporting ones:
-* **Type**: A schematized type, sometimes Stack-based, that is used for type-checking Mu specifications.
* **Identity**: A unit of authentication and authorization, governing access to protected resources.
-* **Configuration**: A bag of key/value settings used either at build or runtime.
+* **Configuration**: A bag of key/value settings used either at build, runtime, or a combination.
* **Secret**: A special kind of key/value configuration bag that is encrypted and protected by identity.
Because Mu is a tool for interacting with existing clouds -- including targets like AWS, Kubernetes, and Docker Swarm --
one of the toolchain's most important jobs is faithfully mapping these abstractions onto "lower level" infrastructure
abstractions, and vice versa. Much of Mu's ability to deliver on its promise of better productivity, sharing, and reuse
-relies on its ability to robustly and intuitively perform these translations.
+relies on its ability to robustly and intuitively perform these translations. There is an extensible provider model for
+creating new providers, which amounts to implementing create, read, update, and delete (CRUD) methods per resource type.
## Toolchain
