UmbraAudio/specs/19-enterprise-control-plane.md

Spec 19 — Umbra Enterprise Control Plane, Multi-Tenant Projects, and Voice Library

• Status: Proposed architecture and migration specification
• Date: 2026-09-23
• Scope: UmbraTrans enterprise platform; additive to UmbraAudio
• Primary users: Authors, editors, translators, proofreaders, audio directors, voice-library operators, release managers, and administrators

1. Executive Decision

The project needs two related but distinct systems:

1. UmbraAudio remains the existing local English audiobook engine and its read-only upstream source for UmbraTrans.
2. Umbra Enterprise Control Plane becomes the multi-user, multi-project system of record for projects, people, permissions, translations, deliverables, reviews, voice assets, pronunciation records, licensing, costs, and releases.

The control plane must not be implemented as another table or mode inside the current UmbraAudio project database. It must be a separate service/package with its own relational database, artifact store, job scheduler, authentication boundary, and audit log.

The central database decision is:

Do not create a database table per project or a table per language. Use a shared logical relational schema with tenant_id, project_id, locale_id, and revision foreign keys. A separate physical database may be used for a large tenant or for an isolated deployment, but it uses the same logical schema and migration system.

A project contains one source work and many target locales. Each locale produces independent translation and audio revisions, and each deliverable type (EPUB, PDF, M4B, MP3, WAV, and future formats) is a versioned artifact. Every source change, translation fix, voice change, pronunciation change, audio regeneration, approval, download, and release is traceable.

The current UmbraAudio implementation has useful local multi-project primitives, but it is not yet a multi-user enterprise platform. This document defines the target architecture without changing the current UmbraAudio code.

2. Current-State Audit

2.1 What exists today

The current repository has several useful building blocks:

Existing capability	Current location	Assessment
Per-project directory and database	project_bootstrap.py, config.py, database.py	Good local isolation primitive
Project discovery	config.list_projects()	Filesystem scan, not an authoritative multi-user catalog
Project selection	active_project browser cookie in web/routes.py	UI context only; not authentication or authorization
Per-project project_id columns	database.py, SCHEMA_SQL	Useful locally, but IDs are scoped to one project database
New project web flow	/projects, /projects/new, /api/projects	Creates isolated projects successfully for a local user
SQLite WAL	project and voice registry connections	Helps same-host contention; not distributed coordination
Shared voice registry	umbraaudio/voices/registry.py	Cross-project names and some voice metadata, but not a commercial voice catalog
Cross-project name/voice library	umbraaudio/library.py	Basic reuse; lacks locale, rights, cost, versions, and access policy
Pipeline/generation status	per-project JSON files and in-process managers	Useful for one operator; not a durable multi-worker scheduler
UmbraTrans contracts	specs/18-UmbraTrans.md	Defines per-project production semantics; needs an enterprise control plane around it

2.2 What is not enterprise-ready today

The current setup does not provide:

• user accounts, organizations, tenants, or authentication;
• project membership, roles, permissions, or row-level access control;
• an authoritative project registry with ownership and lifecycle state;
• safe concurrent editing by multiple people;
• a durable distributed job queue or worker lease system;
• per-user or per-project resource quotas;
• target-language deliverable and revision tracking;
• a central artifact registry for ebooks, PDFs, audiobooks, and QA reports;
• a rights/usage/billing model for rented or purchased voices;
• a global, locale-aware pronunciation catalog with review history;
• provider availability, license expiry, territory, and takedown handling;
• a complete audit trail for reads, writes, approvals, downloads, and releases;
• encrypted object storage and signed artifact access;
• a searchable, cross-project operational dashboard; or
• a reliable separation between a user's selected project and a user's authorized projects.

The active_project cookie must not be treated as an authorization mechanism. A user must be able to select a project only after the server verifies that the user is a member of that project.

2.3 What must remain unchanged

The enterprise migration does not require modifying the current UmbraAudio engine. The control plane imports a read-only snapshot of the current project and keeps a one-way link back to the legacy project. English audiobook generation can continue in UmbraAudio while translation and enterprise workflows run in the new system.

3. Goals and Non-Goals

3.1 Goals

