Overhaul Component docs for v4 (#140)

* just getting started

* progress

* much more progress. ready for rough review

* fix up some things

* start working on components directory changes. draft managing.md

* beep boop writing is fun

* Update docs/developers/components/managing.md

Co-authored-by: Chris Barber <[email protected]>

* first draft finally complete

* fix yaml spacing

* update acl-connect link

* update summary

* many edits

* switch to built-in

* switch to carets instead of curly braces

* s/process/terminal

* Apply suggestions from code review

Co-authored-by: Chris Barber <[email protected]>

* add rolling restart line

---------

Co-authored-by: Chris Barber <[email protected]>

Author: 2 people

docs/SUMMARY.md

@@ -14,12 +14,9 @@
   * [Web Applications](developers/applications/web-applications.md)
   * [Example Projects](developers/applications/example-projects.md)
 * [Components](developers/components/README.md)
-  * [Installing](developers/components/installing.md)
-  * [Writing Extensions](developers/components/writing-extensions.md)
-  * [Operations](developers/components/operations.md)
-  * [Google Data Studio](developers/components/google-data-studio.md)
-  * [SDKs](developers/components/sdks.md)
-  * [Drivers](developers/components/drivers.md)
+  * [Managing](developers/components/managing.md)
+  * [Reference](developers/components/reference.md)
+  * [Built-In Components](developers/components/built-in.md)
 * [REST](developers/rest.md)
 * [Operations API](developers/operations-api/README.md)
   * [Quick Start Examples](developers/operations-api/quickstart-examples.md)
@@ -65,6 +62,9 @@
   * [SQL Functions](developers/sql-guide/functions.md)
   * [SQL JSON Search](developers/sql-guide/json-search.md)
   * [SQL Geospatial Functions](developers/sql-guide/sql-geospatial-functions.md)
+* Miscellaneous
+  * [Google Data Studio](developers/miscellaneous/google-data-studio.md)
+  * [SDKs](developers/miscellaneous/sdks.md)
 
 ## Administration
 

docs/developers/components/README.md

@@ -1,34 +1,21 @@
 # Components
 
-HarperDB is a highly extensible database application platform with support for a rich variety of composable modular components and components that can be used and combined to build applications and add functionality to existing applications. HarperDB tools, components, and add-ons can be found in a few places:
+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`).
 
-* [SDK libraries](sdks.md) are available for connecting to HarperDB from different languages.
-* [Drivers](drivers.md) are available for connecting to HarperDB from different products and tools.
-* [HarperDB-Add-Ons repositories](https://github.com/orgs/HarperDB-Add-Ons/repositories) lists various templates and add-ons for HarperDB.
-* [HarperDB repositories](https://github.com/orgs/HarperDB-Add-Ons/repositories) include additional tools for HarperDB.
-* You can also [search github.com for ever-growing list of projects that use, or work with, HarperDB](https://github.com/search?q=harperdb\&type=repositories)
-* [Google Data Studio](google-data-studio.md) is a visualization tool for building charts and tables from HarperDB data.
+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.
 
-## Components
+From management to development, the following pages document everything a developer needs to know about Harper components.
 
-There are four general categories of components for HarperDB. The most common is applications. Applications are simply a component that delivers complete functionality through an external interface that it defines, and is usually composed of other components. See [our guide to building applications for getting started](../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`)
 
-A data source component can implement the Resource API to customize access to a table or provide access to an external data source. External data source components are used to retrieve and access data from other sources.
+## Custom Components
 
-The next two are considered extension components. Server protocol extension components provide and define ways for clients to access data and can be used to extend or create new protocols.
+The following list is all of Harper's officially maintained, custom components. They are all available on npm and GitHub.
 
