# folder-mcp TUI Application Layout Design
**Version:** 1.0
**Date:** 2025-01-06
**Phase:** Phase 11 - User Interface Design
---
## Executive Summary
This document defines the complete visual layout and navigation structure for the folder-mcp TUI application. The design organizes 5 core screens into a responsive layout that adapts between landscape (sidebar navigation) and portrait (top navigation bar) modes.
**Key Features:**
- Responsive layout switching (landscape ↔ portrait)
- Enhanced header with LLM connection indicator
- Combined Logs & Statistics screen with split panels
- Context-sensitive help system (`?` key)
- Reuses existing custom components extensively
---
## Table of Contents
1. [Screen Overview](#screen-overview)
2. [Responsive Layout Modes](#responsive-layout-modes)
3. [Enhanced Header Design](#enhanced-header-design)
4. [Screen Mockups](#screen-mockups)
5. [Navigation System](#navigation-system)
6. [Context-Sensitive Help](#context-sensitive-help)
7. [Component Mapping](#component-mapping)
8. [Implementation Notes](#implementation-notes)
---
## Screen Overview
### Five Core Screens
| # | Screen Name | Purpose | Frequency |
|---|------------|---------|-----------|
| 1 | **Manage Folders** | Add/remove folders, view indexing status | High (default) |
| 2 | **Logs & Statistics** | Real-time logs + MCP activity monitoring | High |
| 3 | **MCP Connection Setup** | JSON config for Claude Desktop, VSCode, Cursor | Low (one-time) |
| 4 | **Global Settings** | Theme, model config, user overrides | Medium |
| 5 | **Remote Access** | Cloudflare tunnel setup (Phase 12 placeholder) | Low (future) |
---
## Responsive Layout Modes
### Layout Detection Logic
```typescript
const isLandscape = terminalColumns >= 100;
const isPortrait = terminalColumns < 100;
```
### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ SIDEBAR │ MAIN PANEL │
│ (20% width) │ (80% width) │
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │ Screen 1 │ │ │ │ │
│ │ Screen 2 │ │ │ Screen Content Here │ │
│ │ Screen 3 │ │ │ │ │
│ │ Screen 4 │ │ │ │ │
│ │ Screen 5 │ │ │ │ │
│ ╰──────────╯ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ Edit:⏎ Navigate:↑↓ Switch Panel:tab Help:? Exit:esc Theme:T │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Sidebar (20% width):**
- Vertical list of screen names
- Selected screen highlighted
- Focus indicator when active
- Keyboard: arrows to navigate, Enter to switch
**Main Panel (80% width):**
- Full screen content for selected screen
- Focus indicator when active
- Keyboard: Tab switches between sidebar and main
### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [Folders] [Logs] [MCP] [Settings] [Remote] (arrows) │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ │ │
│ │ MAIN PANEL │ │
│ │ (Full Width) │ │
│ │ │ │
│ │ Screen Content Here │ │
│ │ │ │
│ ╰────────────────────────────────────────────────────────────╯ │
│ │
├────────────────────────────────────────────────────────────────────┤
│ Edit:⏎ Navigate:↑↓ Switch:←→ Help:? Exit:esc Theme:T │
└────────────────────────────────────────────────────────────────────┘
```
**Navigation Row (3-5 lines):**
- Horizontal tabs with screen names
- Selected tab highlighted
- Focus indicator when active
- Keyboard: left/right arrows, Enter to switch
**Main Panel (remaining height):**
- Full width content for selected screen
- Focus indicator when active
- Keyboard: Tab switches between nav and main
---
## Enhanced Header Design
### Landscape Mode Header (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
```
**Elements (left to right):**
1. **App Logo**: `📁 folder-mcp`
2. **WebSocket Status**: `WebSocket connected` (green) or `WebSocket disconnected` (red)
3. **Folder Count**: `3 folders monitored`
4. **LLM Indicator**: `🤖 Claude Desktop (2m ago)` (if last interaction < 4 minutes)
### Portrait Mode Header (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
```
**Compact format:**
- WebSocket: `WS:✓` (connected) or `WS:✗` (disconnected)
- Folders: `3 folders`
- LLM: `🤖 2 clients (2m)` or `🤖 Claude Desktop (2m)`
### LLM Indicator Logic
**Display Conditions:**
- Show if: `(now - lastInteractionTime) < 4 minutes`
- Hide if: No interaction in last 4 minutes
**Content Priority:**
1. **Best**: Show client name(s): `🤖 Claude Desktop (2m ago)`
2. **Multiple clients**: `🤖 3 clients (2m ago)`
3. **Fallback**: `🤖 Connected (2m ago)`
4. **Hidden**: If last interaction > 4 minutes
**Example Scenarios:**
```
🤖 Claude Desktop (2m ago) # Single client, known name
🤖 VSCode + Claude Code (30s ago) # Multiple clients, show names
🤖 3 clients (1m ago) # Multiple clients, show count
🤖 Connected (3m ago) # Unknown client name
[no indicator] # No recent activity
```
---
## Screen Mockups
### Screen 1: Manage Folders (Default Landing Screen)
**Purpose:** Add/remove folders, view indexing status (most frequent tasks)
#### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │▸ Folders │ │ │ Manage Monitored Folders │ │
│ │ Logs │ │ ├─────────────────────────────────────────────────────┤ │
│ │ MCP │ │ │ ▸ /Users/hanan/Projects/folder-mcp/docs [active] │ │
│ │ Settings│ │ │ ⚡ 84 files indexed • indexing time 6s │ │
│ │ Remote │ │ │ │ │
│ ╰──────────╯ │ │ ▾ /Users/hanan/Projects/knowledge-base [active] │ │
│ │ │ ⚡ 1,245 files indexed • indexing time 2m 15s │ │
│ │ │ 📊 Last indexed: 5 minutes ago │ │
│ │ │ 🔄 Watching for changes │ │
│ │ │ │ │
│ │ │ /Users/hanan/Documents/work [paused] │ │
│ │ │ ⏸️ Paused • 523 files indexed │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ [+ Add A Folder] │ │
│ │ │ │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ Expand:⏎ Navigate:↑↓ Switch:tab Add:a Remove:del Pause:space Help:? │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Components Used:**
- `GenericListPanel` - Main list container
- `ManageFolderItem` - Collapsible folder items with status
- `SimpleButtonsRow` - "+ Add A Folder" button
- `BorderedBox` - Panel container with rounded borders
**Interactions:**
- **Arrow keys**: Navigate between folders
- **Enter**: Expand/collapse folder details
- **a**: Add new folder (opens file picker)
- **Delete**: Remove selected folder (with confirmation)
- **Space**: Pause/resume folder monitoring
- **Tab**: Switch between sidebar and main panel
- **?**: Show context-sensitive help
#### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 Claude Desktop (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [▸Folders] [Logs] [MCP] [Settings] [Remote] (← →) │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ Manage Monitored Folders │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ ▸ /Users/hanan/Projects/folder-mcp/docs [active] │ │
│ │ ⚡ 84 files • 6s │ │
│ │ │ │
│ │ ▾ /Users/hanan/Projects/knowledge-base [active] │ │
│ │ ⚡ 1,245 files • 2m 15s │ │
│ │ 📊 Last: 5m ago • 🔄 Watching │ │
│ │ │ │
│ │ /Users/hanan/Documents/work [paused] │ │
│ │ ⏸️ Paused • 523 files │ │
│ │ │ │
│ │ [+ Add A Folder] │ │
│ ╰────────────────────────────────────────────────────────────╯ │
│ │
├────────────────────────────────────────────────────────────────────┤
│ Expand:⏎ Nav:↑↓ Switch:←→ Add:a Del:del Pause:sp Help:? │
└────────────────────────────────────────────────────────────────────┘
```
**Portrait Adaptations:**
- Compact navigation row at top
- Text truncation for long paths
- Condensed status indicators
- Same interactions as landscape
---
### Screen 2: Logs & Statistics (Combined Monitoring Screen)
**Purpose:** Real-time logs + MCP activity monitoring in split panels
#### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │ Folders │ │ │ System Statistics [30% ▲] │ │
│ │▸ Logs │ │ ├─────────────────────────────────────────────────────┤ │
│ │ MCP │ │ │ Folders: 3 monitored • 1,852 files indexed │ │
│ │ Settings│ │ │ Cache: 245 MB / 10 GB (2.4%) • Last cleanup: 2h ago │ │
│ │ Remote │ │ │ MCP Connections: 2 active (Claude Desktop, VSCode) │ │
│ ╰──────────╯ │ │ • search: 127 calls • get_document_data: 43 calls │ │
│ │ │ • list_folders: 12 calls • get_document_outline: 8 │ │
│ │ │ Performance: Avg response time 45ms │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ ╭─────────────────────────────────────────────────────╮ │
│ │ │ Live Event Stream [70% ▼] │ │
│ │ ├─────────────────────────────────────────────────────┤ │
│ │ │ 14:32:15 [MCP] search called by Claude Desktop │ │
│ │ │ query: "authentication logic" │ │
│ │ │ folder: folder-mcp │ │
│ │ │ results: 3 documents (85ms) │ │
│ │ │ │ │
│ │ │ 14:32:10 [INFO] File change detected │ │
│ │ │ /docs/design/auth-flow.md modified │ │
│ │ │ Re-indexing... (2 files affected) │ │
│ │ │ │ │
│ │ │ 14:31:58 [MCP] get_document_data by VSCode │ │
│ │ │ file: README.md │ │
│ │ │ response: 1,234 chars (12ms) │ │
│ │ │ │ │
│ │ │ 14:31:45 [INFO] Embedding batch completed │ │
│ │ │ 32 chunks processed (1.2s) │ │
│ │ │ │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ Scroll:↑↓ Filter:f Pause:space Clear:c Export:e Help:? │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Layout Structure:**
- **Top Panel (30% height)**: Statistics summary with high-level metrics
- **Bottom Panel (70% height)**: Scrollable event stream with detailed logs
**Components Used:**
- `GenericListPanel` - Both summary and event stream
- `LogItem` - Individual log entries with expandable details
- `BorderedBox` - Panel containers
- Custom split panel layout
**Top Panel Content (Statistics):**
- Folder count and file count
- Cache usage and cleanup status
- Active MCP connections with client names
- Tool call frequency (search, get_document_data, etc.)
- Performance metrics (avg response time)
**Bottom Panel Content (Live Events):**
- Real-time log streaming
- Timestamp + log level + message
- Expandable details for MCP calls
- Color-coded by severity (INFO, WARN, ERROR)
- Auto-scroll when at bottom
**Interactions:**
- **Arrow keys**: Scroll through event stream
- **f**: Open filter dialog (by level, by client, by keyword)
- **Space**: Pause/resume live streaming
- **c**: Clear event stream
- **e**: Export logs to file
- **Enter**: Expand/collapse event details
- **Tab**: Switch between sidebar and main panel
- **?**: Show context-sensitive help
#### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [Folders] [▸Logs] [MCP] [Settings] [Remote] (← →) │
├────────────────────────────────────────────────────────────────────┤
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ Statistics [25%] │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ Folders: 3 • Files: 1,852 │ │
│ │ Cache: 245 MB / 10 GB (2.4%) │ │
│ │ MCP: 2 active • 127 searches • 43 docs │ │
│ ╰────────────────────────────────────────────────────────────╯ │
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ Live Events [75%] │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ 14:32:15 [MCP] search by Claude Desktop │ │
│ │ query: "auth logic" → 3 docs (85ms) │ │
│ │ │ │
│ │ 14:32:10 [INFO] File change detected │ │
│ │ /docs/design/auth-flow.md │ │
│ │ Re-indexing 2 files... │ │
│ │ │ │
│ │ 14:31:58 [MCP] get_document_data by VSCode │ │
│ │ README.md → 1,234 chars (12ms) │ │
│ │ │ │
│ │ 14:31:45 [INFO] Embedding batch done │ │
│ │ 32 chunks (1.2s) │ │
│ ╰────────────────────────────────────────────────────────────╯ │
├────────────────────────────────────────────────────────────────────┤
│ Scroll:↑↓ Filter:f Pause:sp Clear:c Export:e Help:? │
└────────────────────────────────────────────────────────────────────┘
```
**Portrait Adaptations:**
- Reduced statistics panel height (25% vs 30%)
- Compact log format (one-line with expandable details)
- Text truncation for long queries/paths
- Same interactions as landscape
---
### Screen 3: MCP Connection Setup (One-Time Configuration)
**Purpose:** JSON configuration snippets for connecting MCP clients
#### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │ Folders │ │ │ MCP Connection Setup │ │
│ │ Logs │ │ ├─────────────────────────────────────────────────────┤ │
│ │▸ MCP │ │ │ Select Your MCP Client: │ │
│ │ Settings│ │ │ │ │
│ │ Remote │ │ │ ○ Claude Desktop (Most Popular) │ │
│ ╰──────────╯ │ │ ● Claude Code (VS Code Extension) │ │
│ │ │ ○ VSCode MCP (Official Extension) │ │
│ │ │ ○ Cursor (AI Code Editor) │ │
│ │ │ ○ Generic MCP Client (Manual Setup) │ │
│ │ │ │ │
│ │ ├─────────────────────────────────────────────────────┤ │
│ │ │ Configuration for: Claude Code │ │
│ │ ├─────────────────────────────────────────────────────┤ │
│ │ │ │ │
│ │ │ Add this to your MCP settings: │ │
│ │ │ │ │
│ │ │ { │ │
│ │ │ "mcpServers": { │ │
│ │ │ "folder-mcp": { │ │
│ │ │ "command": "npx", │ │
│ │ │ "args": ["-y", "folder-mcp", "--mcp"], │ │
│ │ │ "env": { │ │
│ │ │ "FOLDER_MCP_PORT": "3000" │ │
│ │ │ } │ │
│ │ │ } │ │
│ │ │ } │ │
│ │ │ } │ │
│ │ │ │ │
│ │ │ [📋 Copy to Clipboard] [📂 Open Config File] │ │
│ │ │ │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ Select:↑↓ Copy:c Open:o Navigate:tab Help:? │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Components Used:**
- `GenericListPanel` - Client selection list
- `SelectionListItem` (radio buttons) - MCP client options
- `TextListItem` - JSON configuration display (with syntax highlighting)
- `SimpleButtonsRow` - Copy and Open buttons
- `BorderedBox` - Panel containers
**Supported MCP Clients:**
1. **Claude Desktop** - Most popular, desktop app
2. **Claude Code** - VS Code extension
3. **VSCode MCP** - Official Microsoft extension
4. **Cursor** - AI-powered code editor
5. **Generic** - Manual configuration template
**Configuration Display:**
- Shows JSON config specific to selected client
- Syntax highlighting for JSON
- Copy to clipboard button
- Open config file button (if applicable)
- Auto-detects config file location
**Interactions:**
- **Arrow keys**: Select MCP client
- **Enter**: Show configuration for selected client
- **c**: Copy JSON to clipboard
- **o**: Open config file in default editor (if path known)
- **Tab**: Switch between list and buttons
- **?**: Show context-sensitive help
#### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [Folders] [Logs] [▸MCP] [Settings] [Remote] (← →) │
├────────────────────────────────────────────────────────────────────┤
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ MCP Connection Setup │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ Select Your Client: │ │
│ │ │ │
│ │ ○ Claude Desktop │ │
│ │ ● Claude Code │ │
│ │ ○ VSCode MCP │ │
│ │ ○ Cursor │ │
│ │ ○ Generic │ │
│ │ │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ Config for: Claude Code │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ { │ │
│ │ "mcpServers": { │ │
│ │ "folder-mcp": { │ │
│ │ "command": "npx", │ │
│ │ "args": ["-y", │ │
│ │ "folder-mcp", │ │
│ │ "--mcp"], │ │
│ │ "env": { │ │
│ │ "FOLDER_MCP_PORT": │ │
│ │ "3000" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ │ [📋 Copy] [📂 Open] │ │
│ ╰────────────────────────────────────────────────────────────╯ │
├────────────────────────────────────────────────────────────────────┤
│ Select:↑↓ Copy:c Open:o Nav:tab Help:? │
└────────────────────────────────────────────────────────────────────┘
```
**Portrait Adaptations:**
- Compact client list (no descriptions)
- JSON auto-wrapping for narrow width
- Smaller buttons
- Same interactions as landscape
---
### Screen 4: Global Settings (Configuration)
**Purpose:** Theme selection, model config, user overrides
#### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │ Folders │ │ │ Global Settings │ │
│ │ Logs │ │ ├─────────────────────────────────────────────────────┤ │
│ │ MCP │ │ │ │ │
│ │▸ Settings│ │ │ ▸ Appearance │ │
│ │ Remote │ │ │ Theme: [default] [nord] [dracula] [solarized] │ │
│ ╰──────────╯ │ │ Currently: default │ │
│ │ │ │ │
│ │ │ ▸ Embedding Model │ │
│ │ │ Model: [nomic-embed-text] [all-MiniLM-L6-v2] │ │
│ │ │ [all-mpnet-base-v2] [Custom...] │ │
│ │ │ Currently: nomic-embed-text (Ollama) │ │
│ │ │ Status: ✅ Available │ │
│ │ │ │ │
│ │ │ ▸ Performance │ │
│ │ │ Batch Size: [32] ───────●─── [128] │ │
│ │ │ Chunk Size: [800] ──────●──── [1200] │ │
│ │ │ Chunk Overlap: [150] ───●──── [250] │ │
│ │ │ │ │
│ │ │ ▸ Cache Management │ │
│ │ │ Max Cache Size: [10 GB] ───●─── [50 GB] │ │
│ │ │ Current Usage: 245 MB (2.4%) │ │
│ │ │ Auto-Cleanup: [Enabled] Last: 2 hours ago │ │
│ │ │ [🗑️ Clear Cache Now] │ │
│ │ │ │ │
│ │ │ ▸ Advanced │ │
│ │ │ Development Mode: [Disabled] │ │
│ │ │ Log Level: [INFO] [DEBUG] [WARN] [ERROR] │ │
│ │ │ Auto-Start on Boot: [Enabled] │ │
│ │ │ │ │
│ │ │ [💾 Save Settings] [↺ Reset to Defaults] │ │
│ │ │ │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ Navigate:↑↓ Adjust:←→ Toggle:space Save:s Reset:r Help:? │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Components Used:**
- `GenericListPanel` - Settings list
- `ConfigurationListItem` - Collapsible setting groups
- `SelectionListItem` - Theme/model selectors
- `VerticalToggleRow` - Radio button groups
- `SimpleButtonsRow` - Save and Reset buttons
- `BorderedBox` - Panel container
**Setting Categories:**
1. **Appearance**
- Theme selection (default, nord, dracula, solarized)
2. **Embedding Model**
- Model selection with availability status
- Custom model URL input option
3. **Performance**
- Batch size slider (32-128)
- Chunk size slider (800-1200)
- Chunk overlap slider (150-250)
4. **Cache Management**
- Max cache size slider (10-50 GB)
- Current usage display
- Auto-cleanup toggle
- Manual clear cache button
5. **Advanced**
- Development mode toggle
- Log level selection
- Auto-start on boot toggle
**Interactions:**
- **Arrow keys**: Navigate between settings
- **Enter**: Expand/collapse setting group
- **Space**: Toggle boolean settings
- **Left/Right**: Adjust sliders, cycle through options
- **s**: Save all settings
- **r**: Reset to defaults (with confirmation)
- **Tab**: Switch between sidebar and main panel
- **?**: Show context-sensitive help
#### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [Folders] [Logs] [MCP] [▸Settings] [Remote] (← →) │
├────────────────────────────────────────────────────────────────────┤
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ Global Settings │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ▸ Appearance │ │
│ │ Theme: [default] [nord] [dracula] [solarized] │ │
│ │ │ │
│ │ ▸ Embedding Model │ │
│ │ Model: [nomic-embed-text] ✅ │ │
│ │ │ │
│ │ ▸ Performance │ │
│ │ Batch: [32] ──●── [128] │ │
│ │ Chunk: [800] ──●── [1200] │ │
│ │ Overlap: [150] ──●── [250] │ │
│ │ │ │
│ │ ▸ Cache │ │
│ │ Max: [10GB] ──●── [50GB] │ │
│ │ Usage: 245 MB (2.4%) │ │
│ │ [🗑️ Clear Cache] │ │
│ │ │ │
│ │ ▸ Advanced │ │
│ │ Dev Mode: [Off] │ │
│ │ Log: [INFO] │ │
│ │ Auto-Start: [On] │ │
│ │ │ │
│ │ [💾 Save] [↺ Reset] │ │
│ ╰────────────────────────────────────────────────────────────╯ │
├────────────────────────────────────────────────────────────────────┤
│ Nav:↑↓ Adj:←→ Toggle:sp Save:s Reset:r Help:? │
└────────────────────────────────────────────────────────────────────┘
```
**Portrait Adaptations:**
- Compact labels and sliders
- Condensed option lists
- Smaller buttons
- Same interactions as landscape
---
### Screen 5: Remote Access (Phase 12 Placeholder)
**Purpose:** Cloudflare tunnel setup for remote access (future implementation)
#### Landscape Mode (≥100 columns)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WebSocket connected • 3 folders • 🤖 Claude Desktop (2m) │
├──────────────┬──────────────────────────────────────────────────────────────┤
│ │ │
│ ╭──────────╮ │ ╭─────────────────────────────────────────────────────╮ │
│ │ Folders │ │ │ Remote Access Management │ │
│ │ Logs │ │ ├─────────────────────────────────────────────────────┤ │
│ │ MCP │ │ │ │ │
│ │ Settings│ │ │ 🚧 Coming in Phase 12 🚧 │ │
│ │▸ Remote │ │ │ │ │
│ ╰──────────╯ │ │ This screen will allow you to: │ │
│ │ │ │ │
│ │ │ • Set up Cloudflare Tunnel for remote access │ │
│ │ │ • Configure custom domains │ │
│ │ │ • Manage access control and authentication │ │
│ │ │ • Monitor remote connections │ │
│ │ │ │ │
│ │ │ For now, folder-mcp runs locally only. │ │
│ │ │ │ │
│ │ │ Stay tuned for future updates! │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ [📚 View Phase 12 Roadmap] │ │
│ │ │ │ │
│ │ │ │ │
│ │ ╰─────────────────────────────────────────────────────╯ │
│ │ │
├──────────────┴──────────────────────────────────────────────────────────────┤
│ View Roadmap:⏎ Navigate:tab Help:? │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Components Used:**
- `BorderedBox` - Panel container
- `TextListItem` - Informational text
- `SimpleButtonsRow` - Roadmap button
**Placeholder Content:**
- Clear "Coming Soon" message
- List of planned features
- Link to Phase 12 roadmap documentation
- Simple, informative layout
**Interactions:**
- **Enter**: Open Phase 12 roadmap in browser
- **Tab**: Switch between sidebar and main panel
- **?**: Show context-sensitive help
#### Portrait Mode (<100 columns)
```
┌────────────────────────────────────────────────────────────────────┐
│ 📁 folder-mcp WS:✓ • 3 folders • 🤖 2 clients (2m) │
├────────────────────────────────────────────────────────────────────┤
│ NAV: [Folders] [Logs] [MCP] [Settings] [▸Remote] (← →) │
├────────────────────────────────────────────────────────────────────┤
│ ╭────────────────────────────────────────────────────────────╮ │
│ │ Remote Access Management │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 🚧 Coming in Phase 12 🚧 │ │
│ │ │ │
│ │ This screen will allow you to: │ │
│ │ │ │
│ │ • Set up Cloudflare Tunnel │ │
│ │ • Configure custom domains │ │
│ │ • Manage access control │ │
│ │ • Monitor remote connections │ │
│ │ │ │
│ │ For now, folder-mcp runs locally only. │ │
│ │ │ │
│ │ [📚 View Phase 12 Roadmap] │ │
│ │ │ │
│ ╰────────────────────────────────────────────────────────────╯ │
├────────────────────────────────────────────────────────────────────┤
│ View:⏎ Nav:tab Help:? │
└────────────────────────────────────────────────────────────────────┘
```
**Portrait Adaptations:**
- Same content, adapted to narrow width
- Text wrapping for feature list
- Same interactions as landscape
---
## Navigation System
### Keyboard Shortcuts (Global)
| Key | Action | Context |
|-----|--------|---------|
| **Tab** | Switch between sidebar/nav and main panel | All screens |
| **1-5** | Quick jump to screen (1=Folders, 2=Logs, etc.) | All screens |
| **?** | Show context-sensitive help | All screens |
| **Esc** | Exit TUI / Close modal | All screens |
| **T** | Toggle theme (cycles through available themes) | All screens |
### Navigation in Landscape Mode (Sidebar)
**Sidebar Focus:**
- **↑/↓**: Navigate between screens in sidebar
- **Enter**: Switch to selected screen (moves focus to main panel)
- **Tab**: Move focus to main panel
- **1-5**: Quick jump to specific screen
**Main Panel Focus:**
- **Tab**: Move focus back to sidebar
- **Screen-specific shortcuts**: See individual screen sections
### Navigation in Portrait Mode (Top Nav)
**Nav Row Focus:**
- **←/→**: Navigate between screens in nav bar
- **Enter**: Switch to selected screen (moves focus to main panel)
- **Tab**: Move focus to main panel
- **1-5**: Quick jump to specific screen
**Main Panel Focus:**
- **Tab**: Move focus back to nav row
- **Screen-specific shortcuts**: See individual screen sections
### Focus Indicators
**Sidebar/Nav Bar:**
- Selected screen: `▸ Screen Name` (arrow prefix)
- Focused but not selected: Highlighted border
- Not focused: Normal border
**Main Panel:**
- Focused: Blue border (using theme color)
- Not focused: Gray border
---
## Context-Sensitive Help
### Triggering Help
**Key:** Press `?` anywhere in the TUI
**Behavior:**
1. Captures currently focused element
2. Looks up help text for that element type
3. Opens full-screen modal with help content
### Help Modal Layout
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ │
│ ╭───────────────────────────────────────────────────────────────────╮ │
│ │ Help: Manage Folder Item │ │
│ ├───────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ DESCRIPTION │ │
│ │ This is a monitored folder that folder-mcp is actively indexing │ │
│ │ and watching for changes. Each folder appears as a collapsible │ │
│ │ item showing its path, status, and indexing statistics. │ │
│ │ │ │
│ │ STATES │ │
│ │ • Active: Folder is being monitored and indexed │ │
│ │ • Paused: Monitoring temporarily stopped │ │
│ │ • Error: Issue with folder access or indexing │ │
│ │ │ │
│ │ ACTIONS │ │
│ │ • Enter: Expand/collapse folder details │ │
│ │ • Space: Pause/resume folder monitoring │ │
│ │ • Delete: Remove folder from monitoring (requires confirmation) │ │
│ │ • ↑/↓: Navigate between folders │ │
│ │ │ │
│ │ DETAILS SHOWN (when expanded) │ │
│ │ • Number of files indexed │ │
│ │ • Indexing time │ │
│ │ • Last indexed timestamp │ │
│ │ • Current activity (watching, indexing, idle) │ │
│ │ │ │
│ │ │ │
│ │ [Press Esc to Close] │ │
│ │ │ │
│ ╰───────────────────────────────────────────────────────────────────╯ │
│ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Help Modal Features:**
- Full-screen overlay with dark background
- Centered modal box with help content
- Scrollable if content exceeds screen height
- **Esc** to close modal
- Context-specific content based on focused element
### Help Content Structure
Each help entry includes:
1. **Element Name/Title** - What the user is looking at
2. **Description** - Brief explanation of purpose
3. **States** - Different states the element can be in (if applicable)
4. **Actions** - Keyboard shortcuts and what they do
5. **Details** - Additional information displayed by the element
### Help Text Repository
Help content is stored in a centralized registry:
```typescript
// src/interfaces/tui-ink/help/help-registry.ts
export const helpRegistry = {
'ManageFolderItem': {
title: 'Manage Folder Item',
description: 'This is a monitored folder...',
states: [...],
actions: [...],
details: [...]
},
'LogItem': {
title: 'Log Entry',
description: 'Real-time log message...',
// ...
},
// ... more entries
};
```
**Fallback Help:**
If no specific help is found for the focused element, show generic help with:
- Global keyboard shortcuts
- Navigation tips
- Link to full documentation
---
## Component Mapping
### Screen → Component Breakdown
| Screen | Components Used |
|--------|----------------|
| **Manage Folders** | `GenericListPanel`, `ManageFolderItem`, `SimpleButtonsRow`, `BorderedBox` |
| **Logs & Statistics** | `GenericListPanel` (×2), `LogItem`, `TextListItem`, `BorderedBox` (×2), Custom split layout |
| **MCP Connection** | `GenericListPanel`, `SelectionListItem`, `TextListItem`, `SimpleButtonsRow`, `BorderedBox` |
| **Global Settings** | `GenericListPanel`, `ConfigurationListItem`, `SelectionListItem`, `VerticalToggleRow`, `SimpleButtonsRow`, `BorderedBox` |
| **Remote Access** | `BorderedBox`, `TextListItem`, `SimpleButtonsRow` |
### New Components Needed
1. **Sidebar Component** (Landscape Mode)
- Vertical list of screen names
- Focus and selection indicators
- Responsive width (20% of terminal)
2. **TopNavBar Component** (Portrait Mode)
- Horizontal tabs for screen names
- Focus and selection indicators
- Responsive wrapping for narrow terminals
3. **SplitPanel Component** (Logs & Statistics Screen)
- Two panels with adjustable split ratio
- Top panel: 30% height
- Bottom panel: 70% height
4. **HelpModal Component** (Context-Sensitive Help)
- Full-screen overlay
- Centered modal box
- Scrollable content area
- Esc to close
5. **EnhancedHeader Component**
- Extended header with LLM indicator
- Responsive text truncation
- Dynamic content based on connection status
### Existing Component Reuse
**Already Available:**
- ✅ `GenericListPanel` - Universal list renderer
- ✅ `BorderedBox` - Container with rounded borders
- ✅ `ManageFolderItem` - Collapsible folder with status
- ✅ `LogItem` - Log entry with expandable details
- ✅ `ConfigurationListItem` - Collapsible setting group
- ✅ `SelectionListItem` - Radio button list item
- ✅ `TextListItem` - Simple text display
- ✅ `SimpleButtonsRow` - Horizontal button row
- ✅ `VerticalToggleRow` - Radio button group
- ✅ `FilePickerListItem` - File/folder picker (for Add Folder)
---
## Implementation Notes
### Phase 1: Layout Infrastructure (1-2 days)
**Tasks:**
1. Create `Sidebar` component for landscape mode
2. Create `TopNavBar` component for portrait mode
3. Implement layout detection and switching logic
4. Create enhanced header with LLM indicator
5. Update `AppFullscreen` to use new layout system
**Files to Create:**
- `src/interfaces/tui-ink/components/Sidebar.tsx`
- `src/interfaces/tui-ink/components/TopNavBar.tsx`
- `src/interfaces/tui-ink/components/EnhancedHeader.tsx`
**Files to Modify:**
- `src/interfaces/tui-ink/components/AppFullscreen.tsx`
### Phase 2: Screen Implementation (3-4 days)
**Tasks:**
1. Refactor existing "Main" panel into Screen 1 (Manage Folders)
2. Implement Screen 2 (Logs & Statistics) with split panels
3. Implement Screen 3 (MCP Connection Setup)
4. Implement Screen 4 (Global Settings)
5. Implement Screen 5 (Remote Access placeholder)
**Files to Create:**
- `src/interfaces/tui-ink/screens/ManageFoldersScreen.tsx`
- `src/interfaces/tui-ink/screens/LogsStatisticsScreen.tsx`
- `src/interfaces/tui-ink/screens/McpConnectionScreen.tsx`
- `src/interfaces/tui-ink/screens/GlobalSettingsScreen.tsx`
- `src/interfaces/tui-ink/screens/RemoteAccessScreen.tsx`
- `src/interfaces/tui-ink/components/SplitPanel.tsx` (for Logs & Statistics)
### Phase 3: Navigation & Help (1-2 days)
**Tasks:**
1. Implement screen switching logic
2. Create help modal component
3. Build help text registry
4. Wire up keyboard shortcuts (1-5 quick jump, Tab, ?)
5. Implement focus management between sidebar/nav and main panel
**Files to Create:**
- `src/interfaces/tui-ink/components/HelpModal.tsx`
- `src/interfaces/tui-ink/help/help-registry.ts`
- `src/interfaces/tui-ink/navigation/screen-manager.ts`
**Files to Modify:**
- `src/interfaces/tui-ink/components/AppFullscreen.tsx` (navigation logic)
### Phase 4: Polish & Testing (1-2 days)
**Tasks:**
1. Test responsive behavior at various terminal sizes
2. Verify keyboard navigation works smoothly
3. Test context-sensitive help on all elements
4. Ensure theme switching works on all screens
5. Test LLM indicator updates correctly
6. Performance testing (smooth rendering, no flickering)
**Testing Checklist:**
- [ ] Landscape mode (≥100 cols) layout correct
- [ ] Portrait mode (<100 cols) layout correct
- [ ] Sidebar navigation works (arrows, enter, tab)
- [ ] Top nav navigation works (arrows, enter, tab)
- [ ] Quick jump shortcuts (1-5) work
- [ ] Context help (?) works on all focusable elements
- [ ] Theme toggle (T) works on all screens
- [ ] LLM indicator appears/disappears correctly
- [ ] All screen-specific actions work (add folder, copy config, etc.)
- [ ] No flickering during navigation
- [ ] No flickering at panel boundaries
---
## Responsive Breakpoints
| Terminal Size | Layout Mode | Sidebar/Nav | Main Panel | Adaptations |
|--------------|-------------|-------------|------------|-------------|
| **≥100 cols** | Landscape | 20% width sidebar | 80% width | Full labels, all details |
| **60-99 cols** | Portrait | Top nav bar (5 lines) | Full width | Compact labels, condensed text |
| **<60 cols** | Portrait (compact) | Top nav bar (3 lines) | Full width | Abbreviated labels, minimal text |
### Width Calculations
**Landscape Mode:**
```typescript
const sidebarWidth = Math.floor(terminalColumns * 0.20); // 20%
const mainWidth = terminalColumns - sidebarWidth - 3; // -3 for borders/padding
```
**Portrait Mode:**
```typescript
const navHeight = 5; // Fixed height for nav bar
const mainHeight = terminalRows - navHeight - 3; // -3 for header/status/borders
```
---
## Future Enhancements (Post-Phase 11)
1. **Screen 2 Enhancements** (Logs & Statistics)
- Real-time graphs for MCP call frequency
- Filtering by log level, client, keyword
- Export logs to file
2. **Screen 3 Enhancements** (MCP Connection)
- Auto-detect installed MCP clients
- Test connection button
- Quick setup wizard
3. **Screen 4 Enhancements** (Global Settings)
- Import/export settings
- Setting presets (performance, balanced, quality)
- Model auto-download if not available
4. **Screen 5 Implementation** (Remote Access - Phase 12)
- Cloudflare tunnel setup
- Custom domain configuration
- Access control and authentication
5. **General Enhancements**
- Mouse support (click to select)
- Copy-to-clipboard for more elements
- Search/filter across all screens
- Notifications/alerts system
---
## Conclusion
This layout design provides:
- ✅ Clear organization of 5 core screens
- ✅ Responsive layout for all terminal sizes
- ✅ Enhanced header with LLM connection monitoring
- ✅ Combined Logs & Statistics screen for efficient monitoring
- ✅ Context-sensitive help system
- ✅ Extensive reuse of existing components
- ✅ Clear implementation roadmap (5-10 days)
The design maintains visual consistency with your existing TUI architecture (rounded borders, theme system, custom components) while providing a modern, slick, and clear user experience.
**Ready for implementation!** 🚀