1. Manage many organizations, users, projects, source works, locales, and deliverables.
2. Let each user see only the projects and locales they are authorized to access.
3. Support a project picker and project-scoped dashboard with language/release status.
4. Track source, translation, pronunciation, voice, audio, review, and release revisions.
5. Support concurrent work on different projects with bounded shared-resource usage.
6. Store ebooks, PDFs, audio, and other large artifacts outside the relational database.
7. Provide immutable lineage and auditability from source text to released audiobook.
8. Support a reusable, licensed voice and pronunciation library across projects.
9. Track voice rental, usage, cost, rights, territory, term, and expiration.
10. Make fixes safe: a correction creates a new revision and never destroys history.
11. Support local development and a later production deployment without changing the domain model.

3.2 Non-goals

• Turning SQLite into a multi-user authorization system.
• Creating one table per project or one table per language.
• Storing WAV, M4B, MP3, PDF, or EPUB binaries as large blobs in the control database.
• Letting a browser cookie grant access to a project.
• Letting a target-language correction silently mutate the English source.
• Letting a voice asset be reused after its license or territory authorization expires.
• Coupling the control plane to one TTS provider or one deployment host.
• Replacing UmbraAudio's existing English generation path in the first migration phase.

4. Architecture at a Glance

Users / Reviewers / Release Managers
                │
                ▼
┌──────────────────────────────────────────────────────────────┐
│                 Web/API Control Plane                        │
│ authentication · organizations · projects · access · review   │
│ deliverables · audit · dashboards · API                      │
└───────────────┬───────────────────────┬──────────────────────┘
                │                       │
                ▼                       ▼
┌──────────────────────────┐  ┌────────────────────────────────┐
│ PostgreSQL Control DB    │  │ Versioned Object/Artifact Store │
│ tenants, projects,       │  │ source, translations, PDFs,     │
│ revisions, issues,       │  │ audio, manifests, QA reports    │
│ voices, rights, usage    │  │ encrypted, signed, immutable    │
└───────────────┬──────────┘  └───────────────┬────────────────┘
                │                              │
                └──────────────┬───────────────┘
                               ▼
                 ┌─────────────────────────┐
                 │ Durable Job Scheduler   │
                 │ queues · leases · quota │
                 │ retries · cancellation  │
                 └────────────┬────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
  Analysis workers      Translation workers     Audio/Export workers
  CPU/LLM/GPU pools     provider/model pools    TTS/mix/ffmpeg pools

The control plane is the source of truth for identity, authorization, state, lineage, and release decisions. Workers are disposable and may be restarted at any time.

5. Tenancy, Identity, and Access Control

5.1 Tenancy model

The primary tenancy boundary is an organization (also called a tenant). An organization may contain many users, projects, voice-library records, billing accounts, and policies.

A user may belong to multiple organizations. A user may have different roles in different organizations and different projects.

organization
  ├── users and memberships
  ├── projects
  │     ├── project members
  │     ├── source work
  │     └── target locales
  ├── shared voice catalog
  ├── pronunciation catalog
  ├── billing and entitlements
  └── audit and policy records

5.2 Identity provider

The control plane uses an external OpenID Connect/SAML identity provider or an equivalent managed identity service. Local passwords may exist only as a controlled fallback for a private installation. The web application never trusts a user-supplied project slug, organization ID, or role without a server-side authorization check.

Every request carries an authenticated subject. A project selection is a signed UI/session context, not a capability.

5.3 Roles and permissions

The initial role set is:

Role	Capabilities
owner	Organization ownership, billing, destructive actions, all projects
admin	Organization configuration, users, projects, policies, library administration
producer	Create projects, schedule work, manage deliverables and releases
source_editor	Edit approved English source analysis and source facts
translator	Draft and revise target text within assigned locales/scenes
proofreader	Review and approve target text; request source clarification
audio_director	Cast voices, approve pronunciation and performance, approve audio
voice_manager	Manage voice catalog, licenses, reservations, rates, and provider connections
release_manager	Approve and publish deliverables, metadata, credits, and manifests
viewer	Read-only access to assigned projects and approved/review-visible artifacts
billing_admin	View usage, invoices, entitlements, and spending limits; no manuscript edit

Permissions are additive policy records, not hard-coded role names in route handlers. A route or worker asks the authorization service whether a subject may perform an action on a specific resource.

5.4 Resource-level access

Access may be restricted by:

