# scooter7/conversational-form architecture

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

- Interactive diagram: https://gitdiagram.com/scooter7/conversational-form
- Repository: https://github.com/scooter7/conversational-form

## Overview

##### Project type and purpose
- This is an open-source front-end JavaScript/TypeScript library (“Conversational Form”) that transforms standard HTML forms into conversational chat-style interfaces. It ships as a distributable bundle (JS + CSS) and is intended for integration into any web page.

##### High-level architectural components
A. Source modules
- cf.Tag classes (form-tags folder): takes native form inputs/buttons and wraps them in “Tag” objects
- cf.Data.Dictionary (dictionaryData): holds default question and error messages
- cf.Logic.FlowManager: orchestrates the question flow, determines next Tag, handles branching, re-usable variables
- cf.UI elements (ui folder):
– BasicElement, ScrollController, UserInput: low-level DOM renderers and event handlers
– ChatList, ChatResponse: chat message components
– ControlElements (buttons, radio, checkbox, upload): interactive widgets
- Styles (stylus files under src/styles): theme variables and UI component styles
B. Build pipeline
- gulp-tasks:
– scripts.js: compiles TypeScript → JavaScript, bundles modules
– styles.js: compiles Stylus → CSS
– images.js: processes images
– bower.js/package.json: manages front-end dependencies
- gulpfile.js coordinates sub-tasks and outputs:
– dist/conversational-form.min.js
– dist/conversational-form.min.css
C. Documentation and examples
- docs/: static site with demos (HTML/CSS/JS)
- test/: HTML pages for automated/manual test scenarios

##### Interactions & data flows
- [Developer’s web page] includes dist JS/CSS →
ConversationalForm auto-scans DOM for <form cf-form-element> →
Instantiates cf.ConversationalForm →
Internally runs Tag.createTag() over form elements →
FlowManager sequences questions using Dictionary data →
UI components render chat bubbles and control elements →
UserInput captures answers →
FlowManager updates state & renders next question →
On completion, submitCallback or form.submit() fires →
Collected form data posted to server or handled by callback
- Build pipeline reads TS/Stylus/images → transforms → writes to dist/ for consumption.

##### Architectural patterns & design principles
- Modular, single-responsibility classes: Tags, Logic, UI are separated
- MVC-style separation:
- Model: Tag definitions + Dictionary
- Controller: FlowManager
- View: UI element classes + stylus styles
- Plugin/extension points:
- Custom tags via Tag.createTag()
- Override dictionaryData / dictionaryAI
- Custom submitCallback and userImage
- TypeScript for type safety; Gulp for task automation; Stylus for theming.

## Diagram (Mermaid)

