Home

project-structure

6 min read

ein-cli Project Structure

This document provides a comprehensive overview of the ein-cli project structure, explaining the purpose and functionality of each component.

📁 Root Directory

ein-cli/
├── main.go                    # Application entry point
├── go.mod                     # Go module definition and dependencies
├── go.sum                     # Dependency checksums (auto-generated)
├── plan.md                    # Development roadmap and implementation plan
├── PROJECT_STRUCTURE.md       # This file - project documentation
└── .gitignore                 # Git ignore rules

Key Root Files

  • main.go: The main entry point that determines whether to launch CLI or TUI mode based on command-line arguments
  • go.mod: Defines the Go module with all Charm stack dependencies (bubbletea, bubbles, lipgloss, cobra, viper)
  • plan.md: Comprehensive development plan with implementation phases and architecture decisions

🖥️ CLI Module (cmd/)

The CLI module uses the Cobra framework to provide command-line interface functionality.

cmd/
├── root.go                    # Root command configuration and global flags
├── api.go                     # API request commands for CLI usage
└── version.go                 # Version information command

CLI Components

cmd/root.go

  • Purpose: Main CLI command configuration and global setup
  • Features:
    • Global flags (—verbose, —output, —config)
    • Configuration file loading with Viper
    • Environment variable binding
    • Base command structure

cmd/api.go

  • Purpose: CLI commands for making API requests directly from command line
  • Features:
    • HTTP method validation (GET, POST, PUT, DELETE, etc.)
    • Header parsing and validation
    • Request body handling
    • Timeout configuration
    • Currently shows request info (HTTP client implementation pending)

cmd/version.go

  • Purpose: Display version, build date, and git commit information
  • Features:
    • Version information display
    • Build metadata (set via build flags in production)

🏗️ Internal Modules (internal/)

Internal packages contain private application code that cannot be imported by external projects.

internal/
├── messages/
│   └── navigation.go          # Custom Bubbletea messages for screen navigation
└── models/
    ├── config.go              # Configuration data structures
    └── api.go                 # API request/response models

Internal Components

internal/messages/navigation.go

  • Purpose: Custom Bubbletea messages for inter-screen communication
  • Features:
    • NavigateMsg: Message type for requesting screen changes
    • Breaks import cycles between TUI packages

internal/models/config.go

  • Purpose: Application configuration structures and defaults
  • Features:
    • Config: Main configuration structure
    • ServerConfig: Default server settings (URL, timeout, headers)
    • ThemeConfig: UI theme preferences (color scheme, accent color)
    • HistoryConfig: Request history behavior settings
    • AuthConfig: Authentication configuration and token storage
    • NewDefaultConfig(): Creates sensible default configuration

internal/models/api.go

  • Purpose: Data models for API requests and responses
  • Features:
    • APIRequest: Complete request structure (method, URL, headers, body, auth)
    • APIResponse: Response data (status, headers, body, timing, errors)
    • AuthInfo: Authentication information for different auth types
    • RequestHistory: Historical request storage
    • HistoryEntry: Individual request-response pairs
    • Helper methods for status code checking (IsSuccess(), IsClientError(), etc.)

🎨 TUI Module (tui/)

The TUI module uses the Charm stack (Bubbletea, Bubbles, Lipgloss) to provide an interactive text user interface.

tui/
├── app.go                     # Main TUI application and coordinator
├── router.go                  # Screen navigation and routing system
├── keys.go                    # Global key bindings and shortcuts
├── styles/
│   ├── theme.go              # Color palette and base styles
│   └── components.go         # Component-specific styling
└── screens/
    ├── main_menu.go          # Main menu screen with navigation options
    ├── api_form.go           # API request form screen (placeholder)
    ├── settings.go           # Settings configuration screen (placeholder)
    └── help.go               # Help and documentation screen

TUI Core Components

tui/app.go

  • Purpose: Main TUI application that coordinates all screens and handles global state
  • Features:
    • Application lifecycle management (Init, Update, View)
    • Screen model registration and initialization
    • Global message handling and routing
    • Window resize handling
    • Header/footer rendering with breadcrumbs
    • Navigation command creation

tui/router.go

  • Purpose: Navigation system between different TUI screens
  • Features:
    • Screen enumeration (MainMenu, APIForm, Settings, etc.)
    • Navigation history for back button functionality
    • Screen-to-screen data passing
    • Breadcrumb path generation
    • Model management for each screen

