PriceUpdaterAppv2/.kiro/specs/tui-missing-screens/design.md

# Design Document

## Overview

This design implements the three missing TUI screens (Scheduling, View Logs, and Tag Analysis) for the Shopify Price Updater application. The design follows the existing TUI architecture using React and Ink components, maintaining consistency with the current Configuration and Operations screens while adding new functionality for scheduling operations, viewing historical logs, and analyzing product tags.

## Architecture

### Current TUI Architecture Analysis

The existing TUI uses:

- **React with Ink**: Terminal UI framework using React.createElement for component creation
- **State Management**: React hooks (useState) for local component state
- **Navigation**: Keyboard input handling with useInput hook
- **Service Integration**: Direct integration with existing ShopifyService, ProductService, and ProgressService
- **Styling**: Consistent color scheme and layout patterns using Box and Text components

### New Screen Integration

The three new screens will integrate seamlessly with the existing architecture:

- Follow the same navigation patterns (↑/↓ arrows, Enter, Esc)
- Use consistent styling and color schemes
- Integrate with existing services and data sources
- Maintain the same error handling and progress indication patterns

## Components and Interfaces

### 1. Scheduling Screen Component

**Purpose**: Allow users to create, view, edit, and delete scheduled operations

**State Management**:

```javascript
const [schedules, setSchedules] = useState([]);
const [selectedScheduleIndex, setSelectedScheduleIndex] = useState(0);
const [editingSchedule, setEditingSchedule] = useState(null);
const [scheduleForm, setScheduleForm] = useState({
	operationType: "update",
	scheduledTime: "",
	recurrence: "once",
	enabled: true,
});
```

**Key Features**:

- List view of existing schedules with status indicators
- Form for creating new schedules with date/time picker simulation
- Edit/delete functionality for existing schedules
- Integration with ScheduleService for persistence

**Navigation Flow**:

1. Main schedule list (default view)
2. Add new schedule form
3. Edit existing schedule form
4. Schedule details view

### 2. View Logs Screen Component

**Purpose**: Display and navigate through historical operation logs

**State Management**:

```javascript
const [logFiles, setLogFiles] = useState([]);
const [selectedLogFile, setSelectedLogFile] = useState(null);
const [logContent, setLogContent] = useState("");
const [currentPage, setCurrentPage] = useState(0);
const [filterOptions, setFilterOptions] = useState({
	dateRange: "all",
	operationType: "all",
	status: "all",
});
```

**Key Features**:

- List of available log files with metadata
- Log content viewer with pagination
- Filtering and search capabilities
- Syntax highlighting for different log entry types
- Integration with existing Progress.md file and log parsing

**Navigation Flow**:

1. Log file selection list
2. Log content viewer with pagination
3. Filter/search interface

### 3. Tag Analysis Screen Component

**Purpose**: Analyze and explore product tags in the Shopify store

**State Management**:

```javascript
const [tags, setTags] = useState([]);
const [selectedTag, setSelectedTag] = useState(null);
const [tagDetails, setTagDetails] = useState(null);
const [analysisStatus, setAnalysisStatus] = useState("idle");
const [searchFilter, setSearchFilter] = useState("");
```

**Key Features**:

- Fetch and display all store tags with product counts
- Detailed tag analysis showing products, variants, and total values
- Search and filter functionality
- Integration with configuration to set target tag
- Real-time API integration with ShopifyService

**Navigation Flow**:

1. Tag list with search/filter
2. Tag details view
3. Product list for selected tag
4. Option to use tag in configuration

### 4. New Service Components

#### ScheduleService

```javascript
class ScheduleService {
  constructor() {
    this.schedulesFile = 'schedules.json';
  }

  async loadSchedules();
  async saveSchedules(schedules);
  async addSchedule(schedule);
  async updateSchedule(id, schedule);
  async deleteSchedule(id);
  validateSchedule(schedule);
}
```

#### LogService

```javascript
class LogService {
  constructor() {
    this.progressFile = 'Progress.md';
  }

  async getLogFiles();
  async readLogFile(filename);
  parseLogContent(content);
  filterLogs(logs, filters);
  paginateLogs(logs, page, pageSize);
}
```

#### TagAnalysisService

```javascript
class TagAnalysisService {
  constructor() {
    this.shopifyService = new ShopifyService();
  }

  async fetchAllTags();
  async getTagDetails(tag);
  calculateTagStatistics(products);
  searchTags(tags, query);
}
```

## Data Models

### Schedule Model