• organization;
• project;
• locale;
• source revision;
• translation revision;
• deliverable/revision;
• voice library record;
• artifact classification; or
• release state.

A project member may have access to only the English source while a target proofreader has access to a specific locale and its review queue. A voice manager may see licensing and usage metadata without seeing an unpublished manuscript.

5.5 Database enforcement

PostgreSQL row-level security is the default enforcement layer. Application checks improve UX, but they do not replace database policies. Every tenant-owned row carries tenant_id. Worker service accounts receive only the permissions required for their queue and artifact scope.

Sensitive actions are denied by default:

• a user cannot download an unpublished artifact without an explicit grant;
• a translator cannot approve their own final release without the required independent review policy;
• a worker cannot read a project outside its lease;
• a voice asset cannot be attached to a project without an active entitlement; and
• a release cannot include a blocked or unapproved revision.

6. Work, Project, Locale, and Release Model

A source ebook is not the same thing as a production project. The model separates them.

6.1 Work

work is the bibliographic identity of a book:

• title, author, series, ISBN/work identifier;
• source language and original publication information;
• rights/provenance records; and
• one or more source editions/assets.

A public-domain edition and an author's revised manuscript can be different source assets belonging to the same work, or separate works if the editorial relationship is uncertain.

6.2 Project

project is a production workspace for one source revision and a selected set of locales, quality policies, voice policy, team, schedule, and release policy.

A project contains:

• one or more source assets and frozen source revisions;
• a current source-analysis revision;
• project members and assignments;
• one or more target locale lanes;
• deliverable definitions;
• review and issue queues;
• voice and pronunciation bindings; and
• release history.

A project can be cloned as a new production effort without copying historical revisions or silently reusing a voice license.

6.3 Locale lane

project_locale is the relationship between a project and a target locale such as de-DE, ja-JP, or zh-Hans. It contains locale-specific:

• translation status and current revision;
• proofreader and translation assignments;
• terminology and style profile;
• pronunciation profile;
• voice/cast matrix;
• audio-build status;
• QA profile and reports;
• deliverable status; and
• release state.

There is no translations_de table, translations_fr table, or audio_de table. All locales use the same tables with a locale_id foreign key and appropriate indexes.

6.4 Deliverable

A deliverable is an output type requested for a project/locale, such as:

• EPUB ebook;
• PDF ebook;
• print PDF;
• M4B audiobook;
• MP3 chapter package;
• WAV masters;
• translation-only DOCX/Markdown package; or
• a future format.

A deliverable has many immutable deliverable_revisions. A revision is never overwritten after approval. A fix creates a successor revision linked through supersedes_revision_id.

7. Storage and Database Topology

7.1 PostgreSQL control database

The control plane uses PostgreSQL as its system of record. SQLite remains appropriate for a single-user local UmbraAudio project or a disposable worker cache, but it is not the enterprise multi-user database.

PostgreSQL stores:

• identity and membership;
• project and locale state;
• source/translation/analysis metadata;
• revisions and lineage;
• review tasks, issues, approvals, and audit events;
• voice catalog metadata, entitlements, rates, and usage;
• job and lease state;
• artifact metadata and storage URIs; and
• release manifests and quality report metadata.

7.2 Object/artifact store

Large files live in an encrypted object store or equivalent content-addressed storage:

• original ebooks and scans;
• normalized source artifacts;
• translation exports;
• PDF/EPUB/DOCX files;
• voice references and approved pronunciation audio;
• individual audio clips;
• chapter and full-book masters;
• QA media samples; and
• signed manifests and reports where file size requires it.

The relational database stores a storage key, URI, checksum, byte size, media type, retention class, encryption key reference, and access policy. It does not store large binary payloads as ordinary rows.

7.3 Physical isolation options

The default production topology is one shared PostgreSQL cluster with tenant RLS. When a customer requires stronger isolation or a very large scale, deploy a separate database cluster or database for that tenant using the same schema migrations. This is database-per- tenant, not table-per-project and not table-per-language.

Object storage may use tenant prefixes, separate buckets, or separate encryption keys. The application always resolves storage through an authorization-aware artifact service; users never receive arbitrary filesystem paths.

7.4 Object lifecycle

Artifacts are immutable and content-addressed. A write follows:

1. request an upload session;
2. stream to a quarantine/temporary object;
3. calculate SHA-256 and validate media type;
4. commit the object and metadata in a transaction;
5. run malware/archive validation and metadata extraction;
6. mark the artifact available; or
7. mark it quarantined/failed without exposing it to workers.

Deletion is a governed tombstone/retention operation, not an immediate filesystem delete. Legal holds, active licenses, release history, and audit requirements can prevent deletion.

8. Logical Relational Model

The following is the logical model, not a mandate to create every table in the first sprint. Names may change, but the relationships and keys are stable.

8.1 Identity and tenancy

organizations
users
organization_memberships
projects
project_members
project_access_grants

Important fields:

• organizations(id, slug, name, status, retention_policy, created_at)
• users(id, identity_subject, display_name, status, created_at)
• organization_memberships(organization_id, user_id, role, status)
• projects(id, organization_id, work_id, slug, name, status, source_locale, created_by)
• project_members(project_id, user_id, role, status)
• project_access_grants(id, project_id, principal_type, principal_id, scope, expires_at)

8.2 Source and production content

works
source_assets
source_revisions
analysis_revisions
semantic_packages
identity_registries
glossary_revisions
memory_revisions
translation_revisions
translation_blocks
target_render_spans
alignment_links

Important foreign keys:

• every project row has organization_id and work_id;
• every source revision has project_id and source_asset_id;
• every analysis revision has source_revision_id;
• every translation revision has project_id, locale_id, and source_revision_id;
• every target render span belongs to one translation revision and has an ordinal order;
• every alignment link references source and target spans, never only raw display text.

8.3 Locale, review, and release

locales
project_locales
review_tasks
review_comments
review_decisions
issues
issue_links
approvals
deliverables
deliverable_revisions
release_manifests

locales is a controlled catalog of BCP-47 language/script/locale values. A locale can be used by many projects, while project_locales stores project-specific status and policy.

issues are first-class records with:

• organization, project, locale, and optional source/target/audio scope;
• severity and category;
• exact source span, target render span, clip, chapter, or deliverable link;
• status, assignee, reviewer, and timestamps;
• evidence and reproduction information;
• fix revision and regression-test result; and
• audit event references.

8.4 Artifacts

artifacts
artifact_versions
artifact_checksums
artifact_links
artifact_access_events

An artifact_version represents one immutable file or structured package. It links to the revision that produced it and records:

• storage key and signed-access policy;
• SHA-256, size, media type, and compression;
• producer job and model/engine versions;
• source/translation/voice/pronunciation/audio dependencies;
• retention and legal-hold state; and
• supersedes/derived-from relationships.

8.5 Operations and audit

jobs
job_attempts
job_leases
worker_heartbeats
resource_pools
resource_reservations
audit_events
idempotency_keys
outbox_events

Every mutation writes an audit event containing actor, organization, project, resource, action, before/after revision IDs, timestamp, request ID, and reason where applicable.

9. Artifact Lineage, Revisions, and Fixes

The canonical lineage is:

source asset
  → immutable source revision
  → analysis/semantic revision
  → identity and glossary revisions
  → target translation revision
  → ordered target render spans
  → target voice/pronunciation binding
  → audio clip and chapter revisions
  → deliverable revision
  → release manifest

A fix is never an in-place mutation of a released artifact. The workflow is:

1. open an issue against an exact revision and scope;
2. assign the appropriate owner;
3. create a source, translation, voice, pronunciation, audio, or release revision;
4. run only the affected validation/rebuild jobs;
5. compare the new artifact with its predecessor;
6. obtain required independent approvals; and
7. publish the successor or reject it.

The UI must show:

• current revision;
• previous approved revision;
• open issues;
• rebuild progress;
• quality delta;
• voice and pronunciation cost delta;
• approvers; and
• download links for each permitted revision.

10. Review, Audit, and Access Workflow

10.1 Project dashboard

The project dashboard is the user's authorized view of a project. It shows:

• source revision and source approval state;
• target locale matrix;
• translation progress and blocked scenes;
• review queue size and age;
• pronunciation coverage;
• voice/cast status and license warnings;
• audio build and QA status;
• deliverable versions and release state;
• current spend/estimate;
• active workers and resource contention; and
• recent audit events.

A typical locale row is:

Locale	Source	Translation	Proofread	Pronunciation	Cast	Audio	QA	Release
de-DE	frozen	82%	14 queued	98%	approved	76%	pending	draft
ja-JP	frozen	61%	32 queued	91%	pending	0%	blocked	draft

10.2 Project picker

The project picker lists only projects returned by the authorization service for the authenticated user. Selecting a project sets a signed session/UI context and navigates to a project-scoped URL. It never grants access and never changes the user's memberships.

10.3 Review queues

Review tasks are assigned by role, locale, risk, and workload. High-risk translation, pronunciation, voice, and audio items are never silently auto-released. A reviewer sees the source evidence, current revision, proposed fix, relevant scene context, and prior approval history.

10.4 Audit and downloads

The system records:

• login and authorization failures;
• project selection and switching;
• source/translation/voice/pronunciation edits;
• review decisions and approvals;
• artifact generation and quality reports;
• downloads and signed-link issuance;
• voice usage and billing changes; and
• release, supersession, withdrawal, and takedown.

Audit records are append-only and retained according to organization policy and legal hold.

11. Independent Voice and Pronunciation Library

The voice library is an independent commercial and creative subsystem. It is not merely a global speakers.json or a name-based row in the current voice registry.

11.1 Voice identity versus provider asset

Keep these concepts separate:

• Logical voice identity: the reusable character/performance identity in UmbraTrans.
• Acoustic voice asset: a provider voice, recorded actor, cloned voice, or licensed sample usable by a particular engine.
• Voice profile: the approved combination of identity, language, style, engine, and pronunciation behavior.
• Project binding: the assignment of a logical speaker to a voice profile for one project, locale, acoustic instance, and revision.

One logical identity may use different provider assets in different languages. One provider asset may be reused by many projects only when its license permits it.

11.2 Voice catalog tables

voice_assets
voice_asset_locales
voice_profiles
voice_profile_revisions
voice_bindings
voice_reviews
voice_licenses
voice_entitlements
voice_reservations
voice_rate_cards
voice_usage_events
voice_invoices
voice_takedowns

Important fields include:

• provider and provider voice ID;
• actor/voice name and legal entity;
• supported languages, scripts, locales, genders/presentations, and styles;
• engine/model compatibility;
• reference audio URI, checksum, transcript, and retention policy;
• license type, territories, media, exclusivity, term, concurrency, and derivative rights;
• rate, minimum commitment, currency, billing unit, and effective dates;
• current availability, reservation state, and takedown state;
• quality, pronunciation, identity, and listener-test results; and
• consent and evidence-document references.

11.3 Commercial voice workflow

provider connection
  → voice asset import
  → rights verification
  → capability/quality test
  → profile approval
  → project casting
  → reservation/lease
  → usage metering
  → invoice/cost allocation
  → renewal, expiry, or takedown

A project cannot bind a voice asset unless the entitlement is active for the project, locale, territory, media, and release date. Expiry or takedown blocks new generation and creates an issue for existing deliverables; it does not erase historical usage or audit records.

11.4 Usage and financial reporting

Track usage by:

• organization, project, work, locale, speaker, and deliverable;
• voice asset and provider;
• character count, audio minutes, jobs, retries, and rerenders;
• rate-card version and currency;
• reservation and overage charges;
• pronunciation-review labor or service cost; and
• release/revenue attribution where applicable.

The dashboard can answer:

• Which voices are used by this project?
• Which locales lack an approved voice?
• Which assets expire before the planned release?
• What will the next rerender cost?
• Which pronunciation fixes affect the most clips?
• Which provider delivered the best quality/cost ratio for this locale?

11.5 Pronunciation catalog

The global pronunciation catalog is separate from voice catalog metadata:

pronunciation_entries
pronunciation_locale_forms
pronunciation_reviews
pronunciation_sources
pronunciation_overrides
pronunciation_usage
pronunciation_audio

An entry contains:

• stable term/entity ID;
• source spelling and locale;
• target reading, transliteration, IPA/phoneme, and stress/pitch information;
• language-specific context and part-of-speech/homograph rules;
• source and confidence;
• reviewer, approval state, and evidence;
• effective dates and supersession history; and
• rights/usage status for reference audio.

Projects may override a global pronunciation entry, but the override is explicit, versioned, reviewed, and linked to the exact target render spans and audio clips it affects. A pronunciation change invalidates only the affected translation/audio scope, not unrelated projects or languages.