tui/keys.go

  • Purpose: Centralized key binding definitions
  • Features:
    • Navigation keys (arrows, vim-style j/k/h/l)
    • Action keys (Enter, Space, Tab)
    • Application control (quit, back, help)
    • Special function keys (refresh, edit, delete, save)
    • Help text generation for each binding

TUI Styling (tui/styles/)

tui/styles/theme.go

  • Purpose: Global color palette and base styling definitions
  • Features:
    • Color Palette: Elegant purple theme with good contrast
      • Primary: Purple (#8B5CF6), PurpleLight (#A78BFA), PurpleDark (#6D28D9)
      • Neutrals: White, Gray, GrayLight, GrayDark
      • Status: Green, Red, Orange, Blue
    • Base Styles: BaseStyle, TitleStyle, SubtitleStyle, TextStyle, HelpStyle

tui/styles/components.go

  • Purpose: Component-specific styling for consistent UI elements
  • Features:
    • Menu Styles: Container, items, selection, hover states
    • Form Styles: Form containers, inputs, labels, focus states
    • Button Styles: Primary, secondary, hover states
    • Status Styles: Success, error, loading indicators
    • Layout Styles: Containers, headers, footers with proper spacing

TUI Screens (tui/screens/)

tui/screens/main_menu.go

  • Purpose: Main navigation hub with menu options
  • Features:
    • Menu items with icons and descriptions
    • Navigation to different application screens
    • Custom list rendering with purple theme
    • Exit functionality
    • Welcome message and usage tips

tui/screens/api_form.go

  • Purpose: Form for creating and editing API requests (placeholder)
  • Features:
    • Form field navigation (Tab/Shift+Tab)
    • Field tracking and validation preparation
    • Integration with APIRequest model
    • Future Implementation: Full form fields with Huh library

tui/screens/settings.go

  • Purpose: Configuration management interface (placeholder)
  • Features:
    • Current configuration display
    • Server, theme, history, and auth settings preview
    • Future Implementation: Interactive configuration forms

tui/screens/help.go

  • Purpose: Documentation and help system
  • Features:
    • Keyboard shortcut documentation organized by category
    • Usage tips and getting started guide
    • Application information and about section
    • Context-aware help text

🔧 Architecture Patterns

Model-View-Update (MVU) Pattern

The TUI follows Bubbletea’s MVU architecture:

  • Model: Application state and data
  • View: Rendering functions that convert state to strings
  • Update: Message handlers that modify state

Screen-Based Navigation

Each screen is a self-contained Bubbletea model:

  • Independent state management
  • Message handling and routing
  • Consistent interface implementation

Shared Business Logic

Core functionality is shared between CLI and TUI:

  • Same configuration models
  • Identical API request structures
  • Common validation and processing logic

Import Cycle Prevention

  • Messages are isolated in internal/messages/
  • Screen constants are defined locally to avoid cycles
  • Interface-based dependencies where needed

🎨 Design Principles

Elegant Purple Theme

  • Consistent purple accent color (#8B5CF6) throughout
  • Good contrast ratios for accessibility
  • Professional appearance with subtle elegance

Responsive Layout

  • Terminal size awareness
  • Proper spacing and padding
  • Flexible component sizing

Keyboard-First Navigation

  • Vim-style navigation (j/k/h/l) alongside arrows
  • Tab-based form navigation
  • Intuitive shortcuts with help text

Extensible Architecture

  • Easy to add new screens and commands
  • Consistent patterns across components
  • Clean separation of concerns

🚀 Getting Started

Running the Application

# TUI Mode (interactive)
./ein-cli
 
# CLI Mode (direct commands)
./ein-cli --help
./ein-cli version
./ein-cli api GET https://httpbin.org/get

Development Workflow

  1. Adding New Screens: Create in tui/screens/, register in tui/app.go
  2. Adding CLI Commands: Create in cmd/, add to root command
  3. Extending Models: Modify structures in internal/models/
  4. Styling Updates: Adjust in tui/styles/ for consistent theming

Next Steps

According to plan.md, the next development phases involve:

  1. HTTP client implementation
  2. Advanced form components with Huh
  3. Request history and persistence
  4. Configuration management
  5. Authentication systems

This architecture provides a solid foundation for building a comprehensive API client tool with both CLI and TUI interfaces.

Graph View

Backlinks