Launcher App - Features & Capabilities Report

Template Version: 1.0.0 Generated: 2026-01-22 Package: @epicdm/flowstate-app-launcher App ID: launcher

Table of Contents

1. Overview
2. App Identity
3. Feature Categories
4. Capabilities
5. Data Models
6. Integration Points
7. Commands & Keybindings
8. Architecture Summary

Overview

Purpose

The Launcher App serves as the central navigation hub and home screen for FlowState. It provides a visual dashboard for discovering and accessing all registered applications, displaying server status, and managing organization/workspace context.

Target Users

Value Proposition

• Single Entry Point: One dashboard to access all FlowState apps
• Dynamic Discovery: Apps automatically appear when registered
• Context Awareness: Always shows current org, workspace, and server status
• Cross-Platform: Consistent experience across Electron, Web, and Mobile

App Identity

Entry Points

Feature Categories

Category 1: Application Navigation

Core app discovery and navigation

Feature: App Grid Display

Description: Displays all registered FlowState applications in a responsive grid layout with visual cards showing app icon, name, and description.

User Story: As a user, I want to see all available apps so that I can quickly navigate to the one I need.

Acceptance Criteria:

• [x] Display apps in responsive grid layout
• [x] Show app icon with branded color
• [x] Show app name and description
• [x] Hover effects for interactivity
• [x] Click to navigate to app route

Implementation:

Routes:

• / - Launcher dashboard

Feature: Dynamic App Discovery

Description: Automatically discovers and displays apps from their registered manifests using the useRegisteredApps hook from the framework.

User Story: As a developer, I want apps to automatically appear in the launcher so that I don't need to manually configure the launcher for each new app.

Acceptance Criteria:

• [x] Load apps from registered manifests
• [x] Convert icon names to Lucide components
• [x] Support custom apps via props
• [x] Fallback to Box icon for unknown icons

Implementation:

Category 2: Context Management

Organization and workspace awareness

Feature: Status Bar

Description: Displays current system status including connection mode, active server count, and current organization.

User Story: As a user, I want to see my current context so that I know which organization and environment I'm working in.

Acceptance Criteria:

• [x] Show connection mode (local/remote)
• [x] Show active server count
• [x] Show current organization name
• [x] Styled status bar at top of dashboard

Implementation:

Feature: Organization/Workspace Selection

Description: Provides organization and workspace selector for switching context, using the OrgWorkspaceSelector component from the framework.

User Story: As a user, I want to switch between organizations and workspaces so that I can access different contexts.

Acceptance Criteria:

• [x] Display current organization
• [x] Allow organization switching
• [x] Allow workspace switching
• [x] Persist selection

Implementation:

Category 3: Platform Support

Cross-platform compatibility

Feature: Multi-Platform Support

Description: The launcher works across multiple platforms including Electron (desktop), Web (Next.js), and React Native (with navigation adapter).

User Story: As a user, I want the launcher to work the same way regardless of platform so that I have a consistent experience.

Acceptance Criteria:

• [x] Works in Electron desktop app
• [x] Works in Next.js web app
• [x] Compatible with React Native (requires navigation adapter)
• [x] Uses react-router-dom for navigation

Implementation:

Capabilities

Core Capabilities

Technical Capabilities

Data Models

Types

AppDefinition

interface AppDefinition {
  id: string;
  name: string;
  description: string;
  icon: LucideIcon;
  route: string;
  color: string;
  category: 'technical' | 'business';
  requiresServer: boolean;
}

LauncherAppProps

interface LauncherAppProps {
  /** Apps to display. If not provided, uses useRegisteredApps() from manifests */
  apps?: AppDefinition[];
  onAppSelect?: (appId: string) => void;
}

Data Flow

App Manifests (flowstate.json) --> useRegisteredApps() --> useManifestApps() --> LauncherApp
                                                                                      |
                                                                                      v
                                                                                  AppCard Grid
                                                                                      |
                                                                                      v
                                                                        User Click --> navigate()

Integration Points

Internal Integrations

Framework Hooks Used

Framework Components Used

Commands & Keybindings

Registered Commands

Keybindings

Architecture Summary

Directory Structure

src/
├── index.ts           # Package exports
├── LauncherApp.tsx    # Main component with AppCard
└── types.ts           # TypeScript type definitions

Key Architectural Patterns

Component Hierarchy

LauncherApp
├── Status Bar (inline)
├── Header (inline)
├── OrgWorkspaceSelector (from framework)
└── App Grid
    └── AppCard (multiple)
        └── Lucide Icon (dynamic)

Build Configuration

Quality & Compliance

Test Coverage

Accessibility

Appendix

Related Documentation

Version History