Web_BLS_ProjectConsole/openspec/specs/command/design.md

# Command Capability Design

## Context

This design document describes the technical implementation of the command capability for the BLS Project Console, which allows users to send console commands to Redis queues for other programs to read and execute.

## Goals / Non-Goals

### Goals

- Implement command sending to Redis queues
- Provide command validation and error handling
- Maintain a history of sent commands
- Handle command responses from Redis
- Ensure high performance and reliability

### Non-Goals

- Command execution or processing
- Complex command syntax highlighting
- Advanced command editing capabilities

## Decisions

### Decision: Redis Queue Implementation

- **What**: Use Redis List as the queue data structure
- **Why**: Redis Lists provide efficient push/pop operations with O(1) time complexity, making them ideal for message queues
- **Alternatives considered**:
  - Redis Streams: More advanced but overkill for our use case
  - Redis Pub/Sub: No persistence, so commands would be lost if the receiving program is down

### Decision: Command History Storage

- **What**: Store command history in memory with a configurable maximum size
- **Why**: In-memory storage provides fast access times and avoids the complexity of database management
- **Alternatives considered**:
  - Database storage: Adds complexity and latency
  - File system: Not suitable for real-time access

### Decision: Command Validation

- **What**: Implement basic command validation on both frontend and backend
- **Why**: Frontend validation provides immediate feedback to users, while backend validation ensures data integrity
- **Alternatives considered**:
  - Only frontend validation: Less secure, as users could bypass it
  - Only backend validation: Less responsive, as users would have to wait for server response

## Architecture

### Frontend Architecture

```
CommandView Component
├── CommandForm Component
├── CommandHistory Component
└── CommandService
```

### Backend Architecture

```
Command Routes
├── Command Service
│   ├── Redis Client
│   └── Command Manager
└── Command History Manager
```

## Implementation Details

### Redis Connection

- Use the `redis` npm package to connect to Redis
- Implement automatic reconnection with exponential backoff
- Handle connection errors gracefully

### Command Sending

1. User enters a command in the frontend form
2. Frontend validates the command (not empty, no invalid characters)
3. Frontend sends a POST request to `/api/commands` with the command content
4. Backend validates the command again
5. Backend generates a unique command ID
6. Backend adds the command to the Redis queue using `LPUSH`
7. Backend stores the command in the in-memory command history
8. Backend sends a success response to the frontend

### Command Validation

- **Frontend validation**:
  - Check that the command is not empty
  - Check that the command does not contain invalid characters (e.g., null bytes)
  - Limit command length to 1024 characters
- **Backend validation**:
  - Same checks as frontend
  - Additional server-side validation if needed

### Command History

- Store command history in an array in memory
- Implement a circular buffer to limit memory usage
- Default maximum command count: 1000
- Configurable via environment variable
- Include command ID, content, timestamp, and status

### Command Response Handling

1. Receiving program reads the command from the Redis queue
2. Receiving program executes the command
3. Receiving program writes the response to a separate Redis queue
4. Backend listens for responses on the response queue using `BLPOP`
5. When a response is received, backend updates the command status in the history
6. Backend notifies the frontend of the response via Server-Sent Events (SSE)

## Risks / Trade-offs

### Risk: Redis Connection Failure

- **Risk**: If Redis connection is lost, commands won't be sent
- **Mitigation**: Implement automatic reconnection with exponential backoff, and notify users when connection is lost

### Risk: Command Loss

- **Risk**: Commands could be lost if Redis goes down
- **Mitigation**: Implement Redis persistence (RDB or AOF) to ensure commands are not lost

### Risk: Command Response Timeout

- **Risk**: Commands could take too long to execute, causing the UI to hang
- **Mitigation**: Implement a timeout mechanism for command responses, and show a loading indicator to users

## Migration Plan

No migration is required as this is a new feature.

## Open Questions

- What is the expected maximum command frequency per minute?
- Should we add support for command templates or macros?
- Should we implement command scheduling for future execution?