wip

Author: Ethan-Arrowood

docs/SUMMARY.md

@@ -18,6 +18,7 @@
   * [Web Applications](developers/applications/web-applications.md)
   * [Example Projects](developers/applications/example-projects.md)
 * [Components](developers/components/README.md)
+  * [Configuration](developers/components/configuration.md)
   * [Managing](developers/components/managing.md)
   * [Reference](developers/components/reference.md)
   * [Built-In Components](developers/components/built-in.md)

docs/developers/components/README.md

@@ -1,22 +1,76 @@
 # Components
 
-Harper components are a core Harper concept defined as flexible JavaScript based _extensions_ of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../../technical-details/reference/globals.md) (such as `Resource`, `databases`, and `tables`).
+**Components** are the high-level concept for modules that extend the Harper core platform adding additional functionality. The application you built in the previous section is an example of a component. In addition to applications, components also encompass extensions.
 
-A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../applications/README.md) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as `rest` (for automatic REST endpoint generation), `graphqlSchema` (for table schema definitions), and many more.
+**Applications** are best defined as the implementation of a specific user-facing feature or functionality. Applications are built on top of extensions and can be thought of as the end product that users interact with. For example, a Next.js application that serves a web interface or an Apollo GraphQL server that provides a GraphQL API are both applications.
 
-From management to development, the following pages document everything a developer needs to know about Harper components.
+**Extensions** are the building blocks of the Harper component system. Applications depend on extensions to provide the functionality the application is implementing. For example, the built-in `graphqlSchema` extension enables applications to define their databases and tables using GraphQL schemas. Furthermore, the `@harperdb/nextjs` and `@harperdb/apollo` extensions are the building blocks that provide support for building Next.js and Apollo applications.
 
-- [Managing Components](./managing.md) - developing, installing, deploying, and executing Harper components locally and remotely
-- [Technical Reference](./reference.md) - detailed, technical reference for component development
-- [Built-In Components](./built-in.md) - documentation for all of Harper's built-in components (i.e. `rest`)
+All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application.
 
-## Custom Components
+Extensions can also depend on other extensions. For example, the [`@harperdb/apollo`](https://github.com/HarperDB/apollo) extension depends on the built-in `graphqlSchema` extension to create a cache table for Apollo queries. Applications can then use the `@harperdb/apollo` extension to implement an Apollo GraphQL backend server.
 
-The following list is all of Harper's officially maintained, custom components. They are all available on npm and GitHub.
+```mermaid
+flowchart TD
+  subgraph Applications
+    direction TB
+    NextJSApp["Next.js App"]
+    ApolloApp["Apollo App"]
+    CustomResource["Custom Resource"]
+  end
+
+  subgraph Extensions
+    direction TB
+    subgraph Custom
+      NextjsExt["@harperdb/nextjs"]
+      ApolloExt["@harperdb/apollo"]
+    end
+    subgraph Built-In
+      GraphqlSchema["graphqlSchema"]
+      JsResource["jsResource"]
+      Rest["rest"]
+    end
+  end
+
+  subgraph Core
+    direction TB
+    Database["database"]
+    FileSystem["file-system"]
+    Networking["networking"]
+  end
+
+  NextJSApp --> NextjsExt
+  ApolloApp --> ApolloExt
+  CustomResource --> JsResource & GraphqlSchema & Rest
+
+  NextjsExt --> Networking
+  NextjsExt --> FileSystem
+  ApolloExt --> GraphqlSchema
+  ApolloExt --> Networking
+
+  GraphqlSchema --> Database
+  JsResource --> Database
+  Rest --> Networking
+
+```
+
+> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleComponent` method. Plugins are **experimental**, and complete documentation is available on the [Plugin API](./plugins.md) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported.
+
+Beyond applications and extensions, components are further classified as built-in or custom. **Built-in** components are included with Harper by default and can be directly referenced by their name. The `graphqlSchema`, `rest`, and `jsResource` extensions used in the previous application example are all examples of built-in extensions. **Custom** components must use external references, generally npm or GitHub packages, and are often included as dependencies within the `package.json` of the component.
+
+> Harper maintains a number of custom components that are available on `npm` and `GitHub`, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) extension or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application.
+
+
+Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](./built-in.md) documentation page, and the list of custom extensions and applications is available below.
+
+## Custom Applications
 
-- [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs)
-- [`@harperdb/apollo`](https://github.com/HarperDB/apollo)
 - [`@harperdb/status-check`](https://github.com/HarperDB/status-check)
 - [`@harperdb/prometheus-exporter`](https://github.com/HarperDB/prometheus-exporter)
 - [`@harperdb/acl-connect`](https://github.com/HarperDB/acl-connect)
+
+## Custom Extensions
+
+- [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs)
+- [`@harperdb/apollo`](https://github.com/HarperDB/apollo)
 - [`@harperdb/astro`](https://github.com/HarperDB/astro)

docs/developers/components/configuration.md

@@ -0,0 +1,81 @@
+# Component Configuration
+
+Harper components are configured with a `config.yaml` file located in the root of the component module directory. This file is how a component configures other components it depends on. Each entry in the file starts with a component name, and then configuration values are indented below it.
+
+```yaml
+name:
+  option-1: value
+  option-2: value
+```
+
+It is the entry's `name` that is used for component resolution. It can be one of the [built-in extensions](./built-in.md), or it must match a package dependency of the component as specified by `package.json`. The [Custom Component Configuration](#custom-component-configuration) section provides more details and examples.
+
+For some built-in components they can be configured with as little as a top-level boolean; for example, the [rest](./built-in.md#rest) extension can be enabled with just:
+
+```yaml
+rest: true
+```
+
+Most components generally have more configuration options. Some options are ubiquitous to the Harper platform, such as the `files` and `urlPath` options for an [extension](./extensions.md) or [plugin](./plugins.md), or `package` for any [custom component](#custom-component-configuration).
+
+## Custom Component Configuration
+
+Any custom component **must** be configured with the `package` option in order for Harper to load that component. When enabled, the name of package must match a dependency of the component. For example, to use the `@harperdb/nextjs` extension, it must first be included in `package.json`:
+
+```json
+{
+	"dependencies": {
+		"@harperdb/nextjs": "1.0.0"
+	}
+}
+```
+
+Then, within `config.yaml` it can be enabled and configured using:
+
+```yaml
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  # ...
+```
+
+Since npm allows for a [variety of dependency configurations](https://docs.npmjs.com/cli/configuring-npm/package-json#dependencies), this can be used to create custom references. For example, to depend on a specific GitHub branch, first update the `package.json`:
+
+```json
+{
+	"dependencies": {
+		"harper-nextjs-test-feature": "HarperDB/nextjs#test-feature"
+	}
+}
+```
+
+And now in `config.yaml`:
+
+```yaml
+harper-nextjs-test-feature:
+  package: '@harperdb/nextjs'
+  files: './'
+  # ...
+```
+
+## Default Component Configuration
+
+Harper components do not need to specify a `config.yaml`. Harper uses the following default configuration to load components.
+
+```yaml
+rest: true
+graphqlSchema:
+  files: '*.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: '.'
+static:
+  files: 'web/**'
+```
+
+Refer to the [built-in components](./built-in.md) documentation for more information on these fields.
+
+If a `config.yaml` is defined, it will **not** be merged with the default config.