Shell App - Features & Capabilities Report

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

Table of Contents

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

Overview

Purpose

The Shell App is a terminal application for FlowState that provides a full-featured terminal experience with session persistence, context-aware sessions, and seamless integration with the FlowState ecosystem. It enables developers and power users to execute shell commands within FlowState while maintaining context association with projects, milestones, and tasks.

Target Users

Value Proposition

• Integrated Terminal: Full xterm.js terminal within FlowState
• Session Persistence: Sessions survive browser refreshes and reconnections
• Context Awareness: Link terminal sessions to projects, milestones, and tasks
• Multi-Session: Run multiple terminals simultaneously
• Bottom Panel Integration: Use as embedded panel in other apps
• Cross-Platform: Works in web browser and Electron desktop app

App Identity

Entry Points

Feature Categories

Category 1: Terminal Emulation

Core terminal functionality powered by xterm.js

Feature: xterm.js Terminal

Description: Full-featured terminal emulator using xterm.js with proper cursor handling, ANSI color support, and bidirectional I/O through WebSocket adapters.

User Story: As a developer, I want a real terminal in FlowState so that I can run commands without leaving the application.

Acceptance Criteria:

• [x] Full xterm.js terminal rendering
• [x] ANSI color and formatting support
• [x] Cursor positioning and movement
• [x] Input handling with proper key translation
• [x] Resize handling with terminal dimensions

Implementation:

Routes:

• /terminal - Full page terminal view

Category 2: Session Management

Create, manage, and persist terminal sessions

Feature: Session CRUD Operations

Description: Full session lifecycle management including creation with context, renaming, closing, and deletion with optional database removal.

User Story: As a user, I want to manage multiple terminal sessions so that I can organize my work by context.

Acceptance Criteria:

• [x] Create new sessions with display name
• [x] Associate sessions with org/workspace/project/milestone/task
• [x] Rename existing sessions
• [x] Close sessions (keep history for reconnection)
• [x] Delete sessions (remove from server and optionally database)
• [x] Session list with selection

Implementation:

Feature: Session Persistence

Description: Sessions are persisted to RxDB with full context metadata, enabling recovery after disconnection and cross-device access through replication.

User Story: As a user, I want my sessions to persist so that I can reconnect to them after refreshing or closing the browser.

Acceptance Criteria:

• [x] Save sessions to RxDB on creation
• [x] Load sessions from RxDB on startup
• [x] Sync sessions with shell server state
• [x] Update session metadata (rename, context) in database
• [x] Handle reconnection to existing sessions

Implementation:

Feature: Context-Aware Sessions

Description: Sessions can be linked to the FlowState entity hierarchy (Org > Workspace > Project > Milestone > Task) for organization and filtering.

User Story: As a project manager, I want to associate terminal sessions with tasks so that I can track what commands were run for each piece of work.

Acceptance Criteria:

• [x] Select workspace when creating session
• [x] Optionally select project, milestone, task
• [x] Display context breadcrumb in session form
• [x] Cascade-clear child selections when parent changes
• [x] Store context in both shell server and RxDB

Implementation:

Category 3: WebSocket Communication

Real-time bidirectional communication with shell server

Feature: Shell Server Connection

Description: WebSocket connection management with auto-connect, auto-reconnect, and connection status tracking.

User Story: As a user, I want reliable connection to the shell server so that my terminal sessions work consistently.

Acceptance Criteria:

• [x] Connect to shell server via WebSocket
• [x] Auto-connect on component mount
• [x] Auto-reconnect on disconnection
• [x] Display connection status
• [x] Manual connect/disconnect controls
• [x] Error handling and display

Implementation:

Feature: Message Protocol

Description: JSON-based message protocol for all shell operations including session management, data transfer, and session updates.

User Story: As a developer, I want a clear API for shell operations so that the terminal works reliably.

Acceptance Criteria:

• [x] Send: list, create, reconnect, data, resize, close, delete, rename, update
• [x] Receive: sessions, created, reconnected, data, exit, session_ended, renamed, session_deleted, session_updated, error
• [x] Handle all message types appropriately
• [x] Forward data to correct terminal instance

Implementation:

Category 4: UI Components

User interface for terminal and session management

Feature: Session List Sidebar

Description: Sidebar showing all terminal sessions with selection, status indicators, and context actions.

User Story: As a user, I want to see all my sessions so that I can switch between them easily.

Acceptance Criteria:

• [x] Display list of all sessions
• [x] Show session display name
• [x] Indicate selected session
• [x] Support session selection
• [x] Configurable sidebar width
• [x] Toggle sidebar visibility

Implementation:

Feature: Connection Status Display

Description: Visual indicators for server connection status with color-coded badges and retry options.

User Story: As a user, I want to know if I'm connected so that I understand why my terminal might not be responding.

Acceptance Criteria:

• [x] Status indicator (connected, connecting, disconnected, error)
• [x] Color-coded status (green, yellow, gray, red)
• [x] Connect button when disconnected
• [x] Retry button on error
• [x] Loading spinner during connection

Implementation:

Category 5: Plugin System

FlowState plugin integration

Feature: App Plugin Registration

Description: Plugin definition for registration with FlowState's HostContainer system, enabling lazy loading and lifecycle hooks.

