FlowFuse / FlowFuse/flowfuse

Inform user of waiting period after Instance creation

Open
#5,772 5 comments 0 reactions 1 assignee Claimed by @dimitrieh View on GitHub
design growth story
Dominant language
JavaScript
Stars
400
Forks
89
Avg merge
1d 21h
Merged PRs (30d)
146

Description

## The Problem

**As a FlowFuse user who has just created a new Instance, I want a visual signal that my Instance is being created, so that I know everything is working correctly.**

The subject of delayed Instance creation comes up occasionally. What is sometimes not recognized is that delayed instance creation can lead to the user's confusion: thinking that the instance they intended to create isn't working or that something went wrong.

Here is an example where it appears that a user is confused about what has happened with the instance they've attempted to create from a Blueprint. The user is brought to the screen for the new instance and starts clicking around everywhere. A plausible explanation is that it's because they don't immediately see anything that signals to them that the instance is being created, and everything is fine.

https://eu.posthog.com/project/2209/replay/0197d79d-2df9-740e-acb7-a5aaa5ec7ea9?t=398

### Current User Journey

| Step | What User Sees | Duration | UX Issue |
|------|---------------|----------|---------|
| 1. Select Blueprint | Blueprint grid, click tile | ~10s | ✅ Clear |
| 2. Fill Form | App → Instance name → Config | 30s-2min | ✅ Clear |
| 3. Click "Create Instance" | Loading overlay: "Creating a new Instance" | 2-5s | ⚠️ Generic message |
| 4. Redirect | Lands on Instance Overview | Immediate | - |
| 5. Instance Overview | Status badge: `installing` (spinner icon) | 30s-2min | ❌ **Problem Zone** |
| 6. Status: Starting | Badge changes to `starting` (spinner icon) | 10-30s | ❌ **Problem Zone** |
| 7. Running | Green badge, Editor link active | - | ✅ Clear |

Details

### What could be better?

When the user lands on the Instance Overview page after creating an instance, they see:
- **Status badge** showing `installing` or `starting` with a spinner icon
- **Editor URL** showing "Unavailable"
- **"Last Updated"** showing "flows never deployed"
- **No explanation** of what's happening or how long to wait
- **No visible progress** beyond the spinning icon

Most of the Overview page content is designed for a *running* instance. During startup, it displays confusing states:
- "Unavailable" suggests something is broken
- "flows never deployed" looks like an error
- Security/Maintenance/HA settings aren't relevant yet

**Result**: Users don't understand if they should wait, refresh, or troubleshoot. They start clicking around trying to figure out what's wrong (see PostHog example above).

**Total time from "Create Instance" to editor ready**: 45 seconds to 5+ minutes
- Most of this happens asynchronously in the background
- Users see minimal feedback via status badge updates (polled every 1-2s)


## Solution

### Dedicated Startup View

When instance state is `loading`, `installing`, or `starting`, **replace the Instance Overview content** with a dedicated startup view.

#### Components of Startup View

Image

#### UX details

UX details

### 1. Progress Bar (Top)
- **Visual**: Full-width progress bar with percentage
- **States & Progress**:
- `loading` = 25% → "Loading Instance..."
- `installing` = 50% → "Installing packages..."
- `starting` = 75% → "Starting Node-RED..."
- `running` = 100% → Auto-transition to Overview

### 2. Live Log Stream (Left Panel)
- **Data Source**: Poll `/api/v1/projects/:id/logs` endpoint
- **Polling Frequency**: Every 1-2 seconds (faster than current Logs page 5s interval)
- **Display Format**:
- Timestamped entries: `[HH:MM:SS AM/PM] Log message`
- Log levels indicated by color (error=red, warning=yellow, info=default)
- Auto-scroll to show latest entries
- Show real launcher output (unfiltered)
- **Content Examples**:
- "Instance Created"
- "Downloading container image"
- "Setting up environment variables"
- "Starting Node.js 22.21.1"
- "Loading Node-RED"
- "Configuring Node-RED"
- "Installing custom nodes..." (if applicable)
- "Deploying flows..." (if from Blueprint)

### 3. Recent Activity (Right Sidebar)
- **Data Source**: Audit log entries (existing component)
- **Purpose**:
- Shows high-level milestones
- Helps diagnose errors if startup fails
- **Display**: List of audit events with timestamps

### 4. Auto-Transition to Overview
- **Trigger**: When `instance.meta.state` changes to `running`
- **Behavior**: Fade out startup view → Show normal Instance Overview
- **Timing**: Handled by existing `InstanceStatusPolling` component


#### Technical Implementation Details

Technical Implementation Details

### Data Sources Available

| Data | Endpoint/Source | Update Frequency | Contains |
|------|----------------|------------------|----------|
| **Instance State** | `/api/v1/projects/:id` | Polled 1-2s (exponential backoff) | `meta.state`: loading/installing/starting/running |
| **Launcher Logs** | `/api/v1/projects/:id/logs` | Poll every 1-2s | Timestamped log entries with level and message |
| **Audit Events** | Audit log query | On change | High-level events: created, started, failed |
| **In-flight State** | Instance meta | Via polling | Current operation: starting/stopping/restarting |

### Existing Components to Leverage

- **`InstanceStatusPolling.vue`** - Already polls instance state with exponential backoff (1s → 1.15s → 1.32s...)
- **`InstanceLogs.vue`** - Already fetches and displays launcher logs (currently polls at 5s)
- **Audit log display** - Already shown in Overview "Recent Activity" section

### Implementation Files

| File | Change Type | Purpose |
|------|-------------|---------|
| `frontend/src/pages/instance/Overview.vue` | Modify | Add conditional rendering for startup view |
| `frontend/src/pages/instance/components/InstanceStartupView.vue` | New | Dedicated startup view component |
| `frontend/src/pages/instance/components/InstanceLogs.vue` | Reference | Reuse log fetching logic |
| `frontend/src/components/InstanceStatusPolling.vue` | Reference | Existing state polling (no change needed) |

---

## Acceptance Criteria

- [ ] When instance state is `loading`, `installing`, or `starting`, the Instance Overview page shows a dedicated startup view instead of regular Overview content
- [ ] Progress bar displays with appropriate percentage based on current state (25%, 50%, 75%)
- [ ] Progress bar shows descriptive status text: "Loading Instance...", "Installing packages...", "Starting Node-RED..."
- [ ] Live log stream displays real launcher logs with timestamps
- [ ] Logs auto-scroll to show the latest entries
- [ ] Logs poll every 1-2 seconds during startup states
- [ ] Recent Activity sidebar shows audit log entries
- [ ] When instance reaches `running` state, the view automatically transitions to normal Instance Overview
- [ ] If instance enters `error` or `crashed` state during startup, the logs help diagnose what went wrong

---

## Design References

Related issues:
- FlowFuse/flowfuse#6063 - Performance Tab feedback improvements (similar state-specific messaging pattern)
- FlowFuse/flowfuse#5844 - Design task (closed in favor of this issue)

Mockup reference:
- See `mockups-6063/` directory for visual reference of progress bar + log stream layout

### Which customers would this be available to

None

### Have you provided an initial effort estimate for this issue?

I have provided an initial effort estimate

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.