# Planning Considerations

## Assumptions
- **Python Version**: The project will use Python 3.10 or higher to leverage modern `asyncio` features and pattern matching.
- **Dependency Management**: `uv` is the primary tool for Python dependency management. `pip` compatibility is maintained via `requirements.txt` generation if needed.
- **TUI Complexity**: The "Terminal User Interface" is assumed to be a functional Command Line Interface (CLI) with an interactive shell for the first iteration, rather than a full-window ncurses/textual GUI, to prioritize architectural correctness.
- **Message Format**: Messages passed between Broker, Workers, and Clients are assumed to be JSON-serializable dictionaries.

## Constraints
- **Single Threaded**: The Core (Broker/Worker) must run in a single thread using `asyncio`. No `threading` or `multiprocessing` for the core message passing logic to avoid locking overheads.
- **Heartbeat Timing**: Strict adherence to the 5s send / 10s timeout rule is required to satisfy the specification.
- **Workspace Isolation**: All file I/O related to the instance state must happen within the configured `WORKSPACE` directory.

## Risks
- **Event Loop Blocking**: Since the system is single-threaded, any CPU-intensive task in a Worker will block the entire Broker and other Workers.
    - *Mitigation*: Emphasize in documentation that Workers must yield control frequently or offload heavy computation (though offloading is out of initial scope).
- **Heartbeat Deadlock**: If the event loop is blocked (see above), heartbeats might be missed, causing false disconnections.
    - *Mitigation*: Keep handler logic minimal.
- **Race Conditions**: Although single-threaded, `asyncio` tasks can still have race conditions regarding shared state (e.g., Worker lists).
    - *Mitigation*: Use atomic operations where possible or `asyncio.Lock` if absolutely necessary (prefer lock-free designs).

## Dependencies
- **Runtime**:
    - `python >= 3.10`
    - `fastapi`: Web server framework.
    - `uvicorn`: ASGI server.
    - `websockets`: WebSocket protocol handling.
    - `python-dotenv`: Configuration management.
    - `typer`: (Optional) For building the CLI client easily.
- **Development**:
    - `pytest`: Testing framework.
    - `pytest-asyncio`: Async testing support.
    - `pytest-cov`: Code coverage.
    - `hypothesis`: For fuzzing/random testing.