12. Jobs, Resources, and Concurrency

The current in-process GenerationManager lock and JSON status files are not a distributed scheduler. They can remain local worker safeguards, but enterprise execution needs a durable queue and lease system.

12.1 Job types

Jobs are typed and resource-labeled:

• source_import;
• parse;
• semantic_analysis;
• identity_review;
• translation_draft;
• translation_verify;
• pronunciation_resolve;
• voice_cast;
• voice_sample_generate;
• audio_render;
• audio_qa;
• ebook_export;
• pdf_export;
• audio_assembly;
• release_package; and
• artifact_derivative.

12.2 Scheduler requirements

Every job has:

• organization/project/locale/revision scope;
• deterministic idempotency key;
• priority and deadline;
• required resource pool and capabilities;
• lease owner and heartbeat;
• retry and backoff policy;
• cancellation state;
• progress and structured logs; and
• output artifact and dependency hashes.

A worker claims a job with a lease. If the worker dies, the lease expires and another worker can resume safely. Jobs never use a filename alone as a global identity.

12.3 Resource pools

Resource pools include:

• CPU parsing/OCR;
• LLM analysis/translation;
• target TTS GPU;
• pronunciation/QA CPU/GPU;
• audio mixing/FFmpeg;
• object storage/export workers; and
• optional provider API workers.

Each pool has capacity, per-organization quotas, per-project concurrency, priorities, and cost limits. A project can run multiple independent language lanes while expensive TTS capacity is shared fairly. A model server that can serve one Mac is not treated as an unlimited multi-user service.

12.4 Optimistic concurrency

Metadata edits use a version number or ETag. Two reviewers cannot silently overwrite each other's changes. A conflict creates a review task or merge decision. Artifact uploads use idempotency keys and cannot overwrite an approved revision.

13. Service and API Boundaries

The first implementation may be a modular monolith, but the logical boundaries remain:

Identity/Tenant Service
Project/Work Service
Source and Analysis Service
Translation Service
Review Service
Voice/Pronunciation Catalog Service
Artifact Service
Job Scheduler
Billing/Entitlement Service
Notification Service
Reporting/Search Index

13.1 Project API

GET    /api/projects
POST   /api/projects
GET    /api/projects/{project_id}
GET    /api/projects/{project_id}/dashboard
GET    /api/projects/{project_id}/locales
POST   /api/projects/{project_id}/members
GET    /api/projects/{project_id}/audit

Every endpoint authorizes the subject against the organization and project. Project IDs are opaque UUIDs/ULIDs; slugs are display and routing conveniences only.

13.2 Artifact API

POST   /api/projects/{project_id}/artifacts/upload-sessions
POST   /api/artifacts/{artifact_id}/commit
GET    /api/artifacts/{artifact_id}
POST   /api/artifacts/{artifact_id}/download-url
GET    /api/artifacts/{artifact_id}/lineage
POST   /api/artifacts/{artifact_id}/supersede

Download URLs are short-lived, signed, audited, and scoped to the caller's permissions.

13.3 Voice catalog API

GET    /api/voice-assets
POST   /api/voice-assets
GET    /api/voice-assets/{voice_asset_id}/availability
GET    /api/voice-assets/{voice_asset_id}/rights
POST   /api/voice-assets/{voice_asset_id}/reserve
GET    /api/voice-assets/{voice_asset_id}/usage
POST   /api/voice-assets/{voice_asset_id}/takedown

13.4 Event and outbox contract

Domain events are written transactionally to an outbox and delivered asynchronously:

• project.created;
• source_revision.frozen;
• identity.review_required;
• translation.revision.created;
• pronunciation.changed;
• voice.license.expiring;
• audio.rebuild_requested;
• artifact.revision.created;
• issue.opened;
• approval.recorded; and
• release.published.

Consumers must be idempotent. Events carry IDs and revisions, not mutable filenames.

14. Web User Experience

The enterprise UI is project-centric but not project-cookie-centric.

14.1 Navigation

• Organization/workspace switcher.
• Authorized project list with search, status, and activity.
• Project dashboard.
• Source and analysis review.
• Locale matrix.
• Translation and proofing queues.
• Pronunciation review.
• Voice casting and license view.
• Audio build and listening review.
• Deliverables and release packages.
• Issues and audit timeline.
• Voice library and usage/billing for authorized operators.

