docs/reviews/platform-experience-routes.md

Rama main · réplica de lectura del repositorio original.

# Platform form and route inventory

Read-only source inventory from public commit `85e07e0` and the Cloud overlay. Counts describe route modules, not distinct runtime states. Public has 75 TSX route modules plus two nonvisual handlers (`api.$.ts`, `session.ts`). Cloud adds 14 overlay route modules: 11 visual workspace/account routes, two API proxies, and a nonvisual health handler.

## First visual priorities

1. **Application creation and configuration** — `/applications/new`, `/applications/:id/configure`, and `/applications/:id/services/new` converge on `DeploymentForm`. The form combines entry-mode selection, application policy, every service, conditional runtime type, resources, environment rows, files, review, secrets, and deployment. In a multi-service application all service editors are expanded in one document, so the user must repeatedly parse the same long field sequence.
2. **Add service** — `/applications/:id/services/new` presents catalog/Compose, HTTP function, and container-image creation as three equally prominent paths before handing the draft to the full deployment form. The route contains two forms and multiple availability/collision branches; progressive choice is weak.
3. **Service update** — `/applications/:id/configure?service=` still uses the same broad editor as whole-application configuration. Runtime type, image/function, command, registry, port, size, replicas, custom resources, environment, exposure, recovery, and review compete even when the user intends one small edit.
4. **Environment variables and secrets** — `/applications/:id/environment?service=` is safer because it has a dedicated review, conflict merge, and preserved draft. `EnvironmentFields` is still a dense row editor with name/value, show/hide, secret conversion, delete, dotenv paste/import, inherited application values, and shared-secret impact.
5. **Build creation/edit** — `BuildForm` is the next largest wizard: repository/provider, revision/context, build method-specific fields, runtime service, environment, registry, resources, paths, triggers, and review.

## Public route families

