- factory-studio
- platform
- clients
- sdk
- cli doc_status: target plane: experience platform: factory-studio
Factory Studio — clients and SDK¶
Target
This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.
Every client speaks the same contract: the BFF's /studio/screens/{screenId} compositions, /studio/commands/{commandId} forwarding with idempotency keys, the realtime gateway's streams, and sign-in through the identity platform (OpenIddict, PKCE for interactive clients, device flow for the CLI, client credentials for automation). No client reaches a platform API directly except through the public Control plane API (GW-03) when it acts as an integration rather than a user.
Clients¶
| Client | Built on | Authentication | What it adds |
|---|---|---|---|
| Web Studio | Blazor shell + microfrontends + ConnectSoft.Blazor.UIKit |
PKCE | the full work areas; realtime; notifications tray |
CLI (factory) |
.NET global tool over the SDK | device flow; client credentials for CI | scripting and watch modes; JSON output; the same commands as the screens |
| VS Code extension | TypeScript over the SDK's REST surface | PKCE through the editor's auth provider | run timeline panel; inline feedback on generated files; evaluation badges; proposal status in source control |
SDK (ConnectSoft.Factory.Sdk) |
typed client for BFF compositions, commands and streams; generated from the BFF's OpenAPI and the run-event envelope | any of the above | the one typed surface the CLI and extension use; third parties use the public API, not the SDK |
Command surface mirrors screens¶
| Screen (UX model) | CLI | VS Code |
|---|---|---|
| run-submit | factory run submit --workflow w --input file |
command palette: Submit run |
| run-detail / run-timeline | factory run show <id> --timeline --watch |
run timeline panel |
| approvals-list / approval-card | factory approvals list, factory approvals decide <id> --version v --approve |
notification → approval card webview |
| asset-catalog / release-detail | factory assets list --kind agent, factory assets release show <id> |
asset explorer |
| evaluation-runs | factory eval run --suite s --release r [--baseline b], factory eval verdict <releaseId> |
evaluation badge on asset |
| alerts | factory alerts list, factory alerts ack <id> |
status bar item |
| proposals / pipeline-runs / promotions | factory delivery … (see DevOps / GitOps UI) |
source-control decorations |
| fleet-board / rollouts / incidents | factory fleet … (see Fleet UI) |
— |
| governance screens | factory policy …, factory data …, factory capacity … |
— |
Rules for every client¶
- Idempotency keys on every command; the client shows the server's outcome and never retries silently.
- Exact-version approvals: a decision carries the proposal version it was shown; a stale version is a visible 412, not a retry.
- Usage figures by status; uncertain amounts are shown separately (FUX-08).
- Realtime resume from sequence; overflow refresh.
- Locale and RTL follow the user's preference in every client; the CLI emits locale-aware text only in interactive mode and always stable JSON in
--json.