Engineering inside Orbit /

Interface and interaction architecture

The public design preview uses isolated React state for each artwork and version. The private full-stack workspace adds uploads, versioned records and a WaveSurfer media timeline tied to the actual video.

Files have identities

Each media version records its file identifier and SHA-256 digest. Comments store the file digest and version identifier alongside their anchor. This keeps a note attached to the bytes that the reviewer saw. Adding a version preserves existing comments and explicitly resets approval instead of relying on a visual status badge.

Approval checks current state

The server checks the owner’s permission, expected record version and reviewed content digest before approval. It also rejects approval when current-version comments remain open. The client therefore cannot approve an obsolete review by submitting an old screen’s state. Reloading and reviewing the current version is the recovery path after a conflict.

A room is a permission boundary

Private records and original files are scoped to the authenticated workspace. Public review links use a limited projection, with a stored token hash and expiry time. File access through that link is restricted to versions in its room. A read-only share does not unlock the private owner endpoints or unrelated uploaded files.

Exports retain the decision trail

The PDF decision log includes version filenames and digests, note authors and resolution states, and recorded approval information. It is generated from the saved room. Upload validation and explicit size limits sit before the version command, while the interface handles a failed upload without manufacturing a successful version or approval.

Operating the product

Start with the public interface to explore the design using example records. These interactions stay in the current view. Open the private workspace from the interface to use the existing account, storage and product workflows.

When a file upload fails, keep the previous version and review state. Correct the file or size issue before retrying.

When the saved version changes during review, reload and inspect the current file before approving again.

Use the decision-log export for a portable review record; retain the original media separately when needed.

Treat review-link access as reading access. Record approvals through the authorised workspace.

A deployment handover must verify configured origin, persistent records and files, backup recovery and notification providers independently.

Independent by construction

Orbit has its own application source, build configuration, local server, database, object store and session cookie. The fifteen applications reuse copies of a common foundation, but their operational data and credentials are independent. A shared dependency cache on this Mac saves disk space; each product includes a lockfile and a command to install its own dependencies.

Mutations validate the workspace and current record version. Approval binds the reviewed content digest; an idempotency key prevents an identical retry from becoming a second action. These controls are implemented in the server, alongside the product-specific rules described above.