| Family | Paths and create/edit variants | Primary form components and branches | Main cognitive-load risk |
| --- | --- | --- | --- |
| Applications | `/`, `/projects/:project`, `/applications/new`, `/applications/import`, `/applications/:id`, `/applications/:id/configure`, `/applications/:id/services/new`, `/applications/:id/environment`, `/applications/:id/domains`, `/applications/:id/certificates`, `/applications/:id/notifications`, `/applications/:id/source`, `/applications/:id/previews/new` | `DeploymentForm`, `ComposeImport`, `ServiceEnvironmentForm`, `BackendCertificateForm`, TLS/domain/notification forms. New app modes: guided image, TOML, Compose, repository redirect. Configure variants: whole app, one service, remove service, runner pool, all-runner selector. Add-service variants: template, Compose, JS/Python function, new/reused image. | Several entry routes funnel into one editor without a task-level summary. Multi-service editing multiplies long service sections. Mode switching requires server conversion and makes information architecture harder to predict. |
| Deployment form internals | Nested within create/configure/add-service | Application name and recovery; per-service image or function source; service name; registry credential; commands/args; port; size; replicas; architecture/node/runtime fields; four custom resource values; environment and secrets; public exposure; environment files; TOML editor; Compose conversion; plan diff; missing secrets; deploy. Conditional types include ordinary HTTP/private workers, scheduled/one-shot jobs, serverless HTTP functions, and Managed Actions (guided runner form or TOML-only provider settings). | More than four inputs per service and repeated sections for every service. Basic and advanced settings lack a stable step model; destructive/remove affordances coexist with routine edits. Review occurs only after a long page. |
| Catalog/templates | `/templates`, `/templates/:templateId`; create app or add to existing app | `TemplateForm`; generic config fields plus conditional public access, storage, architecture, site URL, database name/user, Open WebUI provider/model/URL, vLLM model/revision/token, required secrets, plan and deploy. | Template-specific branches change the shape after selection; generic fields, requirements, compute eligibility, and secret resolution can make one page feel unpredictable. |
| Builds | `/builds`, `/builds/new`, `/builds/:id`, `/builds/:id/edit` | `BuildForm`; new/edit and multi-step review. Git provider/repository/service/revision/context, build method (Dockerfile/buildpack/static), preset/architecture/build args, runtime command/image/registry/resources/environment, trigger and path rules, plan review. | One of the largest forms; source, build, runtime, and automation are separate mental models shown in one workflow. Conditional fields materially reflow the page. |
| Deployments and requests | `/deployments/:id`, `/requests` | Read/inspect, retry/cancel/approval actions and logs/events rather than creation forms. | Dense status/event data and consequential actions; should not inherit form density patterns. |
| Environment and secrets | Application/service environment route plus service `environment` and `secrets` tabs | `ServiceEnvironmentForm`, `EnvironmentFields`, `ApplicationSecrets`, `ServiceSecrets`, `DeploymentSecrets`. Plain/secret rows, dotenv import/paste, inherited values, secret references, plan/conflict/retry states. | Repeated row controls, hidden values, inheritance, and shared-secret scope make scanning and consequence prediction difficult. |
| Databases | `/databases`, `/databases/new`, `/databases/import`, `/databases/:id`, `/databases/:id/connect`, `/databases/:id/recover`, `/databases/:id/resize` | `DatabaseForm`, import form, connection/credential view, recovery and resize confirmations. Engine/version/layout, replicas/resources/storage/network/name, credentials, backup source/point-in-time branches. | Create/import/recover each expose infrastructure consequences; import is especially field-heavy (source, TLS, credentials, network and verification). |
| Backups | `/backups`, `/backups/new`, `/backups/:jobId`, `/backups/destinations/new`, `/backups/destinations/:id/edit`, `/backups/schedules/new`, `/backups/schedules/:id/edit`, `/backups/artifacts/:id/restore` | `BackupRunForm`, `BackupDestinationForm`, `BackupScheduleForm`, restore form. Destination branches include S3-compatible details, credentials/encryption/recovery key; schedules combine database, destination, interval in hours, retained-backup count; restore selects target and confirmation. | Destination setup is long and security-sensitive; create/edit/recovery-key states differ. Schedule and restore need clearer consequence summaries. |
| Networks | `/networks`, `/networks/new`, `/networks/:name`, `/networks/:name/connect` | `VirtualNetworkForm`, `VirtualNetworkConnect`; create/edit/delete/connect with project/environment/application/service and address/policy branches. | Scope selection and connection consequences are distributed across catalog, detail, and connect pages. |
| Alarms | `/alarms`, `/alarms/settings`; application notification route | Alarm filters/list plus rule/channel configuration and application notification settings. | Rule conditions, destinations, evaluation timing, and application scope create many compact controls; current route-level JSX has 9 direct controls in settings. |
| Infrastructure | `/infrastructure`, `/infrastructure/registries/new`, `/infrastructure/registries/:name`, `/infrastructure/nodes/:node/terminal` | Node controls/enrollment, `RegistryForm`, terminal, installation updates. Registry create/rotate includes identity and authentication; node operations have confirmation and runtime state. | Admin-only operations mix monitoring with mutation. Credential rotation and node actions require strong separation and review. |
| DNS, TLS and edge | `/settings/dns-providers`, `/settings/dns-providers/new`, `/settings/dns-providers/:name/edit`, `/settings/edge`, application domains/certificates | `DNSProviderEditor`, `DNSProviderCredentialFields`, `ServiceTLS`, issuer forms, `ProxyEditor`, `EdgePolicyFields`. Provider-specific credentials, permitted zones, availability scopes; certificate method/issuer/domain/source; HAProxy text plus structured traffic rules. | Provider-specific credentials and scope are long. Edge rules are a repeatable sub-form with ordering controls. Raw and structured configuration coexist. |
| Git and integrations | `/settings/integrations`, `/settings/integrations/:provider`, `/settings/git/connections/new`, `/settings/git/connections/:id`, GitHub/GitLab callback routes | `GitConnections`, `GitHubAppSetup`, OAuth/callback flows, provider integration editors. | External setup state, callback values, permissions, capability flags and credentials are split across redirects and local forms. |
| Identity and settings | `/settings`, `/settings/profile`, `/settings/host-access`, `/settings/login-providers/:provider`, `/settings/roles/new`, `/settings/roles/:role/edit`, `/settings/secret-providers`, `/settings/secret-providers/new`, `/settings/secret-providers/:name/edit`, `/settings/smtp` | Account/appearance/license/team/installation settings; role editor; secret-provider form with provider-specific source/credential/scope/review; SMTP delivery/server/security/auth; login-provider enablement and credentials; host access. | Many admin forms exceed four fields. Settings navigation hides substantial nested workflows; provider-specific forms change shape and frequently contain secrets. |
| Authentication | `/login/signup`, `/login/forgot`, `/login/reset`, `/login/verify`, `/login/invite`, `/login/device`, `/login/onboarding` | `AuthScreen` variants and installation onboarding. | Mostly focused forms, but invite/onboarding/provider/device branches need mobile and error-state coverage. |

