# terkelg/prompts architecture

> Architecture diagram of the GitHub repository terkelg/prompts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terkelg/prompts
- Repository: https://github.com/terkelg/prompts

## Overview

Based on both the file tree and the README, the project is a Node.js package that provides a lightweight, visually appealing, and flexible command‐line interface (CLI) for gathering user input interactively. It is essentially an open-source tool/library for building interactive prompts that can be integrated into any Node-based CLI application.

##### Main Components
- Prompts API Layer: At the core, there’s the main “prompts” function (exported in lib/index.js) that accepts an array (or single) prompt objects and coordinates the prompt flow.
- Prompt Types & Elements: Under the “lib/elements” directory you have individual implementations for different prompt types (text, number, select, multiselect, toggle, date, etc.). These modules encapsulate the UI logic specifically for each type.
- Utility Functions: In “lib/util” there are helper modules dealing with formatting, style, wrapping text, and managing figures for the prompt UI.
- Date Parts Functions: “lib/dateparts” provides helpers to work with date components used in the ‘date’ prompt module.
- Prompt Orchestration and Logic: The orchestration that handles the prompt chain (including processing questions, applying validation, formatting responses, handling submit and cancel events) is centralized in the overall “prompts” function and in “lib/prompts.js”.
- External Interfaces: The package exports an API that’s used in user applications (see example.js) and exposes override/inject functions for pre-populating responses (helpful for testing).

##### Component Relationships and Data Flow
- Input Handling Layer: The API routes the prompt questions through a controller that selects the correct type from the “elements” directory.
- Presentation/Rendering: Each prompt type module (e.g., text, number, date) is responsible for rendering its specific interface in the CLI with proper formatting.
- Utility Invocations: Common behaviors such as style, wrapping, clearing the command line, and formatting responses are handled by the “util” modules. For date prompts, the “dateparts” modules break down and format date-related inputs.
- Response Handling and Validation: After user input, the onSubmit and onCancel (if defined) functions are invoked. This logic ensures that responses are validated/formatted and that any pre-specified actions (like quitting early) are respected.
- Testing and Overrides: A separate “test” directory and functions like override/inject allow for testing prompts independently—linking to a testing layer that simulates user input.

##### Architectural Patterns and Design Principles
- Modularity: The implementation is highly modular with separate directories for different aspects (elements, utilities, dateparts). Each module has a focused responsibility.
- Extensibility: The design allows new types of prompt elements to be added easily by adhering to a common interface (e.g., properties like type, name, message, format, etc.).
- Separation of Concerns: User input, presentation logic, and utility functions are clearly separated which improves testability (note the presence of a “test” folder) and maintainability.
- Callback and Asynchronous Flow: The API is designed with async/await and promise-based callbacks (onSubmit, onCancel) to neatly handle asynchronous user interactions.

##### Technologies and Frameworks
- Node.js is the underlying runtime.
- There are integrations with GitHub workflows indicated in the “.github” folder which suggest CI testing using automated workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        EA["User Application (example.js)"]:::external
    end

    subgraph "Core CLI Prompts"
        PC["Prompts API Controller (lib/index.js & lib/prompts.js)"]:::controller
        PE["Prompt Element Modules (lib/elements)"]:::elements
    end

    subgraph "Utility & Helpers"
        U["Utility Modules (lib/util)"]:::util
        DP["Date Parts Helpers (lib/dateparts)"]:::util
    end

    subgraph "Testing"
        T["Testing & Override Layer (test)"]:::test
    end

    subgraph "CI/CD"
        CI["GitHub Workflows"]:::cd
    end

    EA -->|"calls_prompts"| PC
    PC -->|"routes_questions"| PE
    PE -->|"calls_formatting"| U
    PE -->|"calls_dateProcessing"| DP
    PE -->|"returns_response"| PC
    T -->|"inject_override"| PC
    T -->|"simulate_prompt"| PE
    PC -->|"CI_integration"| CI

    click EA "https://github.com/terkelg/prompts/blob/master/example.js"
    click PC "https://github.com/terkelg/prompts/blob/master/lib/index.js"
    click PC "https://github.com/terkelg/prompts/blob/master/lib/prompts.js"
    click PE "https://github.com/terkelg/prompts/tree/master/lib/elements"
    click U "https://github.com/terkelg/prompts/tree/master/lib/util"
    click DP "https://github.com/terkelg/prompts/tree/master/lib/dateparts"
    click T "https://github.com/terkelg/prompts/tree/master/test"

    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef controller fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef elements fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef util fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef cd fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