14.2 Locale matrix

A project dashboard shows every target locale in one view:

• source revision;
• translation current/superseded revisions;
• proofing status;
• open issue count and age;
• pronunciation coverage;
• voice binding and license status;
• audio build progress and cost estimate;
• QA profile/result;
• deliverable versions;
• release state; and
• next responsible action.

14.3 Fix navigation

An issue links directly to:

• the exact source span;
• the scene and context packet;
• the target block/render span;
• the voice and pronunciation plan;
• the audio clip and chapter;
• the prior and new artifact revisions; and
• the approvals and audit events.

This is the primary audit/repair workflow for authors, editors, translators, audio staff, and release managers.

15. Deployment and Operations

15.1 Recommended production services

• FastAPI or equivalent control-plane API;
• PostgreSQL with managed backups and point-in-time recovery;
• S3-compatible encrypted object storage;
• Redis or a durable database-backed queue;
• CPU analysis workers;
• LLM workers;
• TTS/GPU workers;
• audio/export workers;
• search index for projects, terms, issues, and artifacts;
• notification/email service; and
• metrics, logs, traces, and alerting.

15.2 Local development

Local development may use:

• PostgreSQL in a container or managed local instance;
• MinIO or a local object-store emulator;
• Redis or a database queue;
• a single worker process for functional tests; and
• filesystem-backed artifact storage behind the same ArtifactStore interface.

The domain and API contracts must not depend on SQLite-specific behavior.

15.3 Availability and recovery

• Database backups and point-in-time recovery are tested.
• Object storage versioning and checksum validation are enabled.
• Jobs are resumable after worker loss.
• Release manifests survive service restarts.
• A project can be exported and re-imported without losing lineage.
• Deletion and retention policies are explicit.
• Voice license and pronunciation data are backed up independently of project files.

16. Migration from Current UmbraAudio

Migration is one-way and non-destructive.

Phase M0 — Inventory

Collect:

• every current project directory and source path;
• each project database and its schema/version;
• speakers.json, voice assignments, approved voice references, and markers;
• global voice registry and pronunciation/name library;
• generated audio and export files;
• pipeline/generation status and QA reports; and
• current source and output hashes.

Phase M1 — Import projects

For each current project:

1. create an organization or assign it to the appropriate organization;
2. create a work, project, and source asset;
3. copy the raw source into the enterprise artifact store;
4. create an immutable source revision and legacy source link;
5. import chapters, utterances, speaker hints, and attribution evidence;
6. mark all imported analysis as legacy_advisory until source review;
7. import generated English audio as legacy artifact revisions; and
8. record the exact UmbraAudio project path and database hash.

No current UmbraAudio file is moved, renamed, or rewritten.

Phase M2 — Import voice/name library

• Convert current registry speakers into logical voice profiles, not final commercial assets.
• Convert library names into pronunciation entries with legacy_source provenance.
• Preserve aliases, evidence, source project, and current confirmation state.
• Mark missing rights, locale, provider, and usage data as unknown.
• Require voice-manager review before a legacy voice can be used in a paid or public release.

Phase M3 — Validate lineage

For a sample of projects and artifacts, prove:

• source text can be found in the enterprise artifact store;
• speaker/utterance links resolve to stable IDs;
• audio artifacts link to the expected source/utterance revisions;
• checksums match;
• project membership can restrict access; and
• a regenerated translation/audio artifact can supersede the imported one.

Phase M4 — Dual operation

Run the current UmbraAudio English path and the enterprise target-language workers in parallel. The enterprise system records UmbraAudio output as an imported dependency and does not write into its database.

Phase M5 — Cutover per project

Only after validation, a project can be marked enterprise_active. Cutover is per project and per locale, not a global irreversible switch.

17. Implementation Roadmap

Phase E0 — Decisions and inventory

• Choose PostgreSQL and object-store providers.
• Define organizations, roles, retention, privacy, and deployment assumptions.
• Inventory current projects and voice/name libraries.
• Select artifact ID, project ID, revision, and idempotency conventions.

Phase E1 — Control-plane foundation