```javascript
{
  id: string,
  operationType: 'update' | 'rollback',
  scheduledTime: Date,
  recurrence: 'once' | 'daily' | 'weekly' | 'monthly',
  enabled: boolean,
  config: {
    targetTag: string,
    priceAdjustmentPercentage?: number,
    shopDomain: string,
    accessToken: string
  },
  status: 'pending' | 'completed' | 'failed' | 'cancelled',
  createdAt: Date,
  lastExecuted?: Date,
  nextExecution?: Date
}
```

### Log Entry Model

```javascript
{
  timestamp: Date,
  type: 'operation_start' | 'product_update' | 'error' | 'completion',
  operationType: 'update' | 'rollback',
  productId?: string,
  productTitle?: string,
  message: string,
  details?: object
}
```

### Tag Analysis Model

```javascript
{
  tag: string,
  productCount: number,
  variantCount: number,
  totalValue: number,
  averagePrice: number,
  priceRange: {
    min: number,
    max: number
  },
  products: Array<{
    id: string,
    title: string,
    variants: Array<{
      id: string,
      price: number,
      title: string
    }>
  }>
}
```

## Error Handling

### Consistent Error Patterns

All new screens will follow the existing error handling patterns:

1. **API Errors**: Display user-friendly messages with troubleshooting tips
2. **Network Errors**: Show retry options and connection status
3. **Validation Errors**: Highlight invalid inputs with clear guidance
4. **File System Errors**: Handle missing files gracefully with fallbacks

### Error Display Components

```javascript
const ErrorDisplay = ({ error, onRetry, onDismiss }) => {
	return React.createElement(
		Box,
		{ borderStyle: "single", borderColor: "red", padding: 1 },
		React.createElement(Text, { color: "red", bold: true }, "❌ Error"),
		React.createElement(Text, { color: "gray" }, error.message)
		// Retry and dismiss options
	);
};
```

## Testing Strategy

### Unit Testing

- Test individual screen components with mock data
- Test service classes with mocked dependencies
- Test data parsing and validation functions
- Test keyboard navigation and state management

### Integration Testing

- Test screen navigation flow
- Test service integration with real data
- Test file system operations (schedules.json, Progress.md)
- Test API integration with Shopify services

### User Experience Testing

- Test keyboard navigation consistency
- Test error handling and recovery
- Test performance with large datasets
- Test accessibility and readability

## Implementation Phases

### Phase 1: Core Services and Data Models

1. Implement ScheduleService with JSON persistence
2. Implement LogService with Progress.md parsing
3. Implement TagAnalysisService with Shopify API integration
4. Create data models and validation functions

### Phase 2: Basic Screen Implementations

1. Create Scheduling screen with basic CRUD operations
2. Create View Logs screen with file listing and content display
3. Create Tag Analysis screen with tag fetching and display
4. Implement basic navigation and keyboard handling

### Phase 3: Advanced Features and Polish

1. Add scheduling form with date/time input simulation
2. Add log filtering and pagination
3. Add tag search and detailed analysis
4. Implement configuration integration for tag selection

### Phase 4: Error Handling and Testing

1. Add comprehensive error handling for all screens
2. Implement retry logic and fallback mechanisms
3. Add loading states and progress indicators
4. Conduct thorough testing and bug fixes

## File Structure

```
src/
├── tui/
│   ├── screens/
│   │   ├── SchedulingScreen.js
│   │   ├── ViewLogsScreen.js
│   │   └── TagAnalysisScreen.js
│   ├── components/
│   │   ├── ErrorDisplay.js
│   │   ├── LoadingIndicator.js
│   │   ├── Pagination.js
│   │   └── FormInput.js
│   └── services/
│       ├── ScheduleService.js
│       ├── LogService.js
│       └── TagAnalysisService.js
├── services/ (existing)
└── tui-entry.js (updated)
```

## Integration Points

### With Existing Configuration

- Tag Analysis screen can update configuration with selected tag
- Scheduling screen uses current configuration for scheduled operations
- All screens respect current configuration settings

### With Existing Services

- Use ShopifyService for API calls in Tag Analysis
- Use ProgressService for logging scheduled operations
- Use ProductService for tag-related product operations

### With File System

- schedules.json for persistent schedule storage
- Progress.md for log reading and analysis
- .env file for configuration integration

## Performance Considerations

### Data Loading

- Implement lazy loading for large tag lists
- Use pagination for log content display
- Cache frequently accessed data in memory

### API Rate Limiting

- Respect Shopify API rate limits in tag analysis
- Implement retry logic with exponential backoff
- Show progress indicators for long-running operations

### Memory Management

- Limit log content loaded into memory
- Implement efficient data structures for tag analysis
- Clean up resources when switching screens