|
1 | 1 | # Applications |
2 | 2 |
|
3 | | -## Overview of HarperDB Applications |
4 | | - |
5 | 3 | Harper is more than a database, it's a distributed clustering platform allowing you to package your schema, endpoints and application logic and deploy them to an entire fleet of Harper instances optimized for on-the-edge scalable data delivery. |
6 | 4 |
|
7 | | -In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper component, a fundamental building-block of the Harper ecosystem. |
| 5 | +In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper application, a fundamental building-block of the Harper ecosystem. |
8 | 6 |
|
9 | 7 | When working through this guide, we recommend you use the [Harper Application Template](https://github.com/HarperDB/application-template) repo as a reference. |
10 | 8 |
|
11 | | -## Understanding the Component Application Architecture |
| 9 | +Before we get started, let's clarify some terminology that is used throughout the documentation. |
| 10 | + |
| 11 | +**Components** are the high-level concept for modules that extend the Harper core platform adding additional functionality. The application you will build here is a component. In addition to applications, components also encompass extensions. |
| 12 | + |
| 13 | +> We are actively working to disambiguate the terminology. When you see "component", such as in the Operations API or CLI, it generally refers to an application. We will do our best to clarify exactly which classification of a component whenever possible. |
| 14 | +
|
| 15 | +**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. |
12 | 16 |
|
13 | | -Harper provides several types of components. Any package that is added to Harper is called a "component", and components are generally categorized as either "applications", which deliver a set of endpoints for users, or "extensions", which are building blocks for features like authentication, additional protocols, and connectors that can be used by other components. Components can be added to the `hdb/components` directory and will be loaded by Harper when it starts. Components that are remotely deployed to Harper (through the studio or the operation API) are installed into the `hdb/node_modules` directory. Using `harperdb run .` or `harperdb dev .` allows us to specifically load a certain application in addition to any that have been manually added to `hdb/components` or installed (in `hdb/node_modules`). |
| 17 | +**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. |
| 18 | + |
| 19 | +All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application. |
| 20 | + |
| 21 | +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. |
14 | 22 |
|
15 | 23 | ```mermaid |
16 | | -flowchart LR |
17 | | - Client(Client)-->Endpoints |
18 | | - Client(Client)-->HTTP |
19 | | - Client(Client)-->Extensions |
20 | | - subgraph Harper |
| 24 | +flowchart TD |
| 25 | + subgraph Applications |
21 | 26 | direction TB |
22 | | - Applications(Applications)-- "Schemas" --> Tables[(Tables)] |
23 | | - Applications-->Endpoints[/Custom Endpoints/] |
24 | | - Applications-->Extensions |
25 | | - Endpoints-->Tables |
26 | | - HTTP[/REST/HTTP/]-->Tables |
27 | | - Extensions[/Extensions/]-->Tables |
| 27 | + NextJSApp["Next.js App"] |
| 28 | + ApolloApp["Apollo App"] |
| 29 | + CustomResource["Custom Resource"] |
| 30 | + end |
| 31 | +
|
| 32 | + subgraph Extensions |
| 33 | + direction TB |
| 34 | + subgraph Custom |
| 35 | + NextjsExt["@harperdb/nextjs"] |
| 36 | + ApolloExt["@harperdb/apollo"] |
| 37 | + end |
| 38 | + subgraph Built-In |
| 39 | + GraphqlSchema["graphqlSchema"] |
| 40 | + JsResource["jsResource"] |
| 41 | + Rest["rest"] |
28 | 42 | end |
| 43 | + end |
| 44 | +
|
| 45 | + subgraph Core |
| 46 | + direction TB |
| 47 | + Database["database"] |
| 48 | + FileSystem["file-system"] |
| 49 | + Networking["networking"] |
| 50 | + end |
| 51 | +
|
| 52 | + NextJSApp --> NextjsExt |
| 53 | + ApolloApp --> ApolloExt |
| 54 | + CustomResource --> JsResource & GraphqlSchema & Rest |
| 55 | +
|
| 56 | + NextjsExt --> Networking |
| 57 | + NextjsExt --> FileSystem |
| 58 | + ApolloExt --> GraphqlSchema |
| 59 | + ApolloExt --> Networking |
| 60 | +
|
| 61 | + GraphqlSchema --> Database |
| 62 | + JsResource --> Database |
| 63 | + Rest --> Networking |
| 64 | +
|
29 | 65 | ``` |
30 | 66 |
|
| 67 | +> 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](../../technical-details/reference/components/plugins.md) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. |
| 68 | +
|
| 69 | +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. |
| 70 | + |
| 71 | +> 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. |
| 72 | +
|
| 73 | +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](../../technical-details/reference/components/built-in.md) documentation page, and the list of custom extensions and applications is available below. |
| 74 | + |
| 75 | +This guide is going to walk you through building a basic Harper application using a set of built-in extensions. |
| 76 | + |
| 77 | +Complete reference documentation for all built-ins, extensions, and plugins is available in the Technical Details section of the documentation. |
| 78 | +- [Built-In Extensions](../../technical-details/reference/components/built-in.md) |
| 79 | +- [Extension API Reference](../../technical-details/reference/components/extensions.md) |
| 80 | +- [Plugin API Reference](../../technical-details/reference/components/plugins.md) |
| 81 | + |
| 82 | +### Custom Applications |
| 83 | + |
| 84 | +- [`@harperdb/status-check`](https://github.com/HarperDB/status-check) |
| 85 | +- [`@harperdb/prometheus-exporter`](https://github.com/HarperDB/prometheus-exporter) |
| 86 | +- [`@harperdb/acl-connect`](https://github.com/HarperDB/acl-connect) |
| 87 | + |
| 88 | +### Custom Extensions |
| 89 | + |
| 90 | +- [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) |
| 91 | +- [`@harperdb/apollo`](https://github.com/HarperDB/apollo) |
| 92 | +- [`@harperdb/astro`](https://github.com/HarperDB/astro) |
| 93 | + |
31 | 94 | ## Custom Functionality with JavaScript |
32 | 95 |
|
33 | 96 | [The getting started guide](../../getting-started/first-harper-app.md) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resource.md), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. |
|
0 commit comments