# Screen and flow map

## Roles

| Role | Main job | Hub access | Fleet access |
|---|---|---|---|
| Customer employee | Open and use assigned applications | Home, news/status, documentation | None |
| Customer administrator | Keep the customer environment usable | Employee access plus requests, notifications, updates, deployment progress | None |
| RapidCloud operator | Keep customer environments healthy | Support-only, through the customer process | Fleet operations and customers |
| RapidCloud commercial/admin | Manage catalog, licenses, releases, and communication | None | Fleet commercial and authoring areas |

## Authentication and account journeys

Authentication has two visual layers. The product owns the branded entry,
return, error, session, and account-menu screens. Microsoft owns the hosted
credential, MFA, consent, and Conditional Access screens. The product must not
imitate Microsoft's password UI.

### Customer Hub access

`Customer-branded entry -> Microsoft Entra -> validated Hub session -> safe next route`

- The entry screen names the customer organization and explains that the next
  step takes place at Microsoft. Hub never asks for the Microsoft password.
- A successful login returns to a server-validated relative `next` route.
- An expired session explains what happened and preserves the intended route.
- Cancellation, invalid state, token-exchange failure, forbidden tenant/domain,
  and technical validation failure all return to designed HTML states. Browser
  users never receive raw authentication JSON.
- `Use another account` starts Entra with `prompt=select_account`.
- App-level logout ends only the Hub session. It does not sign the person out of
  Microsoft 365 and must say so clearly.
- The signed-in account menu contains identity, role, settings, account switch,
  and logout. Profile data is read-only and sourced from Entra.

HTTP Basic remains available only under `AUTH_MODE=dev`. Its dialog is rendered
by the browser and cannot be branded. Development hosts must be visibly labelled,
must never be shared as customer previews, and must not use customer-like host
names. Customer and acceptance deployments use `AUTH_MODE=entra`.

### Fleet operator access

`Fleet login -> RapidCloud portal SSO assertion -> operator allowlist -> Fleet session`

- RapidCloud SSO is the only prominent browser action.
- A valid portal identity without an operator role receives a designed access
  explanation and an audited access-request route.
- Password login is collapsed under `Emergency access`. It is break-glass only,
  rate-limited, audited on success and failure, and covered by an alert.
- HTTP Basic is retained for existing automation clients only. Interactive HTML
  requests always receive the Fleet login page rather than a native Basic popup.
- Fleet session expiry stops pending mutations and returns the operator to SSO.

### Required authentication states

| State | Hub response | Fleet response |
|---|---|---|
| First visit | Customer-branded Entra hand-off | RapidCloud SSO login |
| Existing valid session | Continue to requested route | Continue to requested route |
| Expired or invalid session | Explain expiry, preserve safe destination | Explain expiry, return to command center after SSO |
| Login cancelled | Calm retry/account-switch state | Return to Fleet login |
| Authenticated but forbidden | Account-specific no-access state | Operator-role-required state |
| Provider or validation fault | Retry, service status, support reference | Retry and support reference |
| Account switch | Microsoft account picker | RapidCloud portal account switch |
| Logout | Customer-specific signed-out state | Fleet signed-out state |
| Development Basic | Browser-owned, dev-labelled and isolated | Not used for browser journeys |

## Hub

### 1. Home — default for every user

- Organization-branded welcome and service-status summary.
- Important maintenance or service notice.
- `Your apps` cards with **Open app** as the primary action.
- App state: environment, health, installed version, latest version, and update
  availability.
- Role-aware secondary actions. Employees see documentation; administrators see
  `Manage` and update actions.
- Recent changes and upcoming maintenance.

### 2. App detail — customer administrators

- Product header, launch action, production state, and version comparison.
- Tabs: Overview, Updates, Documentation, Activity.
- Update card with release summary, compatibility/preflight state, and review
  action.
- Environment list without exposing secrets.
- Activity timeline for deployments and health transitions.

### 3. Discover apps

- Separate operational apps from products not yet licensed.
- Customer-facing product copy, capabilities, intended audience, dependencies,
  and availability.
- `Request app`, not `Buy`, until price and checkout are actually supported.
- Request state and expected next step.