```mermaid
graph TB

  %% Source Modules
  subgraph "Source Modules" 
    direction TB
    %% Core
    CFCore["ConversationalForm.ts\nConversationalForm.plugin.js"]:::src
    %% Model: Tags
    subgraph "Model: Tag Classes" 
      direction TB
      Tag["Tag.ts"]:::src
      TagGroup["TagGroup.ts"]:::src
      InputTag["InputTag.ts"]:::src
      ButtonTag["ButtonTag.ts"]:::src
      OptionTag["OptionTag.ts"]:::src
      SelectTag["SelectTag.ts"]:::src
    end
    %% Model: Dictionary
    Dictionary["Dictionary.ts"]:::src
    %% Controller
    subgraph "Controller: FlowManager" 
      direction TB
      FlowMgr["FlowManager.ts"]:::src
      Helpers["Helpers.ts"]:::src
    end
    %% View: UI Elements
    subgraph "View: UI Elements" 
      direction TB
      BasicEl["BasicElement.ts"]:::src
      ScrollCtrl["ScrollController.ts"]:::src
      UserInput["UserInput.ts"]:::src
      subgraph "Chat Components"
        ChatList["ChatList.ts"]:::src
        ChatResponse["ChatResponse.ts"]:::src
      end
      subgraph "Control Elements"
        ControlEl["ControlElements.ts"]:::src
        ControlElement["ControlElement.ts"]:::src
        Btn["Button.ts"]:::src
        Checkbox["CheckboxButton.ts"]:::src
        OptionBtn["OptionButton.ts"]:::src
        OptionsList["OptionsList.ts"]:::src
        Radio["RadioButton.ts"]:::src
        Upload["UploadFileUI.ts"]:::src
      end
    end
    %% Styles
    subgraph "Styles (Stylus)" 
      direction TB
      VarStyl["cf-variables.styl"]:::src
      CFStyl["cf.styl"]:::src
      InfoStyl["cf-info.styl"]:::src
      InputStyl["cf-input.styl"]:::src
      ListBtnStyl["cf-list-button.styl"]:::src
      ChatStyl["cf-chat.styl"]:::src
      ChatRespStyl["cf-chat-response.styl"]:::src
      BtnStyl["cf-button.styl"]:::src
      CheckboxStyl["cf-checkbox-button.styl"]:::src
      CtrlElStyl["cf-control-elements.styl"]:::src
      OptionsListStyl["cf-options-list.styl"]:::src
      RadioStyl["cf-radio-button.styl"]:::src
      UploadStyl["cf-upload-file-ui.styl"]:::src
    end
  end

  %% Build Pipeline
  subgraph "Build Pipeline & Distribution"
    direction TB
    Scripts["gulp-tasks/scripts.js"]:::build
    StylesTask["gulp-tasks/styles.js"]:::build
    Images["gulp-tasks/images.js"]:::build
    Bower["gulp-tasks/bower.js\npackage.json"]:::build
    Gulpfile["gulpfile.js"]:::build
    DistJS["dist/conversational-form.min.js"]:::build
    DistCSS["dist/conversational-form.min.css"]:::build
  end

  %% Documentation & Tests
  subgraph "Docs & Tests" 
    direction TB
    Docs["docs/"]:::external
    Tests["test/"]:::external
  end

  %% Runtime Integration
  subgraph "Runtime Integration" 
    direction TB
    Host["Host Web Page\n(form cf-form-element)"]:::external
    Init["ConversationalForm.init()"]:::runtime
    TagCreate["Tag.createTag()"]:::runtime
    Sequence["FlowManager.sequence"]:::runtime
    UIRender["UI.renderChat & Controls"]:::runtime
    User["User Input"]:::external
    Submit["submitCallback / form.submit()"]:::runtime
  end

  %% Flows
  CFCore -->|includes| Tag
  CFCore -->|includes| Dictionary
  CFCore -->|includes| FlowMgr
  CFCore -->|includes| BasicEl
  CFCore -->|includes| VarStyl

  Scripts -->|compiles TS→JS| DistJS
  StylesTask -->|compiles Stylus→CSS| DistCSS
  Images -->|processes images| DistJS
  Bower -->|manages deps| Scripts
  Gulpfile -->|orchestrates tasks| Scripts
  Gulpfile --> StylesTask
  Gulpfile --> Images
  Gulpfile --> Bower

  Host -->|loads JS/CSS| DistJS
  Host -->|loads JS/CSS| DistCSS
  Host -->|auto-scans DOM| Init
  Init -->|instantiates| TagCreate
  TagCreate -->|wraps form elements| Sequence
  Sequence -->|uses Dictionary| Dictionary
  Sequence -->|calls| UIRender
  UIRender -->|renders chat| User
  User -->|answers| Sequence
  Sequence -->|on complete| Submit

  %% Extension Points
  Dictionary -.->|override here| Init
  Tag -.->|custom tags| Init
  Submit -.->|custom callback| Init

  %% Click events
  click CFCore "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ConversationalForm.ts"
  click CFCore "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ConversationalForm.plugin.js"
  click Tag "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/Tag.ts"
  click TagGroup "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/TagGroup.ts"
  click InputTag "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/InputTag.ts"
  click ButtonTag "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/ButtonTag.ts"
  click OptionTag "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/OptionTag.ts"
  click SelectTag "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/form-tags/SelectTag.ts"
  click Dictionary "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/data/Dictionary.ts"
  click FlowMgr "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/logic/FlowManager.ts"
  click Helpers "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/logic/Helpers.ts"
  click BasicEl "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/BasicElement.ts"
  click ScrollCtrl "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/ScrollController.ts"
  click UserInput "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/UserInput.ts"
  click ChatList "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/chat/ChatList.ts"
  click ChatResponse "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/chat/ChatResponse.ts"
  click ControlElement "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/ControlElement.ts"
  click ControlEl "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/ControlElements.ts"
  click Btn "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/Button.ts"
  click Checkbox "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/CheckboxButton.ts"
  click OptionBtn "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/OptionButton.ts"
  click OptionsList "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/OptionsList.ts"
  click Radio "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/RadioButton.ts"
  click Upload "https://github.com/scooter7/conversational-form/blob/master/src/scripts/cf/ui/control-elements/UploadFileUI.ts"
  click VarStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/cf-variables.styl"
  click CFStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/cf.styl"
  click InfoStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/cf-info.styl"
  click InputStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/cf-input.styl"
  click ListBtnStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/cf-list-button.styl"
  click ChatStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/chat/cf-chat.styl"
  click ChatRespStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/chat/cf-chat-response.styl"
  click BtnStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-button.styl"
  click CheckboxStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-checkbox-button.styl"
  click CtrlElStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-control-elements.styl"
  click OptionsListStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-options-list.styl"
  click RadioStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-radio-button.styl"
  click UploadStyl "https://github.com/scooter7/conversational-form/blob/master/src/styles/cf/ui/control-elements/cf-upload-file-ui.styl"
  click Scripts "https://github.com/scooter7/conversational-form/blob/master/gulp-tasks/scripts.js"
  click StylesTask "https://github.com/scooter7/conversational-form/blob/master/gulp-tasks/styles.js"
  click Images "https://github.com/scooter7/conversational-form/blob/master/gulp-tasks/images.js"
  click Bower "https://github.com/scooter7/conversational-form/blob/master/gulp-tasks/bower.js"
  click Gulpfile "https://github.com/scooter7/conversational-form/blob/master/gulpfile.js"
  click DistJS "https://github.com/scooter7/conversational-form/blob/master/dist/conversational-form.min.js"
  click DistCSS "https://github.com/scooter7/conversational-form/blob/master/dist/conversational-form.min.css"
  click Docs "https://github.com/scooter7/conversational-form/tree/master/docs/"
  click Tests "https://github.com/scooter7/conversational-form/tree/master/test/"

  %% Styles
  classDef src fill:#cce5ff,stroke:#005293
  classDef build fill:#d4edda,stroke:#155724
  classDef runtime fill:#ffeeba,stroke:#856404
  classDef external fill:#e2e3e5,stroke:#6c757d
```
