# ArdaForm

> ArdaForm is a platform for building, deploying and remotely managing dedicated
> applications on Linux-based devices — kiosks, point-of-sale terminals, digital
> signage, attendance terminals, industrial panels and Raspberry Pi products.
> Applications are written in HTML, CSS and JavaScript and run on ArdaPlayer, a
> lightweight Go + WebKit runtime that exposes native hardware through a
> capability-scoped JavaScript API.

ArdaForm is under active development. The runtime, encrypted packaging, device
control protocol and remote management are implemented and running on deployed
hardware. The public portal (control panel) is not open for public sign-up yet;
the `arda` CLI and several API groups are still being finalised. Documentation
labels every capability as Working, In progress or Planned.

## Core concepts

- **Application** — your HTML/CSS/JavaScript plus an `arda.json` manifest that
  declares the entry point and the device capabilities the app may use.
- **Package** — the built artefact: one signed (Ed25519) and encrypted
  (AES-256-GCM) `.arda` file, optionally bound to a device, installation or
  account. Decrypted into memory at load, never unpacked to disk.
- **ArdaPlayer** — a single Go binary that renders the application full screen
  through the system WebKit, verifies and loads the package, injects the `arda.*`
  native bridge, and holds one outbound control connection.
- **Release** — a package uploaded to the control plane, identified by ID and
  SHA-256. Immutable; promoted between channels (dev/beta/stable) rather than
  rebuilt.
- **Device** — one installation, identified by a stable ID derived from the
  machine. Belongs to a fleet and optionally a group.
- **Fleet** — the set of devices running one application.

## Key technical facts

- Devices open **no inbound ports**. A device dials the control plane over TLS
  and holds one persistent WebSocket; all operator commands ride down it.
- Control-channel frames are `command|payload`, split on the first `|` only;
  payload is JSON or empty.
- Application data reaches the server only through `arda.sync.*`. The page has no
  network stack of its own.
- `arda.sync.push()` is durable and **at-least-once** — servers must deduplicate
  by record ID and acknowledge each one.
- Updates are named, not pushed: the control plane sends a URL plus SHA-256; the
  device downloads, verifies signature and hash, stages, and reports status.
- Local databases and the outbound queue are encrypted at rest with
  hardware-derived keys.
- The control plane never holds a private signing key. Application packages are
  signed by the customer's own pack key; runtime binaries by a separate release
  key.

## JavaScript API groups (`arda.*`)

- `arda.system` — device ID, OS/CPU/memory/disk snapshot, display control,
  restart, reboot, logging. **Working**
- `arda.db(name)` — encrypted key/value stores; put/get/del/keys/scan/batch.
  **Working**
- `arda.storage` — scoped file storage with quotas. **Working**
- `arda.sync` — push (durable queue), get (request/response), profiles, state
  and events. **Working**
- `arda.usb` — enumerate devices, attach/detach events, classified types.
  **Working**
- `arda.app` — config from the control plane, update checks, restart. **Working**
- `arda.net` — connectivity state, interfaces, Wi-Fi scan/join. **In progress**
- `arda.printer` — receipts, labels, raw ESC/POS, cash drawer, status.
  **In progress**
- `arda.camera` — open/capture/stream, QR and barcode scanning. **In progress**
- `arda.gpio` — mode/read/write/toggle/pulse/watch with debounce. **In progress**
- `arda.face` — local detect/enrol/match, on-device only. **Planned**
- `arda.audio` — play/stop/volume/output selection. **Planned**

Capabilities are declared in the manifest. An undeclared group is `undefined` at
runtime, not a method that throws. Check with `arda.can(capability)`.
Errors reject as `ArdaError` with a stable `code` field.

## The arda CLI (preview — names may change)

`login` `init` `link` `build` `push` `releases` `promote` `tag` `deploy`
`rollback` `pin` `cancel` `devices` `status` `claim` `group` `env` `logs`
`console` `screenshot` `watch` `shell` `exec` `info` `restart`

Authenticates from `ARDA_TOKEN`; signs with `ARDA_PACK_KEY` locally.
Non-interactive by default, `--json` output, meaningful exit codes.

## Pages

- [Home](https://ardaform.net/) — what ArdaForm is and who it's for
- [Platform](https://ardaform.net/platform) — the four pieces and how the loop closes
- [ArdaPlayer](https://ardaform.net/ardaplayer) — the Go + WebKit runtime, boot sequence, Electron comparison
- [Native APIs](https://ardaform.net/apis) — the twelve API groups with worked examples
- [CLI](https://ardaform.net/cli) — git-style deployment workflow
- [Deployment](https://ardaform.net/deployment) — provisioning, updates, staged rollouts, support tools
- [Security](https://ardaform.net/security) — threat model, layers, key handling
- [Use cases](https://ardaform.net/use-cases) — POS, kiosks, signage, attendance, industrial, Raspberry Pi
- [Roadmap](https://ardaform.net/roadmap) — working / in progress / planned
- [About](https://ardaform.net/about) — why the platform exists
- [Early access](https://ardaform.net/early-access) — the portal is not open for public sign-up yet

## Documentation

- [Docs overview](https://ardaform.net/docs/)
- [Quickstart](https://ardaform.net/docs/quickstart)
- [JavaScript API reference](https://ardaform.net/docs/api-reference)
- [arda CLI reference](https://ardaform.net/docs/cli-reference)
- [Package format](https://ardaform.net/docs/packaging)
- [Device control protocol](https://ardaform.net/docs/protocol)

## Related tooling

- **ArdaLive** — a published VS Code extension (v1.4.0, MIT) by the same team:
  lightning-fast HTML live preview that diffs <head>/<body> and patches the live
  DOM in place via idiomorph, so scroll, focus and JS state survive each edit.
  Linked CSS hot-swaps via blob URLs; serves the unsaved editor buffer rather
  than the file on disk. Plain HTML/CSS, no framework required — which is what
  an ArdaForm application is, though the extension is fully independent of the
  platform and useful on any website. Localhost only.
  https://marketplace.visualstudio.com/items?itemName=tominkoltd.ardalive
- **APM (Advanced Process Manager)** — a separate, finished product by the same
  team: a single static Go binary that supervises any Linux executable, with a
  built-in reverse proxy, rate limiting, TLS and cross-language inter-worker
  IPC. The ArdaForm control plane runs under it. https://processmanager.dev

## Contact

- Contact form: https://ardaform.net/contact
- Security reports: https://ardaform.net/contact?topic=security
- Early access:  https://ardaform.net/early-access

No email addresses are published on this site; all contact is via the forms above.
- Portal (not yet public): https://portal.ardaform.net