• PostgreSQL schema and migrations.
• Authentication and organization membership.
• Projects, project members, access grants, and RLS.
• Audit events and outbox events.
• Project picker and authorized project dashboard.

Phase E2 — Artifact and revision system

• Object store adapter.
• Immutable source, translation, audio, and deliverable revisions.
• Lineage graph.
• Signed download URLs.
• Fix/supersede workflow.

Phase E3 — Review and issues

• Locale matrix.
• Translation, source, pronunciation, voice, and audio review queues.
• Issue links to exact spans/clips/artifacts.
• Approval and audit timeline.

Phase E4 — Jobs and workers

• Durable queue, leases, retries, cancellation, and resource pools.
• Per-project quotas and concurrency.
• Worker dashboards and cost estimates.

Phase E5 — Voice and pronunciation catalog

• Voice assets, profiles, bindings, licenses, entitlements, rates, usage, and takedowns.
• Locale-aware pronunciation entries and review.
• Voice/pronunciation cost and expiry dashboards.

Phase E6 — Deliverables and releases

• EPUB/PDF/text exporters.
• M4B/MP3/WAV package manifests.
• Release sign-off and immutable release packages.
• Per-locale delivery tracking.

Phase E7 — Migration and hardening

• Import current projects and library.
• Cross-project reporting and search.
• Backup/restore, retention, legal hold, and disaster recovery.
• Security, concurrency, load, and cost testing.

18. Acceptance Criteria

The enterprise architecture is ready for multiple users when:

1. Two organizations with users in only one organization cannot discover or access the other's projects, artifacts, voices, or usage data.
2. A user with access to multiple projects can select among only those projects, and every request remains authorized after switching.
3. Two users editing the same translation revision receive an optimistic-lock conflict rather than silently overwriting each other.
4. Two projects can run independent jobs concurrently without sharing project status files, database rows, artifact paths, or review decisions.
5. Shared TTS/LLM resources are queued and metered rather than protected only by an in-process lock.
6. Every source, translation, render span, audio clip, deliverable, and release has a complete lineage path and content hash.
7. A fix creates a new revision and preserves the prior approved revision and audit trail.
8. Every target locale has independent translation, pronunciation, voice, audio, QA, and release status.
9. A voice or pronunciation change shows exactly which target spans and audio clips it invalidates.
10. An expired or revoked voice entitlement blocks new generation and creates a visible project issue.
11. Voice usage, rerenders, reservations, rates, and projected costs are visible by project and locale.
12. A release package contains only authorized, approved, non-superseded revisions.
13. A full backup/restore preserves project access, lineage, audit, and release state.
14. The current UmbraAudio project tree remains unchanged after import and enterprise operation.
15. The system passes concurrency, authorization, path-security, and provider-failure tests.

19. Open Decisions

1. Deployment: managed cloud, private cloud, or hybrid Mac/GPU workers.
2. Identity: preferred OIDC/SAML provider and service-account strategy.
3. Tenancy: one organization per author, one per studio, or explicit workspace nesting.
4. Commercial model: internal voices, licensed third-party voices, rented actors, or a hybrid catalog.
5. Billing: internal cost allocation, customer invoicing, or both.
6. Voice rights: territories, media, exclusivity, term, derivative rights, and takedown policy.
7. Pronunciation ownership: global catalog, per-customer overrides, or both.
8. Artifact retention: how long source, rejected revisions, audio, and audit data remain.
9. Review sampling: required qualified human review by locale and risk class.
10. Search: PostgreSQL full-text search initially or a separate search service later.

20. Summary

The current UmbraAudio repository is a capable local English audiobook engine with partial multi-project support, a shared basic voice registry, and a browser project selector. It is not yet a multi-user or enterprise system.

UmbraTrans needs a separate enterprise control plane with:

• organizations and authenticated users;
• authorized project membership and project selection;
• one logical relational schema, not tables per project or language;
• immutable source, translation, pronunciation, voice, audio, and deliverable revisions;
• object storage and complete lineage;
• durable jobs and resource quotas;
• review, issue, approval, and audit workflows;
• a licensed, metered, reusable voice library; and
• a global, locale-aware pronunciation library.

This structure lets one source ebook become multiple independently tracked ebooks, PDFs, and audiobooks in many languages while keeping the English source, people, permissions, commercial voice rights, costs, and every fix under one auditable control plane.