UmbraTrans/docs/umbratrans-ui-design.md

UmbraTrans Web UI design

Status: static prototype for review Database transition: paused Primary URL: https://umbratrans.bdmurphy.me/ Admin URL: https://umbratrans.bdmurphy.me/uadmin/ Prototype listener: local machine, TCP 8442

Product shape

UmbraTrans has two related surfaces:

1. Workspace — the daily working environment for a signed-in user. It is project-focused and optimized for reviewing books, speakers, voices, translations, audio runs, and delivery status.
2. Control — the /uadmin/ management surface for account provisioning, organizations, projects, maintenance, audit, and system statistics.

The workspace and control surfaces share the Umbra brand and accessibility conventions, but intentionally use different layouts and visual emphasis.

Visual reference

The control surface references the existing Umbra Audio Review UI at umbraudio.bdmurphy.me:

• background: #1a1a2e
• panel: #16213e
• elevated/stat panel: #0f3460
• primary accent: #7c3aed
• secondary accent: #a78bfa
• text: #e0e0e0
• muted text: #94a3b8
• success: #10b981
• warning: #f59e0b
• danger: #ef4444
• compact cards, top navigation, status badges, and data tables
• supplied site icon: /home/umbra/Documents/UmberTrans_Icon.jpg, copied to the prototype as web/assets/umbratrans-icon.jpg

The workspace uses a deliberately different Studio language: a slate/indigo canvas, left navigation rail, teal action accent, amber review accent, larger reading areas, and a pipeline-oriented layout. It should feel like a production desk rather than an admin console.

Routes

Route	Purpose	Access
/	Sign-in and account entry	Public
/workspace/ or /workspace.html	Authenticated project workspace	Authenticated user
/uadmin/	Accounts, projects, maintenance, statistics	Organization/platform administrator
/uadmin/accounts	Account provisioning and lifecycle	Administrator
/uadmin/projects	Project management	Administrator
/uadmin/maintenance	Worker, queue, and storage operations	Administrator
/uadmin/statistics	Usage and system health	Administrator

The static prototype uses index.html, workspace.html, and uadmin/index.html. The eventual application should serve the same routes without exposing filesystem paths.

Authentication direction

The UI supports two account-enrollment paths:

1. Temporary local password — an administrator provisions an account with a one-time temporary password. Only an Argon2id hash is stored. The account is marked must_change_password; the first login must change it before any workspace access.
2. OIDC enrollment — an administrator provisions an account or invitation and the identity provider completes credential setup. No local password is created.

The application should hide this choice behind an authentication adapter. Both paths must resolve to the same canonical users identity, organization membership, project membership, and server-side session. The browser must never supply a trusted user_id, organization_id, project_id, or role.

The prototype does not authenticate, store credentials, or call a database.

Admin workflows to design

• Create/suspend/reactivate an account.
• Issue a temporary password or OIDC invitation.
• Require first-login password change for temporary-password accounts.
• Assign organization and project memberships.
• View account status, last login, and MFA state.
• Create, archive, and transfer projects.
• View worker health, queue depth, failed jobs, and storage status.
• View audit history and export a sanitized report.

Every destructive action requires a confirmation step, an explicit permission check, and an audit event.

Workspace workflows to design

• Select an authorized project.
• View source book, analysis version, speakers, canonical voices, and voice cast.
• Review translation status by locale.
• Monitor analysis, audio, QA, and release stages.
• Inspect job progress without exposing filesystem paths.
• Download only artifacts authorized for the current project and release state.

Prototype limitations

The current prototype uses mock data and client-side navigation only. It does not:

• connect to PostgreSQL;
• authenticate users;
• issue or validate passwords;
• expose real accounts or projects;
• accept real credentials;
• perform administrative actions.

Buttons demonstrate intended states and interactions only. The UI must remain a prototype until the database transition and security gates are approved.

Local review

From the workspace root:

cd /home/umbra/src/UmbraTrans
python3 -m http.server 8442 --bind 0.0.0.0 --directory web

Then open:

• http://<local-host>:8442/
• http://<local-host>:8442/workspace.html
• http://<local-host>:8442/uadmin/

For production, terminate TLS at the approved reverse proxy, restrict the application listener to the required interface, and define the network allow-list before exposing port 8442.