feat(website): improve broker docs

website/src/pages/documentation/broker.md

@@ -16,7 +16,7 @@ npm install @deepkit/broker
 
 ## Broker Classes
 
-Deepkit Broker provides four main broker classes: 
+Deepkit Broker provides these main broker classes: 
 
 - **BrokerCache** - L2 cache abstraction with cache invalidation 
 - **BrokerBus** - Message bus (Pub/Sub)
@@ -26,6 +26,11 @@ Deepkit Broker provides four main broker classes:
 
 These classes are designed to take a broker adapter to communicate with a broker server in a type-safe way.
 
+A default adapter `BrokerDeepkitAdapter` that communicates with Deepkit Broker server is included in the package, but you can write your own adapter to communicate with other broker servers (e.g. Redis).
+
+The FrameworkModule provides and registers the default adapter and connects to Deepkit Broker server, which runs per default in the same process.
+In a production environment, you would run the broker server in a separate process or even on a different machine.
+
 To give a high level overview of how the classes can be used outside the framework, here is an example:
 
 ```typescript
@@ -43,6 +48,7 @@ class MyAdapter implements BrokerAdapterBus {
   }
 }
 
+// or BrokerDeepkitAdapter for the default adapter
 const adapter = new MyAdapter;
 const bus = new BrokerBus(adapter);
 
@@ -59,41 +65,26 @@ await channel.subscribe((message) => {
 await channel.publish({ foo: 'bar' });
 ```
 
-In this example we write our own adapter to communicate with a broker server. The adapter is then passed to the BrokerBus class, which is used to create a channel. The channel can then be used to subscribe to messages and publish messages.
+In this example we write our own adapter to communicate with a broker server. The adapter is then passed to the BrokerBus class, which is used to create a channel.
+This is the common pattern all Broker classes follow: They take an adapter in the constructor and use it to communicate with the broker server.
+
+The channel can then be used to subscribe to messages and publish messages.
 
 Thanks to runtime types and the call `channel<MyMessage>('my-channel-name');` everything is type-safe and the message can be validated and serialized automatically in the adapter directly.
 The default implementation `BrokerDeepkitAdapter` handles this automatically for you (and uses BSON for serialization).
 
 Note that each broker class has its own adapter interface, so you can implement only the methods you need. The `BrokerDeepkitAdapter` implements all of these interfaces and can be used in all broker classes.
 
-To use these classes in a Deepkit application with dependency injection, you can use the `FrameworkModule` which provides a default adapter for the broker server and registers all broker classes as providers. See next chapter Usage for more information.
-
-Here is an example on how to manually set up an application with BrokerBus.
-
-```typescript
-type MyBusChannel = BrokerBusChannel<MyMessage>;
-
-const app = new App({
-  providers: [
-    MyAdapter,
-    provide<BrokerBus>((adapter: MyAdapter) => new BrokerBus(adapter)),
-    provide<MyBusChannel>((bus: BrokerBus) => bus.channel<MyMessage>('my-channel-name')),
-  ]
-});
-
-await app.get<MyBusChannel>().subscribe((message) => {
-  console.log('received message', message);
-});
-
-await app.get<MyBusChannel>().publish({ foo: 'bar' });
+To use these classes in a Deepkit application with dependency injection, you can use the `FrameworkModule` which provides several things:
 
-app.get(MyAdapter).disconnect();
-```
+- a default adapter for the broker server
+- the broker server itself (and starts it automatically)
+- and registers all broker classes as providers
 
 ## Usage
 
-The FrameworkModule provides a default broker adapter for the configured broker server based on the given configuration.
-It also registers providers for all the broker classes, so you can inject them into your services directly.
+The `FrameworkModule` provides a default broker adapter for the configured broker server based on the given configuration.
+It also registers providers for all the broker classes, so you can inject them (e.g. BrokerBus) into your services and provider factories directly.
 
 ```typescript
 // in an extra file, e.g. broker-channels.ts
@@ -115,8 +106,6 @@ const app = new App({
     },
   })],
 });
-
-void app.run();
 ```
 
 You can then inject the broker derived classes (or the broker class directly) into your services:
@@ -147,3 +136,22 @@ If you need more connections or a custom adapter, you can create your own adapte
 export type BrokerAdapter = BrokerAdapterCache & BrokerAdapterBus & BrokerAdapterLock & BrokerAdapterQueue & BrokerAdapterKeyValue;
 ```
 
+## Broker Server
+
+The Broker server starts automatically per default as soon as you import the `FrameworkModule` and run the `server:start` command.
+All Broker classes are configured per default to connect to this server.
+
+In a production environment, you would run the broker server in a separate process or even on a different machine. Instead of doing `server:start` you would start the broker server with `server:broker:start`.
+
+```bash
+ts-node app.ts server:broker:start
+```
+
+This starts the server on the host configured via for example `new FrameworkModule({broker: {listen: 'localhost:8811'}})`.
+You could change the address also via environment variables if you enabled `app.loadConfigFromEnv({prefix: 'APP_', namingStrategy: 'upper'});`:
+
+```bash
+APP_FRAMEWORK_BROKER_LISTEN=localhost:8811 ts-node app.ts server:broker:start
+```
+
+If you start the server manually, make sure to disable automatic broker server start via `startOnBootstrap: false` in your application configuration.