Servers App - Features & Capabilities Report

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

Table of Contents

1. Overview
2. App Identity
3. Feature Categories
4. Data Models
5. User Workflows
6. Commands & Keybindings
7. Architecture Summary

Overview

Purpose

The Servers App provides centralized management for RxDB server configurations used across all FlowState applications. It enables users to add, configure, and authenticate with multiple servers, supporting development, staging, and production environments with seamless switching between them.

Target Users

Value Proposition

• Centralized Configuration: Single place to manage all server connections
• Multi-Server Support: Easy switching between development, staging, and production
• Secure Authentication: Email verification flow with JWT token storage
• Connection Validation: Test connections before activating servers
• Visual Status: Clear indicators for active and authenticated states

App Identity

Entry Points

Feature Categories

Category 1: Server Configuration Management

Core CRUD operations for server configurations

Feature: Server CRUD Operations

Description: Create, view, edit, and delete RxDB server configurations with comprehensive settings including URL, database name, domain ID, and authentication tokens.

User Story: As a developer, I want to manage server configurations so that I can connect FlowState apps to different RxDB servers.

Acceptance Criteria:

• [x] Create servers with name, URL, database name, domain ID
• [x] View servers in a table with status indicators
• [x] Edit existing server configurations
• [x] Delete server configurations (with confirmation)
• [x] Default configuration pre-filled for new servers

Implementation:

Routes:

• / - Server list with CRUD operations

Feature: Active Server Selection

Description: Set one server as the active server for replication. The active server is used by all FlowState apps for data synchronization.

User Story: As a user, I want to set an active server so that my data syncs with the correct backend.

Acceptance Criteria:

• [x] Set any configured server as active
• [x] Visual indicator (star icon) for active server
• [x] Status badge showing active/inactive state
• [x] Cannot delete the currently active server

Implementation:

Feature: Connection Testing

Description: Test server connectivity before saving or activating a server configuration.

User Story: As a developer, I want to test server connections so that I can verify my configuration is correct.

Acceptance Criteria:

• [x] Test connection button in server dialog
• [x] Success/failure feedback
• [x] Connection test before save

Implementation:

Category 2: Authentication

Server authentication and token management

Feature: Email Verification Login

Description: Authenticate with a server using email verification. A verification code is sent to the user's email, which is then entered to complete authentication.

User Story: As a user, I want to authenticate with a server so that I can sync my data securely.

Acceptance Criteria:

• [x] Navigate to server-specific login page
• [x] Enter email address
• [x] Receive verification code via email
• [x] Enter code to complete authentication
• [x] Store JWT token in server configuration

Implementation:

Routes:

• /login/:serverName - Server-specific login page

Feature: Token Management

Description: Manage authentication tokens including storage, refresh, and logout functionality.

User Story: As a user, I want my authentication to persist so that I don't have to log in repeatedly.

Acceptance Criteria:

• [x] Store auth token in server configuration
• [x] Auto-refresh tokens when expired
• [x] Logout button to clear authentication
• [x] Visual indicator for authenticated state

Implementation:

Category 3: User Interface

Visual components and user experience

Feature: Server List Table

Description: Tabular display of all configured servers with columns for name, URL, database, auth status, and actions.

User Story: As a user, I want to see all my servers in a clear list so that I can manage them easily.

Acceptance Criteria:

• [x] Table with sortable columns
• [x] Server name with active indicator
• [x] Truncated URL display
• [x] Database name column
• [x] Auth status with login/logout buttons
• [x] Action buttons (edit, delete, set active)

Implementation:

Feature: Empty State

Description: Helpful empty state when no servers are configured, guiding users to add their first server.

User Story: As a new user, I want guidance when no servers exist so that I know how to get started.

Acceptance Criteria:

• [x] Friendly empty state message
• [x] Add server button prominently displayed
• [x] Default configuration mention

Implementation:

Feature: Status Bar

Description: Status bar showing current mode, server count, and organization context.

User Story: As a user, I want to see system status so that I understand my current context.

Acceptance Criteria:

• [x] Display current mode (local/server)
• [x] Display server count
• [x] Display current organization

Implementation:

Feature: Delete Confirmation

Description: Confirmation dialog before deleting a server configuration to prevent accidental deletion.

User Story: As a user, I want confirmation before deleting so that I don't accidentally remove servers.

Acceptance Criteria:

• [x] Modal dialog with server name
• [x] Cancel and confirm buttons
• [x] Loading state during deletion

Implementation:

Data Models

Server Configuration

The app manages ServerConfig objects with the following structure:

Default Configuration

const DEFAULT_SERVER_CONFIG = {
  name: 'flowstate-dev',
  url: 'https://localhost:7443',
  databaseName: 'flowstate-dev',
  domainId: 'flowstate-dev',
  replicationEnabled: true,
};

Data Flow

User Action --> ServersPage --> useServerConfig --> ServerConfigService --> Storage
                    |
                    +--> LoginPage --> FlowstateAuthProvider --> Auth Server
                                              |
                                              +--> updateServer (token storage)

User Workflows

Workflow 1: Add New Server

Configure a new RxDB server connection

Trigger: Click "Add Server" button

Steps:

Success Outcome: New server configuration saved and ready for use Failure Handling: Validation errors shown, form state preserved

Workflow 2: Authenticate with Server

Log in to a server for data synchronization

Trigger: Click "Login" button on a server row

Steps:

Success Outcome: Server shows "Authenticated" status, replication enabled Failure Handling: Error message shown, can retry

Workflow 3: Switch Active Server

Change which server is used for replication

Trigger: Click "Set Active" on an inactive server

Steps:

Success Outcome: New server is active, replication switches to it Failure Handling: Connection test before activation (if configured)

Workflow 4: Edit Server Configuration

Modify an existing server's settings

Trigger: Click edit (pencil) icon on a server row

Steps:

Success Outcome: Server configuration updated Failure Handling: Validation errors shown

Commands & Keybindings

Registered Commands

Keybindings

Menu Contributions

Architecture Summary

Directory Structure

src/
├── index.ts           # Package exports
├── ServersApp.tsx     # Main app component with routing
├── plugin.ts          # FlowState plugin registration
├── types.ts           # Type re-exports
└── pages/
    ├── ServersPage.tsx  # Server list and management
    └── LoginPage.tsx    # Authentication flow

Key Architectural Patterns

Framework Dependencies

Component Hierarchy

ServersApp
├── FlowstateAppContainer
│   └── ServersAppContent
│       ├── StatusBar
│       └── Routes
│           ├── ServersPage (/)
│           │   ├── LoadingSkeleton
│           │   ├── EmptyState
│           │   ├── Server Table
│           │   ├── ServerConfigDialog
│           │   └── DeleteConfirmDialog
│           └── LoginPage (/login/:serverName)
│               └── FlowstateAuthProvider
│                   └── LoginContent
│                       └── LoginForm

Platform Support

Related Documentation

Version History