PETRA System Brief¶

Purpose¶

PETRA is a battlespace management system providing command, control, and situational awareness across strategic, operational, and tactical echelons. It enables HQ commanders to plan and manage the battlespace while keeping troops at the edge synchronised in near-real-time, even under intermittent connectivity.

Components¶

Name	Type	Description
Node	Edge device	A blue-force-tracked edge device. May advertise video streams and/or control interfaces (e.g. MAVLink waypoints).
Server	Infrastructure	Routes traffic across the mesh using Zenoh. Designed to be stateless and expendable.
Web	Application	AdonisJS 7 web app for HQ commanders to view, plan, and manage the battlespace.
Directory	Application	AdonisJS 7 web app responsible for identity, auth, and RBAC across the entire system.
Gateway	Service	Rust-based translation layer converting between PETRA's internal schema and NATO partner formats.
Media Server	Infrastructure	RTSP server for video streams originating from Nodes and sensors. Configured out-of-band by HQ operations staff.
Tile Server	Infrastructure	MapProxy instance serving map tiles to Web and Android clients. May cache upstream sources or serve a pre-seeded offline dataset.
NiFi	Infrastructure	Optional ingest pipeline for external data feeds (AIS, ADS-B, satellite imagery, etc.) into Web.

Deployment¶

Directory is stood up first. All principals are onboarded with roles reflecting their military rank. Tokens are issued for Web and other services.
Web is deployed and first-time setup is completed — this creates the initial ORBAT and Comms Matrix.
Servers are deployed using tokens from Directory, either in cloud (via Docker) or on physical edge devices (via Ansible + Rust binaries).
Android clients are deployed via MDM, with config pointing to a Server for bootstrap and to Directory for auth.
Users authenticate on Web and Android via YubiKey (the same keys registered in Directory) and begin operating the system.

From this baseline, the system is designed to support ongoing churn: users joining and leaving, new servers being stood up, and new feeds or sensors being added at any time.

Optionally, a Gateway or NiFi instance can be deployed depending on operational requirements. NiFi is used to ingest external data sources into Web via DB or API (e.g. satellite imagery, targets, AIS, ADS-B). The Gateway handles import/export of position data for NATO interoperability.

A Media Server and Tile Server (MapProxy) may also be deployed. The Tile Server must have upstream connectivity to a tile source or a pre-seeded cache to function under the intermittent connectivity conditions expected at the edge. Both are configured out-of-band by HQ operations staff and do not require first-time setup within PETRA itself.

Trust Model¶

Web, Directory, Gateway, NiFi, Media Server, and Tile Server form the privileged core of the system. They are deployed and operated by HQ staff and are assumed to have reliable connectivity and physical security.

NiFi and Gateway are write-capable into the core and must authenticate via API token (NiFi) or verified inbound pipeline (Gateway). They should be treated with the same care as Web when scoping credentials and access.

The Media Server (RTSP) and Tile Server (MapProxy) are globally readable. They serve binary assets only, carry no per-principal access control, and do not authenticate readers — map tiles and video are assumed non-sensitive, with access controlled at the network level rather than by PETRA. All ingest and configuration is handled out-of-band by HQ operations staff, who are out-of-model — they do not hold Directory identities and are not PETRA principals. Consequently, content served by these components carries no PETRA provenance or audit trail; this is an accepted residual risk, mitigated by network-level controls.

Servers are content-blind store-and-forward relays, not pure routers. To support intermittently-connected edge devices, a Server durably buffers resources (chat, channels, drawings, invites, records) and replays them on reconnect. A Server never holds the content group key and cannot read payloads, forge identities, or mint tokens — content stays confidential even under capture. The security goals are therefore graded: (1) content confidentiality — strong and non-negotiable; (2) minimal metadata exposure — key-expressions must avoid carrying a semantic graph (channel membership, principal identifiers, precise location); and (3) bounded retention — buffered data is kept no longer than the expected offline-resync horizon. Compromise of a Server should expose no content and only bounded, minimised metadata.

Android devices are expected to be lost, captured, or frequently re-assigned between users with different access levels. They should hold only the information required for the current user's active session.

Nodes are edge devices and share the Android threat model: assume loss or capture. A captured Node exposes its signing identity for the duration of the current token batch, and — because a Node is a full mesh member — the shared deployment group key held in memory. A single captured Node therefore allows decryption of all members' sealed content for the current and previous key epoch, until the group key is rotated. That rotation is automatic on loss: revoking a device/node (or revoking an operator flagged lost/captured) triggers a coalesced group-key rotation, so a captured holder is cut off from newly-sealed content without waiting for a manual rotation — it keeps only what it already cached under epochs it already held. Nodes should store as little as possible and advertise only what is needed for their current operational role.

Auth and RBAC¶

Directory¶

All authentication and RBAC originates from Directory. On login, a user receives an IdentityToken encoding their roles. Servers receive a ServerToken. Devices do not receive a distinct token type — a device principal is issued an IdentityToken carrying a kind:device role prefix. All tokens use a protobuf format analogous to JWT.

Roles are shaped around jobs to be done — for example, a targeter receives access to the Targeting Board on Web and drone command controls on Android. The exception is the Admin role, which grants full visibility and control across the system and is intended for support or break-glass use only.

ORBAT¶