-Server resource components implement support for different types of files that can be used as resources in applications. HarperDB includes support for using JavaScript modules and GraphQL Schemas as resources, but resource components may add support for different file types like HTML templates (like JSX), CSV data, and more.
-
-## Server components
-
-Server components can be easily be added and configured by simply adding an entry to your harperdb-config.yaml:
-
-```yaml
-my-server-component:
-  package: 'HarperDB-Add-Ons/package-name' # this can be any valid github or npm reference
-  port: 4321
-```
-
-## Writing Extension Components
-
-You can write your own extensions to build new functionality on HarperDB. See the [writing extension components documentation](writing-extensions.md) for more information.
+- [`@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)

docs/developers/components/built-in.md

@@ -0,0 +1,125 @@
+# Built-In Components
+
+Harper provides extended features using built-in components. They do **not** need to be installed with a package manager, and simply must be specified in a config to run. These are used throughout many Harper docs, guides, and examples. Unlike external components which have their own semantic versions, built-in components follow Harper's semantic version.
+
+- [Built-In Components](#built-in-components)
+	- [fastifyRoutes](#fastifyroutes)
+	- [graphql](#graphql)
+	- [graphqlSchema](#graphqlschema)
+	- [jsResource](#jsresource)
+	- [rest](#rest)
+	- [roles](#roles)
+	- [static](#static)
+
+<!-- ## authentication -->
+
+<!-- ## clustering -->
+
+## fastifyRoutes
+
+Specify custom endpoints using [Fastify](https://fastify.dev/).
+
+This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
+
+Complete documentation for this feature is available here: [Define Fastify Routes](https://docs.harperdb.io/docs/developers/applications/define-fastify-routes)
+
+```yaml
+fastifyRoutes:
+  files: './routes/*.js'
+```
+
+## graphql
+
+> GraphQL querying is **experimental**, and only partially implements the GraphQL Over HTTP / GraphQL specifications.
+
+Enables GraphQL querying via a `/graphql` endpoint loosely implementing the GraphQL Over HTTP specification.
+
+Complete documentation for this feature is available here: [GraphQL](https://docs.harperdb.io/docs/technical-details/reference/graphql)
+
+```yaml
+graphql: true
+```
+
+## graphqlSchema
+
+Specify schemas for Harper tables and resources via GraphQL schema syntax.
+
+This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
+
+Complete documentation for this feature is available here: [Defining Schemas](https://docs.harperdb.io/docs/developers/applications/defining-schemas)
+
+```yaml
+graphqlSchema:
+  files: './schemas.graphql'
+```
+
+## jsResource
+
+Specify custom, JavaScript based Harper resources.
+
+Refer to the Application [Custom Functionality with JavaScript](https://docs.harperdb.io/docs/developers/applications#custom-functionality-with-javascript) guide, or [Resource Class](https://docs.harperdb.io/docs/technical-details/reference/resource) reference documentation for more information on custom resources.
+
+This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
+
+```yaml
+jsResource:
+  files: './resource.js'
+```
+
+<!-- ## login -->
+
+<!-- ## mqtt -->
+
+<!-- ## operationsApi -->
+
+<!-- ## replication -->
+
+## rest
+
+Enable automatic REST endpoint generation for exported resources with this component.
+
+Complete documentation for this feature is available here: [REST](https://docs.harperdb.io/docs/developers/rest)
+
+```yaml
+rest: true
+```
+
+This component contains additional options:
+
+To enable `Last-Modified` header support:
+
+```yaml
+rest:
+  lastModified: true
+```
+
+To disable automatic WebSocket support:
+
+```yaml
+rest:
+  webSocket: false
+```
+
+## roles
+
+Specify roles for Harper tables and resources.
+
+This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
+
+Complete documentation for this feature is available here: [Defining Roles](https://docs.harperdb.io/docs/developers/applications/defining-roles)
+
+```yaml
+roles:
+  files: './roles.yaml'
+```
+
+## static
+
+Specify which files to server statically from the Harper HTTP endpoint. Built using the [send](https://www.npmjs.com/package/send) and [serve-static](https://www.npmjs.com/package/serve-static) modules.
+
+This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
+
+```yaml
+static:
+  files: './web/*'
+```