## Cloud-only overlay

Cloud inherits every public engine route through composition, then adds 11 visual routes: `/workspaces`, `/workspaces/plans`, `/workspaces/team-access`, `/workspaces/:workspace`, `/workspaces/:workspace/team`, `/workspaces/:workspace/waitlist`, `/workspaces/:workspace/approvals`, `/workspaces/:workspace/approvals/:approval`, `/workspaces/:workspace/roles/new`, `/workspaces/:workspace/roles/:role/edit`, and `/invite`. The remaining nonvisual overlay modules are `/api/node/$` and `/cloud-api/$` proxies, plus `/healthz`.

Key components are `CloudOnboarding`, `HostedCompute`, `WorkspaceCompute`, `CloudCollaboration`, and `NodeEnrollment`. Branches cover workspace creation/naming, personal versus team access, plan selection, hosted versus own-server compute, region/size/capacity, node enrollment, waitlist, approvals, invitations, members and custom roles. The main risk is that account, billing, workspace identity, compute allocation, and collaboration are shown as neighboring settings even though they have different ownership and consequence levels. Cloud review must also verify the composed engine forms, because the overlay does not replace the public application/service editors.

## Existing fixture harness assets

The current managed worktree does not contain the old ignored global harness, but the primary checkout does. It can be copied or adapted into a new ignored harness without changing product source.

- `work/ui-migration/global-review/`: full application router harness with `main.tsx`, `review.mjs`, `edge.mjs`, `help*.mjs`, `probe.mjs`, `routes.json`, proxy fixtures and 65-case historic screenshots. Existing route map includes application new/import/configure/environment/source/detail and broad settings/infrastructure families.
- `work/ui-migration/operations-fixture/`: strongest reusable API fixture for the named flows. It already has application/service records, environment conflict and failed-plan/deploy states, service secrets/shared-secret states, template add/review states, TOML expanded states, network and project states, plus `main.tsx`, `server.mjs`, QA scripts and proxy/template fixtures.
- `work/ui-migration/dashboard-fixture/`: application and service catalog layouts, environment failure retention, required-select validation and keyboard/layout scripts.
- `work/ui-migration/build-fixture/`: dedicated build create/edit/review fixture and server.
- `work/ui-migration/page-inset-review/`, `project-review/`, `alarms-review/`, `git-provider-review/`, `smtp-readiness-review/`, and `public-tcp-policy-review/`: narrower route/API fixtures useful for settings and policy branches.

The old `global-review/routes.json` predates several current routes: services/new, previews/new, notifications, certificates, alarms, databases, DNS providers, secret providers, SMTP, roles and Cloud workspaces. A new platform harness should extend the route map rather than treating the old 65 cases as current coverage. Fixture screenshots are development evidence only and must remain explicitly labeled artificial.

## Audit-state matrix required next

For each mutating form, render create, edit with saved values, validation error, backend failure with draft retention, review/confirmation, permission denied, loading and unavailable dependencies. Check Ink and Paper themes, 1440/390/320 widths, keyboard focus order, touch disclosure behavior, real element bounds and long values. For repeatable rows, include empty, one row, many rows, long names/values, secret-hidden and inherited/shared states. For conditional forms, capture every branch listed above rather than only the default selection.