### 4. Updates

- Queue of available, scheduled, running, failed, and completed updates.
- Review flow: release notes -> dependency/config validation -> Azure what-if ->
  confirmation -> progress -> health verification -> rollback if needed.

### 5. News & status

- Status incidents and maintenance are visually distinct from product news.
- Filters by type and app.
- Customer-admin notification preferences move to Settings.

### 6. Documentation

- Search and filter by app and document type.
- Rendered document previews for manuals, DPIA material, Entra setup, and release
  guidance instead of an unstructured link list.

### 7. Settings — customer administrators

- Notification recipients and per-recipient topics.
- Organization and support information.
- Hub/Fleet last-sync state.
- Read-only identity and deployment integration status.

## Fleet

### 1. Command center — operator default

- Urgent production exceptions first.
- Action queues for health, drift, failed deployment runs, open requests,
  expiring licenses, and failed communication.
- Counts drill into already-filtered views.
- Deployment list supports customer, app, environment, health, and update-state
  filters.

### 2. Customers

- Searchable customer directory with lifecycle, production health, open
  requests, and license summary.
- Customer detail tabs: Overview, Apps & licenses, Deployments, Requests,
  Connections, Communications, Audit.
- Contacts, Entra tenant, Hub token metadata, and notification coverage are
  visible without mixing them into create forms.

### 3. Applications

- Customer-facing catalog preview from the shared branding source.
- Operational metadata, documentation, release channels, dependencies, and
  customer adoption.
- Structured create/edit forms with validation.

### 4. Deployments

- Cross-customer health and drift view.
- Deployment detail includes heartbeat history, version/digest, alerts, and
  deployment-run timeline.
- Factory/test Azure stages are a separate labelled surface; they are not mixed
  with customer-reported production deployments.

### 5. Requests & licenses

- Work queue with request context, customer contacts, notes, decision history,
  and explicit approve/reject confirmation.
- License lifecycle has a timeline and expiry warnings.
- Operators select customers and apps by name; slugs remain secondary IDs.

### 6. Releases

- Draft, validate, preview, promote, and deprecate workflow.
- Rendered release notes, compatibility and gate evidence.
- JSON remains downloadable/inspectable but is no longer the primary authoring
  interface.

### 7. Communications

- Draft, audience, preview, schedule, publish, and delivery state.
- Per-customer and per-app targeting.
- Retry and delivery failure visibility.

### 8. Audit & settings

- Searchable audit trail.
- Hub token issue, rotate, revoke, age, and last-used state.
- Alert routing and policy.

## Core flows

### Open an application

`Hub Home -> Open app -> customer application URL`

The launch URL must work from the last-good Hub cache when Fleet is unavailable.

### Sign in and return

`Requested Hub route -> branded access screen -> Entra -> callback validation -> requested route`

Only allowlisted relative routes can be stored as `next`; external redirect
targets and arbitrary paths fall back to Hub Home.

### Switch account or sign out

`Account menu -> switch account -> end Hub session -> Entra account picker`

`Account menu -> sign out -> end Hub session -> branded signed-out screen`

### Request an application

`Discover -> App detail -> Request -> confirmation -> Fleet request queue -> decision -> Hub state refresh`

### Update an application

`App detail -> Review update -> preflight -> what-if -> confirm -> customer-side pipeline -> progress callbacks -> heartbeat verification -> complete/rollback`

### Triage an incident

`Fleet command center -> production exception -> deployment detail -> history/owner -> customer contact or approved recovery action -> audit entry`

## State vocabulary

| Domain | States shown to people |
|---|---|
| Health | Healthy, Attention needed, Stale, Unavailable, Unknown |
| Update | Up to date, Update available, Scheduled, Updating, Verification failed, Rolled back |
| Request | Not requested, Requested, Under review, Approved, Rejected |
| License | Draft, Pending, Active, Expiring, Expired, Cancelled |
| Deployment run | Validating, Ready, Awaiting confirmation, Deploying, Verifying, Succeeded, Failed, Rolling back, Rolled back |

Internal values can remain stable for compatibility, but the interface must use
one consistent language and human-readable labels.