User Story: As a FlowState developer, I want the shell app to integrate with the plugin system so that it loads efficiently.

Acceptance Criteria:

• [x] Plugin definition with id, name, version
• [x] Lazy component loading
• [x] Lifecycle hooks (onLoad, onUnload)
• [x] Route and basePath configuration
• [x] Icon and color metadata

Implementation:

Feature: Plugin Manifest

Description: Plugin manifest with contributions for commands, keybindings, toolbar items, and settings tabs.

User Story: As a user, I want terminal shortcuts and toolbar buttons so that I can work efficiently.

Acceptance Criteria:

• [x] Register terminal commands
• [x] Define keyboard shortcuts
• [x] Add bottom panel toolbar items
• [x] Configure settings tab

Implementation:

Category 6: Bottom Panel Integration

Integration with FlowState's bottom panel system

Feature: Terminal Panel Renderer

Description: Panel renderer component for embedding terminal in FlowState's bottom panel, used by other apps like ElectronShell and NextShell.

User Story: As a user, I want the terminal in a bottom panel so that I can see it alongside my main work.

Acceptance Criteria:

• [x] Panel renderer component for BottomPanel
• [x] Export panelRenderers map
• [x] Support dark/light color modes
• [x] Configurable session list width
• [x] Tab-based panel identification

Implementation:

Capabilities

Core Capabilities

Technical Capabilities

Integration Capabilities

Data Models

Collections Used

Entity Relationships

Session
    |
    +-- Org (belongsTo)
    |
    +-- Workspace (belongsTo)
    |
    +-- Project (belongsTo, optional)
    |       |
    |       +-- Milestone (belongsTo, optional)
    |               |
    |               +-- Task (belongsTo, optional)
    |
    +-- User (belongsTo)
    |
    +-- Codebase (belongsTo)

Session Model Fields

Key Data Flows

User Action --> Component --> Hook --> Shell Server --> Terminal Output
                                  |
                                  +--> RxDB (persistence)
                                  |
                                  +--> Replication --> Other Devices

User Workflows

Workflow 1: Create Terminal Session

Create a new terminal with project context

Trigger: Click "New Terminal" or press Ctrl+Shift+`

Steps:

Success Outcome: New terminal session connected and ready Failure Handling: Connection error shown with retry option

Workflow 2: Reconnect to Session

Reconnect to a disconnected session

Trigger: Click on disconnected session in list

Steps:

Success Outcome: Session reconnected with history restored Failure Handling: If session not found, creates new session with same context

Workflow 3: Delete Session

Permanently delete a terminal session

Trigger: Delete action on session

Steps:

Success Outcome: Session completely removed Failure Handling: Conflict errors ignored (already deleted)

State Transitions

Connection Status States

┌──────────────┐   connect    ┌────────────┐   open    ┌───────────┐
│ disconnected │─────────────▶│ connecting │─────────▶│ connected │
└──────────────┘              └────────────┘          └───────────┘
       ▲                            │                       │
       │                            │ error                 │ close
       │                            ▼                       │
       │                      ┌───────────┐                 │
       └──────────────────────│   error   │◀────────────────┘
         (auto-reconnect)     └───────────┘

Session Status States

┌───────────────┐   select   ┌────────────┐   data   ┌───────────┐
│  disconnected │───────────▶│ connecting │─────────▶│ connected │
└───────────────┘            └────────────┘          └───────────┘
       ▲                                                   │
       │                                                   │ exit
       └───────────────────────────────────────────────────┘

Integration Points

Internal Integrations

External Integrations

MCP Integration

Commands & Keybindings

Registered Commands

Keybindings

Toolbar Items

Architecture Summary

Directory Structure

src/
├── components/           # UI components
│   ├── IntegratedTerminalTab.tsx  # Main terminal with sessions
│   ├── TerminalPanelRenderer.tsx  # Bottom panel renderer
│   ├── SessionForm.tsx            # Session create/edit form
│   ├── ShellSidebar.tsx           # App navigation sidebar
│   └── ShellHeader.tsx            # Connection status header
├── hooks/                # Custom React hooks
│   ├── index.ts                   # Hook exports
│   ├── useShellServer.ts          # WebSocket connection
│   └── useTerminalSessions.ts     # Session management
├── pages/                # Page components
│   ├── TerminalPage.tsx           # Full page terminal
│   ├── SettingsPage.tsx           # Settings page
│   └── AboutPage.tsx              # About page
├── ShellApp.tsx          # Main app component
├── plugin.ts             # Plugin definition
├── manifest.ts           # Plugin manifest
├── bottomPanelRenderers.ts  # Panel renderer registry
├── index.ts              # Package exports
└── standalone.tsx        # Standalone entry

Key Architectural Patterns

Hooks Overview

Component Overview

Quality & Compliance

Test Coverage

Accessibility

Security Considerations

FlowState Alignment

Spec-Driven Development

This app follows the FlowState Standard for spec-driven development:

• Requirements: .flowstate/specs/{{feature-name}}/requirements.md
• Design: .flowstate/specs/{{feature-name}}/design.md
• Wireframes: .flowstate/specs/{{feature-name}}/wireframes.html
• Tasks: .flowstate/specs/{{feature-name}}/tasks.md

Quality Gates

Appendix

Related Documentation

Version History