feat: general cleanup of copy. Add Glossary

src/.vitepress/config.mjs

@@ -49,6 +49,10 @@ export default defineConfig({
             text: '🟨 hyper Response Shape',
             link: '/docs/concepts/hyper-shape',
           },
+          {
+            text: '📚 Glossary',
+            link: '/docs/concepts/glossary',
+          },
         ],
       },
       {
@@ -64,17 +68,17 @@ export default defineConfig({
             link: '/docs/build/hyper-nano'
           },
           {
-            text: '⨠ Custom Middleware',
-            link: '/docs/build/custom-middleware',
+            text: '⨠ Middleware',
+            link: '/docs/build/middleware',
           },
           {
-            text: '🪗 Custom Adapter',
+            text: '🪗 Custom Adapters',
             link: '/docs/build/custom-adapter',
           }
         ],
       },
       {
-        text: '🤖 Host',
+        text: '🚢 Host',
         link: '/docs/host/index',
         items: [
           {

src/docs/build/middleware.md

@@ -0,0 +1,72 @@
+# hyper App Middleware
+
+hyper `Middleware` allows you to extend the hyper `App` interface to support opinionated features, without having to modify the `Core` interface.
+
+`Middleware` should be function that receives the `App` instance as a parameter and returns the `App` instance, creating a chain-able collection of middleware. For example, with `express`:
+
+```ts
+type HyperExpressAppMiddleware = (app: Express) => Express;
+```
+
+:::info
+It is up to the hyper `App` implementation to properly apply the `Middleware` to itself.
+
+In other words, the `Middleware` is specific to an `App` implementation
+:::
+
+## Middleware Examples
+
+A common use-case is to enforce authN/Z on the hyper `Server`. Here is an example of a JWT verifying middleware when using an `express`-based `App` (See [here](/docs/api-reference/rest/index)):
+
+```ts
+import jwt from 'npm:express-jwt'
+
+const auth = (app) => {
+  app.use(jwt({
+    secret: process.env.SECRET,
+    algorithms: ['HS256']
+  }).unless({ path: ['/', /^\/data$/] }))
+
+  app.use('/data', jwt({
+    secret: process.env.ADMIN_SECRET,
+    algorithms: ['HS256']
+  })
+
+  app.use((err, req, res, next) => {
+    if (err.name === 'UnauthorizedError') {
+      res.status(401).send({ok: false, msg: 'not authorized'})
+    }
+  })
+
+  return app
+}
+```
+
+Because hyper is modular and in this case using `express`, you could use any `express` framework middleware to manage your authN/Z process. You can add more advanced security checks for each hyper `Service` resource or even for a specific `Domain`.
+
+For example, let's say you only wanted certain clients to be able to create or destroy hyper `Data` Services on your hyper `Server`.
+
+You would modify your `Middleware` to perform special checks based on those endpoints.
+
+**Other common use-cases:**
+
+- Throttling
+- Additional Routes for other services, like email, or maybe _serving_ files in a hyper `Storage` service
+
+## Applying Middleware
+
+Once you've created your middleware, you'll want to apply it to your hyper `Server`
+
+In the [hyper Config file](/docs/host/hyper-config), you may specify an array of `middleware`. This `middleware` is then passed to the hyper `App` as `services.middleware` by hyper `Core`
+
+```js hyper.config.js
+import { auth } from "./auth.js";
+
+export default {
+  app: express,
+  adapters: [
+    /*...*/
+  ],
+  middleware: [auth],
+};
+```

src/docs/concepts/clean-cloud-architecture.md

@@ -28,7 +28,7 @@ It also allows for the separation of concerns. Each tier of the architecture can
 
 > The only time we must touch multiple tiers is if a Port is changed. And that is usually a find and replace
 
-## hyper Clean Architecture Lingua Franca 📚
+## hyper Lingua Franca 📚
 
 ![hyper-architecture](/hyper-architecture.png)
 

src/docs/concepts/glossary.md

@@ -0,0 +1,31 @@
+# Glossary
+
+### hyper Apps 🎮
+
+The Driving Adapters in the hyper Service Framework are called `Apps` or `Apis`. This is the public interface used to interact with the hyper `Server`
+
+### hyper Core 🪨
+
+The business layer in hyper that contains all of the hyper business logic and enforces each `Port`. `Core` also defines the `Port` that a hyper `App` invokes to interact with `Core`.
+
+### hyper Ports 🔌
+
+The service primitive APIs defined in hyper `Core`. There are multiple `Ports` defined in the hyper Service Framework. The current ones are `Data`, `Cache`, `Storage`, `Queue`, and `Search`.
+
+### hyper Adapters 🛠
+
+The Driven Adapters in The hyper Service Framework. Each `Adapter` implements a hyper `Port` and does the heavy lifting of communicating with an underlying technology being used to power the `Port`.
+
+Generally, these are referred using the hyper `Port` names ie. `Data` Adapter, `Cache` Adapter, `Storage` Adapter, `Queue` Adapter, and `Search` Adapter
+
+You can see many of them that the Core team has implemented [here](https://github.com/hyper63?q=hyper-adapter&type=all&language=&sort=)
+
+### hyper Services
+
+The composed components described above:
+
+- A hyper `App`
+- hyper `Core`
+- A hyper `Adapter`
+
+Generally, these are referred using the hyper `Port` names ie. `Data` Service, `Cache` Service, `Storage` Service, `Queue` Service, and `Search` Service

src/docs/host/hyper-config.md

@@ -1,21 +1,22 @@
 # The `hyper` Config File
 
-The config file is the core manifest for hyper, it pulls all of the adapters into the fold and configures, and applies them to the core module.
+The Config file is the core manifest for hyper, it pulls all of the adapters into the fold, configures, and applies them to hyper `Core`.
 
-The config file is where you choose the `App` and set of `Adapters` you would like hyper `Core` to use. The hyper Service Framework uses a config file to bootstrap the hyper `Server` with the provided `App` and `Adapter`.
+The Config file is where you choose the `App` and set of `Adapters` you would like hyper `Core` to use.
 
 A Config file will look like this:
 
 ::: code-group
 
 ```js [hyper.config.js]
-// hyper driving adapter
+// hyper App
 import express from "https://raw.githubusercontent.com/hyper63/hyper/hyper-app-express%40v1.2.1/packages/app-express/mod.ts";
 
-// hyper driven adapters
+// hyper Adapters
 import mongodb from "https://raw.githubusercontent.com/hyper63/hyper-adapter-mongodb/v3.3.0/mod.ts";
 import redis from "https://raw.githubusercontent.com/hyper63/hyper-adapter-redis/v3.1.2/mod.js";
 
+// hyper Middleware
 import { auth } from "./auth.ts";
 
 export default {
@@ -97,6 +98,7 @@ This will download hyper `Core`, load your configuration file, and start up a hy
 You can also start hyper by importing it using `Deno`
 
 ```ts
+// hyper Core
 import hyper from "https://raw.githubusercontent.com/hyper63/hyper/hyper%40v4.3.2/packages/core/mod.ts";
 
 hyper({

src/docs/index.md

@@ -29,12 +29,12 @@ Understand the why and how of the hyper Service Framework.
 
 ## Host
 
-Learn how to host the hyper Service Framework Server.
+Learn how to host a hyper Service Framework `Server`.
 
 [Read More](./host/index)
 
 ## Build
 
-Learn how to build your own hyper Port adapters and apps.
+Learn how to build your own hyper `Port` `Adapters` and `Apps`.
 
 [Read More](./build/index)