An ORBAT (Order of Battle) is created during Web's first-time setup and can be updated at any time by users with the appropriate role. It defines the command structure and serves two purposes:

Operational authority — who holds command at each echelon
Planning — who can issue and receive orders

The latest ORBAT always takes precedence. Users may be added to or removed from assets and channels at any time, including while edge devices are offline. After reconnecting, Android devices must resync their ORBAT — the tactical team may have new members, a new commander, or pending SitRep requests and plans.

Connectivity¶

Web and Directory are assumed to have reliable connectivity. Servers and Android devices are assumed to have intermittent connectivity and must function gracefully when offline, syncing state on reconnect.

Planning¶

HQ (Web)¶

Strategic and operational planning is conducted on Web, where commanders have access to full data feeds, a keyboard and mouse, and a richer interface.

Plans are created via the Orders tab and are modelled on the 7 Questions framework. A plan comprises:

7 Questions structured text
Drawings (SIDC/NATO symbology)
Optional attachments (e.g. KML files)

These are packaged and published as a single plan pack. On Web, the latest plan is displayed as a toggleable map layer; prior plans are available as additional layers.

Edge (Android)¶

When a new plan is published from Web, it arrives on Android as a push notification. The latest plan is displayed as a toggleable layer.

Upon receiving a plan, a commander at the edge creates a Tactical Plan — also following the 7 Questions structure, with drawings and optional KML — as an extension of the plan received from above. This tactical plan is distributed:

Up — back to Web
Down — to subordinate troops as defined by the ORBAT

This ensures troops see both their own commander's plan and the higher-level plan above it. The ORBAT structure is infinitely nestable, so multiple active plan layers may exist simultaneously across echelons.

Access control: Plans are sensitive. A member of a unit sees their own unit's plan, the plan one echelon above, and the plans of subordinate units. Plans more than one echelon above a unit are visible to commanders only. Higher intent beyond one echelon reaches troops through the chain of tactical-plan extensions, not through raw plan distribution. Commander status is derived from the ORBAT.

SitReps¶

Web planners can schedule SitRep requests on a recurring cadence. When due, a push notification is sent to the relevant Android user. A SitRep is a commander's return: only a unit's appointed commander — or a field-formed team's lead — is asked and only they may submit, so a unit with nobody appointed shows as an ORBAT gap rather than as a non-response. The SitRep form is a simple RAG status plus free-text comments. Web logs all responses, including non-responses, for accountability.

Data Retention and Tombstoning¶

Drawings, channels, plans, and SitReps are never deleted — they are tombstoned.

Web stores every version of an object, with the final version marked as the tombstone. This supports the replay feature (see below).
Servers may store tombstones with minimal metadata for routing purposes.
Android stores only the latest version of an object. Tombstones are propagated to the edge to ensure stale data is replaced rather than persisted.

Chat and Voice¶

Channel membership is derived from the Comms Matrix configured on Web. Channels created at the edge (Android) are valid but are flagged on Web for review — they must be formally adopted or removed by an administrator.

Channel ownership and admin rights are determined by the ORBAT (i.e. who holds command), distinct from system-level RBAC. Users with the Admin system role have visibility and management rights across all channels regardless of ORBAT position.

Voice uses the Opus codec. Voice can be disabled entirely on Android when a physical radio is in use.

Drawings¶

All drawings use SIDC / NATO symbology. Drawings are subject to ORBAT and RBAC controls. A drawing may be attached to a plan or exist as a standalone layer. All drawings are toggleable on the map.

Video¶

Web and Android support RTSP streams, typically served by the Media Server. A Node (sensor or drone) may advertise a stream URL — this is not constrained to the Media Server; the advertised URL is used as-is by the operational team. If present, a player is shown in the interface. The Media Server is configured and managed out-of-band by HQ operations staff — no PETRA principal has write access to it via the system.

Targeting¶

Web includes a Targeting Board modelled on Palantir's targeting workbench, presented as a Kanban interface. Targeting is primarily a Web feature.

Users with the Targeting Directory role can promote targets from the board to the COP (Common Operating Picture) and vice versa. Targets on the COP are distributed to Android devices and displayed on the map.

NiFi¶

Some PETRA deployments include a NiFi cluster co-located with Web. NiFi is used to:

Ingest external data feeds (e.g. AIS, ADS-B) as tracks on the COP
Push targets to the Targeting Board via API

NiFi authenticates via an API token generated from the Web admin page, and all writes go through the authenticated API so that app-layer authz, versioning, and tombstoning apply. (Earlier deployments wrote position tracks directly to the database; that path is being retired in favour of the API. Those track rows are ephemeral COP assets and are exempt from tombstoning either way.) NiFi operators are out-of-model — they do not hold Directory identities and are not PETRA principals.

Replay¶

Web includes a replay feature allowing commanders to scrub through historical COP state for training and post-mission analysis. Because data is versioned and tombstoned rather than deleted, the full lifecycle of every object — creation, modification, and removal — is available for replay. This also provides an audit trail of who did what and when.

Drone Control¶

PETRA Nodes (including drones) provide blue-force tracking and video feeds by default. Nodes may additionally advertise control capabilities. When present, and subject to the user's Directory role, a Control button appears on Web allowing MAVLink waypoints to be sent to the device.