Core Architecture

Purpose and Scope

This document explains the foundational architecture of the hypervel/prompts library, focusing on the Prompt abstract class that serves as the base for all interactive prompts and display components. It covers:

• The Prompt base class structure and responsibilities
• Core architectural components (Terminal, OutputInterface, trait composition)
• High-level execution flow and design patterns
• How the system orchestrates user interaction

For detailed information about specific aspects of the core architecture, see:

• Prompt lifecycle and execution flow: The Prompt Lifecycle
• State transitions and validation logic: State Management and Validation
• Low-level terminal operations: Terminal Integration
• Individual prompt implementations: Interactive Prompts
• Rendering and theming: Theming and Rendering System

---

The Prompt Base Class

The Prompt abstract class at src/Prompt.php15 serves as the foundation for all prompts in the system. Every interactive prompt type (text, select, search, etc.) and display component (progress, table, note) extends this base abstraction.

Class Structure and Responsibilities

Diagram: Prompt Base Class Architecture

The base class defines the template for all prompts with these key responsibilities:

Responsibility	Implementation	Line References
Lifecycle orchestration	prompt() method coordinates initialization, rendering loop, and cleanup	src/Prompt.php104-161
State management	Maintains state property (initial, active, error, submit, cancel)	src/Prompt.php29
Rendering coordination	render() method delegates to theme-specific renderers	src/Prompt.php281-310
Input processing	handleKeyPress() processes keyboard events and updates state	src/Prompt.php327-366
Validation	validate() enforces required constraints and custom validation	src/Prompt.php391-420
Value transformation	transform() applies optional transformation to user input	src/Prompt.php371-378
Value abstraction	Abstract value() method forces subclasses to define their data model	src/Prompt.php99

Sources: src/Prompt.php15-449

---

Core Architectural Components

The Prompt class orchestrates interactions between several architectural components, each with distinct responsibilities.

Component Relationship Diagram

Diagram: Core Component Dependencies

Terminal Integration

The Terminal class (src/Prompt.php94) provides low-level terminal control:

Diagram: Terminal Control Flow

The terminal is configured for raw mode (src/Prompt.php122) to capture individual keystrokes without requiring Enter. The read() method (src/Prompt.php170) blocks until a key is pressed, driving the interactive loop.

Output Abstraction

The static $output property (src/Prompt.php89) holds a Symfony Console OutputInterface instance, defaulting to ConsoleOutput (src/Prompt.php227). This abstraction enables:

• Direct terminal writing via write() and writeln()
• Buffered output for testing (see Testing with Mocked Terminal I/O)
• New line tracking for accurate frame rendering (src/Prompt.php209-211)

Trait Composition Architecture

The Prompt class composes eight traits (src/Prompt.php17-24) to separate cross-cutting concerns:

Trait	Purpose	Key Methods	Documentation
Colors	ANSI color formatting	cyan(), dim(), bold(), etc.	ANSI Colors and Styling
Cursor	Cursor visibility/positioning	hideCursor(), moveCursorUp()	Terminal Control - Cursor and Erase
Erase	Screen/line clearing	eraseDown(), eraseLine()	Terminal Control - Cursor and Erase
Events	Event emission/handling	on(), emit(), clearListeners()	Event System
FakesInputOutput	Testing utilities	fake(), assertOutputContains()	Testing with Mocked Terminal I/O
Fallback	Non-interactive mode	shouldFallback(), fallbackWhen()	Fallback Implementations
Interactivity	TTY detection	$interactive, stream_isatty()	Fallback Implementations
Themes	Renderer delegation	renderTheme()	Theming and Rendering System

Sources: src/Prompt.php17-24

---

Architectural Design Patterns

The core architecture employs several design patterns to achieve flexibility and extensibility.

Template Method Pattern

Diagram: Template Method Pattern in prompt()

The prompt() method (src/Prompt.php104-161) implements the template method pattern:

1. Invariant steps (lines 107-131): Environment setup, TTY configuration, cursor hiding
2. Main loop (line 133): Calls runLoop() with a callback
3. Hook points: Subclasses customize behavior by:
   • Implementing abstract value() method (src/Prompt.php99)
   • Listening to key events via Events trait (src/Prompt.php333)
   • Overriding isInvalidWhenRequired() (src/Prompt.php425)
4. Invariant cleanup (line 159): Event listener cleanup

Sources: src/Prompt.php104-161

State Machine Pattern

The state property (src/Prompt.php29) implements a finite state machine:

Diagram: Prompt State Machine

State transitions occur in these methods:

Transition	Location	Trigger
initial → active	src/Prompt.php294	First render completes
active → error	src/Prompt.php397	Validation returns error string
error → active	src/Prompt.php330	Next key press clears error
active → submit	src/Prompt.php320	submit() called and validation passes
active → cancel	src/Prompt.php356	Ctrl+C pressed

The state determines rendering behavior (delegated to theme renderers) and loop continuation (src/Prompt.php335-337).

Sources: src/Prompt.php29 src/Prompt.php327-366

Event-Driven Architecture

The Events trait provides a simple observer pattern:

Diagram: Event System Flow

Concrete prompts register event listeners to customize behavior without overriding handleKeyPress(). For example, SearchPrompt listens to key events to filter options dynamically.

Sources: src/Prompt.php333

---

High-Level Execution Flow

This diagram shows how a typical prompt execution flows through the architecture:

Diagram: Prompt Execution Sequence

Execution Phases

1. Initialization (src/Prompt.php107-128)

• Capture previous newline count for accurate rendering
• Check if fallback mode should be used
• Verify TTY support and configure raw mode
• Hide cursor to prevent flickering

2. Rendering Loop (src/Prompt.php133-155)

• Implemented via runLoop() method (src/Prompt.php168-186)
• Each iteration:
  • Calls render() to update display (src/Prompt.php281-310)
  • Blocks on Terminal::read() for next keystroke (src/Prompt.php170)
  • Processes key via handleKeyPress() (src/Prompt.php327-366)
  • Emits key event for custom handlers (src/Prompt.php333)

3. Completion (src/Prompt.php150-157)

• Returns Result wrapper with transformed value
• Automatically cleans up event listeners (src/Prompt.php159)
• Destructor restores cursor and TTY state (src/Prompt.php443-448)

Sources: src/Prompt.php104-186 src/Prompt.php327-366 src/Prompt.php443-448

---

Concrete Prompt Implementation Example

The Progress class demonstrates how concrete implementations extend Prompt:

Diagram: Progress Class Architecture

Key implementation details:

Aspect	Implementation	Rationale
Abstract method	value() returns true (src/Progress.php192-194)	Progress doesn't collect user input
Disabled prompt	prompt() throws exception (src/Progress.php184-186)	Progress uses map() instead of interactive loop
Custom lifecycle	start(), advance(), finish() (src/Progress.php100-141)	Manual control over progress updates
Iterator pattern	map(Closure) method (src/Progress.php59-95)	Automatically advances progress for each item
Signal handling	SIGINT handler during execution (src/Progress.php106-110)	Graceful cancellation of long operations
Public render	Overrides render() as public (src/Progress.php146-149)	Allows manual re-rendering after label/hint updates

This demonstrates the flexibility of the Prompt abstraction—subclasses can override or disable inherited behavior as needed while still benefiting from the rendering infrastructure and terminal integration.

Sources: src/Progress.php1-216

---

Summary

The core architecture of hypervel/prompts is built on these key principles:

1. Single abstraction: All prompts extend Prompt, ensuring consistent behavior
2. Template method: prompt() orchestrates the lifecycle, subclasses customize via hooks
3. Trait composition: Cross-cutting concerns separated into reusable traits
4. Dependency injection: Terminal and output dependencies injected as static properties
5. State-driven: Explicit state machine controls rendering and behavior
6. Event-driven: Observer pattern enables decoupled customization

For implementation details on specific aspects:

• Lifecycle mechanics: The Prompt Lifecycle
• State transitions and validation: State Management and Validation
• Terminal operations: Terminal Integration

Sources: src/Prompt.php1-449 src/Progress.php1-216