About Dashboard

Writing a web application typically includes writing a way to create accounts and manage account data and eventually ways to administrate that data too. Dashboard provides a reusable UI for your users and administration, completely API-driven, that installs alongside your web application so you have two servers, one for your Dashboard and one for your application.

As users browse your Dashboard server they receive content proxied from your application server and content provided by Dashboard and its modules.

Dashboard serves your application within its own template, or your app may occupy the entire page.

Dashboard is written in NodeJS and uses local file system, PostGreSQL, Redis, or Amazon S3-compatible backends for data storage. The project code is divided into three groups:

1. Web UI provides an interface for users and administrators powered by the Private API
2. Private API provides user- and administrator-access to data and changing data
3. Internal API provides helpers and an interface for storage and caching

Web UI

These HTML pages are paired with a NodeJS handler that responds to HTTP requests on GET and POST requests. The user and administrator Web UI are both formed out of these pages. Each route in the Web UI can be made from an HTML page and optionally a NodeJS handler.

URL:            /account/change-username
HTML:   /src/www/account/change-username.html
NodeJS: /src/www/account/change-username.js

HTML pages can be served static (without the extension) by not pairing a NodeJS file. The NodeJS file may expose a method for each HTTP method and a before method that will run prior to anything. POST data will be previously bound to the request object as req.body. QueryString data will be req.query. File uploads will be bound to req.uploads.

{
  before: async (req),
  get: async (req, res),
  post: async (req, res),
  patch: async (req, res),
  put: async (req, res),
  delete: async (req, res)
}

Private API

The private API is acccessible to your application server, dashboard modules and code running on your dashboard server. The API composes operations out of the Internal API and other parts of the Private API for user and administrator operations.

The Private API can be exposed to HTTP requests by client-side JavaScript and user's web browser extensions. These requests are authenticated by the web browser cookie created when signing in, the same as when a user is opening pages in their browser.

process.env.ALLOW_PUBLIC_API = true

The Private API is accessible via a NodeJS global object that receives a HTTPClient request object or similar and returns data or performs operations.

const req = {
  body: {
    username: 'my-username',
    password: 'a-password'
  }
}
const account = await global.api.user.CreateAccount.post(req)

Your application server may proxy the HTTP endpoints:

const headers = {
  "x-application-server": "address",
  "x-dashboard-server": "dashboard address",
  "x-accountid": "xxx",
  "x-sessionid": "yyy",
  "x-dashboard-token": bcrypt(`${APPLICATION_SERVER_TOKEN}/${accountid}/${sessionid}`, randomSalt)
}
const body = {
  username: 'my-username',
  password: 'a-password'
}
const account = await proxy.post('/api/user/create-account', headers, body)

Internal API

These are only accessible to code on the Dashboard server. They provide the basic database operations for storage, caching, and request processing.

const dashboard = require('@userappstore/dashboard')
const thing = await dashboard.Storage.write('thing', 'contents')

Multiple storage backends are supported officially for Dashboard. You can add support for any other database or system by replicating the interface's basic read, write and listing operations.

Data can be cached to avoid reloading database operations. It will automatically re-set data when it is modified. By default the caching can be done in local memory or Redis. Using local memory should only be done when you have a single dashboard server instance.