# TUI API Client — Design Specification
A terminal-based API client inspired by Postman, built for keyboard-first workflows.
---
## Overview
The application is a full-screen TUI (Terminal User Interface) divided into logical panels. It allows developers to organize API requests into collections, configure request parameters, send HTTP requests, and inspect responses — all without leaving the terminal.
---
## Design Inspiration & Layout
The design is heavily inspired by **lazydocker**. It prioritizes a clean, efficient layout with intuitive drill-down keyboard navigation. It should look visually identical to lazydocker in terms of structure, but adapted for an API client use case.
The layout uses a split-screen approach:
- **Left Column (30%)**: Dedicated to request organization (Collections and APIs).
- **Right Column (70%)**: Dedicated to request configuration, editing, and response inspection.
---
## Panels & Logical Layers
The UI is divided into **Logical Layers** to facilitate intuitive drill-down navigation.
### Layer 1: Organization (Left Column)
- **Collections Panel**: Displays saved API collections in a tree structure. Folders and Requests.
- **APIs Panel**: Scoped to the selected folder's requests. Allows quick navigation between requests within the active folder.
### Layer 2 & 3: Configuration (Right Column, Top/Middle)
- **Request Bar**: Shows HTTP method, URL, and a visual Send button indicator.
- **Properties Panel (Layer 2)**: List of configurable properties for the selected request (Params, Auth, Headers, Body, Scripts, Settings).
- **Property Details Panel (Layer 3)**: The editor/input area for the currently selected property. E.g., if "Body" is selected in Layer 2, Layer 3 shows the JSON editor.
### Layer 4 & 5: Inspection (Right Column, Bottom)
- **Response Panel (Layer 4)**: Displays the response body with syntax highlighting and the status code badge.
- **Response Stat Panel (Layer 5)**: Meta-information (Response Time, Size, Network details).
---
## Navigation Flow
The navigation flow uses a "Drill-Down" and "Pop-Up" layer system, similar to Lazydocker or Vim-like directory trees.
1. **Initial State (Layer 1)**: By default, the application starts with the **Collections** panel focused.
2. **Layer 1 Navigation**:
- `j`/`k` to navigate up and down the tree.
- `Tab` cycles focus strictly between the `Collections` and `APIs` panels.
- When a folder is highlighted, the `APIs` panel updates to show its contents.
3. **Drill Down to Layer 2 (Properties)**:
- When the user selects a request (by pressing `Enter` or `l`), focus **automatically shifts** to the **Properties Panel** (Layer 2).
- This allows users to immediately configure the request.
4. **Drill Down to Layer 3 (Details)**:
- From the Properties panel, pressing `Enter` or `l` on a specific property (e.g., Headers or Body) shifts focus to the **Property Details Panel** (Layer 3) to edit the values.
5. **Pop-Up / Go Back**:
- At any point in Layer 2 or 3, pressing `Esc` or `h` will return focus to the previous layer (e.g., from Details back to Properties, or from Properties back to Collections).
6. **Execution & Layer 4/5**:
- Pressing `Ctrl+Enter` sends the request.
- Upon receiving a response, focus automatically shifts to the **Response Panel** (Layer 4) for immediate inspection.
- Pressing `Esc` from the Response panel returns focus to the previously active configuration panel.
---
## Color Coding
| `GET` method | Green |
| `POST` method | Orange / Yellow |
| `PUT` method | Blue |
| `DELETE` method | Red |
| `2xx` status | Green |
| `4xx` status | Orange |
| `5xx` status | Red |
| Selected item | Highlighted / reversed |
| Active panel | Bold border / accent |
---
## Implementation Notes
- **Responsive Design**: The Left/Right split should maintain a 30/70 or 25/75 ratio. The right column should dynamically resize its vertical sections based on content or user preference.
- **Vim Modes**: While navigating layers, the app operates in `Normal` mode. When editing a URL or a Body field, it enters `Editing` mode where keystrokes are captured as text.
- **Cross-Platform**: Built with `crossterm` for Windows/Linux compatibility.
- **Theme Support**: Colors and borders should eventually be configurable.