# Frontend (TUI) Architecture

## Render Pipeline

The TUI is built with [ratatui](https://github.com/ratatui-org/ratatui) and [crossterm](https://github.com/crossterm-rs/crossterm).

```
Timer tick
    │
    ▼
main.rs: fn tui_loop()
    │
    ├── controller/input.rs: handle_key() → action
    ├── app/runtime/actions/mod.rs: apply_action()
    │       │
    │       └── state mutates (AppStateRest)
    │
    └── view/mod.rs: build TUI layout
            │
            ├── view/chat.rs: Chat transcript
            ├── view/sidebar.rs: Usage dashboard
            ├── view/status.rs: Status bar
            ├── view/markdown.rs: Message renderer
            ├── view/workflow.rs: Hive-mind progress
            └── view/theme.rs: Tokyo Night palette
```

## Overlay System

16 overlays managed by `app/mode/`:

| Overlay | File | Purpose |
|---------|------|---------|
| Chat input | `mod.rs` | Main input bar with autocomplete |
| Bash | `bash.rs` | Interactive shell panel |
| Editor | `editor.rs` | Built-in file editor |
| Effort | `effort.rs` | LLM effort selector |
| Help | `help.rs` | Keybindings help |
| Key Input | `key_input.rs` | Custom key binding |
| Learning | `learning.rs` | Lesson viewer |
| Loading | `loading.rs` | Spinner overlay |
| MCP | `mcp.rs` | MCP server management |
| Quit Confirm | `quit_confirm.rs` | Exit confirmation dialog |
| Rewind | `rewind.rs` | Message/history rewind |
| Settings | `settings.rs` | Settings panel |
| Todo | `todo.rs` | Task/TODO list |
| Workflow | (via view) | Workflow progress |

## Layout Structure

```
┌─────────────────────────────────────────────┐
│  Status Bar  (view/status.rs)               │
├──────────────────────┬──────────────────────┤
│                      │                      │
│   Chat Transcript    │   Sidebar            │
│   (view/chat.rs)     │   (view/sidebar.rs)  │
│   scrollable,        │   tokens, status,    │
│   inline-log style   │   agent info         │
│                      │                      │
├──────────────────────┴──────────────────────┤
│  Input Bar + Autocomplete dropdown          │
│  (view/mod.rs)                              │
└─────────────────────────────────────────────┘
```

## Input Handling

`controller/input.rs`:

- Normal mode: keystrokes go to the active overlay
- `@mention` triggers fuzzy autocomplete (via `nucleo-matcher`)
- Tab cycles autocomplete candidates
- `Ctrl+Y` copies selected text to clipboard (via OSC52 escape sequence)
- Arrow keys scroll chat, sidebar, and other scrollable panels

## Theme

`view/theme.rs` defines a Tokyo Night color palette as constants (`Theme::PRIMARY`, `Theme::ERROR`, `Theme::TEXT_MUTED`, etc.) rather than using a theme enum or hot-reloadable config. All view modules import and apply these constants directly.