Dynamic Form Builder Project - Complete Package (Internal Proposal, RFP, Technical Specs, Migration Approach)

appendix-a-technical-specifications.md

Appendix A: Technical Specifications

Field Types, Validations, and Behaviors

This appendix provides detailed technical specifications for the existing field types, validation methods, and behaviors that must be supported in the new Dynamic Form Builder implementation.

---

1. Field Types

1.1 Data Field Types

Field types define how data is stored in the database.

Field Type	Description	Database Type
text	Single or multi-line text	String/Text
integer	Whole numbers	Integer
decimal	Decimal numbers	Decimal
date	Date values	Date
datetime	Date and time values	DateTime
boolean	True/false values	Boolean

1.2 UI Types

UI types define how fields are rendered and interact with users.

UI Type	Description	Use Case
text_field	Standard single-line text input	Name, email, etc.
hidden_field	Hidden field not visible to users	System values, IDs
numeric_field	Numeric input with validation	Age, GPA, ID numbers
check_box	Multiple checkboxes	Multi-select options
single_check_box	Single checkbox	Yes/No, acceptance
date	Basic date input	Birth date, enrollment date
date_picker	Interactive date picker	User-friendly date selection
date_picker_100_years_back	Date picker with extended range	Birth dates for older adults
radio_button	Radio button group	Single selection from options
drop_down	Standard dropdown select	State, status selection
multi_select	Multiple selection dropdown	Multiple options
select2	Enhanced Select2 component	Searchable, ajax-enabled selects

---

2. Validation Methods

The ValidationMethods module provides reusable validation logic that can be applied at both backend and frontend levels. This module should be leveraged in the new implementation.

2.1 Backend Validation Methods

Backend validations are executed server-side before data is saved.

2.1.1 SSN Validations

Method	Description	Format
valid_ssn	Basic SSN format	123-45-6789 or 123456789
valid_ssn_strict	SSN with blacklist check	Excludes common patterns (111111111, etc.)
valid_legal_ssn	Legal SSN validation	Validates against SSA rules

2.1.2 Contact Information

Method	Description	Format
valid_email	Email format validation	user@domain.com
valid_iwcc_email	Email excluding specific domain	Excludes @iwcc.edu
valid_cell_phone	Cell phone format	(123) 456-7890 or similar
valid_phone_without_ext	Phone without extension	Various formats supported
valid_zipcode	US and Canadian zip codes	12345, 12345-6789, or A1A 1A1

2.1.3 Student ID Formats

Method	Description	Pattern
valid_eight_digit_m_number	M followed by 8 digits	M12345678
valid_eight_digit_k_number	K followed by 8 digits	K12345678
valid_eight_digit_s_number	S followed by 8 digits	S12345678
valid_eight_digit_a_number	A followed by 8 digits	A12345678
valid_eight_digit_w_number	W followed by 7 digits	W1234567
valid_nine_digit_w_number	W followed by 8 digits	W12345678
valid_nine_digit_j_number	J followed by 8 digits	J12345678

2.1.4 Numeric Patterns

Method	Description	Pattern
valid_nine_digit_number	Exactly 9 digits	123456789
valid_nine_digit_number_leading_900	9 digits starting with 900	900123456
valid_eight_digit_number	Exactly 8 digits	12345678
valid_seven_digit_number	Exactly 7 digits	1234567
valid_seven_digit_leading_zero_number	7 digits starting with 0	0123456
valid_seven_digit_leading_three_number	7 digits starting with 3	3123456
valid_six_to_eight_digit_no	6 to 8 digits	123456-12345678
valid_five_digit_number	Exactly 5 digits	12345
valid_four_digit_number	Exactly 4 digits	1234
valid_four_digit_pin	4-digit PIN	1234

2.1.5 Text Pattern Validations

Method	Description	Allowed Characters
only_letters_or_spaces	Letters and spaces only	A-Z, a-z, space
only_letters_or_hyphens_or_apostrophes	Letters, hyphens, apostrophes	A-Z, a-z, -, '
only_letters_or_hyphens_or_spaces_or_apostrophes	Letters with common punctuation	A-Z, a-z, -, ', space
only_letters_or_numbers_or_spaces_or_periods	Alphanumeric with periods	Requires both letters AND numbers
only_letters_or_numbers_or_spaces	Alphanumeric	Requires both letters AND numbers
only_letters_or_numbers_or_spaces_or_hyphens	Alphanumeric with hyphens	Requires both letters AND numbers
proper_only_letters_or_numbers_or_spaces	Proper alphanumeric	A-Z, a-z, 0-9, -, space
only_mixed_case_letters	Mixed case letters only	Must have both upper and lower
only_mixed_case_letters_or_numbers_or_spaces	Mixed case alphanumeric	Must have mixed case
only_mixed_case_letters_or_hyphens_or_apostrophes_or_spaces	Mixed case with punctuation	Must have mixed case
only_mixed_case_letters_or_hyphens_or_spaces	Mixed case letters with hyphens/spaces	Must have mixed case

2.1.6 Specialized Validations

Method	Description	Rules
valid_name	Proper name validation	Capital first letter, no titles/prefixes
valid_gpa	GPA validation (0-5 scale)	0.00 to 5.00, up to 2 decimals
valid_gpa_max_six	GPA validation (0-6 scale)	0.00 to 6.00
confirmation	Field confirmation match	Must match another field value

2.2 Frontend (UI) Validation Methods

Frontend validations provide immediate user feedback in the browser. These largely mirror backend validations with some UI-specific additions.

Additional UI-Only Validations:

Method	Description	Format
valid_date	Date format validation	Client-side date validation
valid_us_birth_date	US birth date validation	Valid US birth date format
valid_date_with_age_range	Date with age constraints	Birth date within age range
valid_ssn_ivytech	IvyTech-specific SSN	College-specific SSN rules
valid_eight_digit_j_number	J followed by 7 digits	J1234567
valid_eight_digit_h_number	H followed by 7 digits	H1234567

Note: All backend validation methods listed in section 2.1 are also available for frontend validation except confirmation and valid_nine_digit_number_leading_900 in some cases.

2.3 Validation Implementation Notes

• Reusable Module: The ValidationMethods module should be preserved and extended in the new implementation
• Regex Conversion: The module includes regexp_to_javascript method to convert Ruby regexes to JavaScript for client-side validation
• Consistent Validation: Same validation logic should apply on both frontend and backend for data integrity
• Extensibility: New validation methods can be added to the module following the established pattern

---

3. Field Behaviors

Behaviors define how fields interact with different user roles and application states. Currently, only one behavior per field is supported, but the new implementation should support multiple behaviors per field.

3.1 Required Behavior

Behavior	Description
required	Field must be filled out before submission

3.2 Visibility Behaviors

3.2.1 Application Visibility

Behavior	Description	Use Case
hide_in_application	Hidden during application process	Internal/system fields

3.2.2 Role-Based Visibility After Completion

Behavior	Description	Affected Role
hide_from_student_after_completion	Hidden from student after application submitted	Student
hide_from_high_school_after_completion	Hidden from high school after completion	High School User
hide_from_college_after_completion	Hidden from college after completion	College User

3.2.3 Role-Based Always Hidden

Behavior	Description	Affected Role
hide_from_student_always	Never visible to students	Student
hide_from_high_school_always	Never visible to high school users	High School User

3.2.4 Conditional Visibility with Read-Only

Behavior	Description	Use Case
hide_from_student_until_populated_then_read_only	Hidden until populated, then read-only for student	System-populated fields
hide_from_high_school_until_populated_then_read_only	Hidden until populated, then read-only for HS	System-populated fields

3.3 Read-Only Behaviors

Behavior	Description	Use Case
student_read_only_after_populated	Student can't edit after value entered	Prevent changes to critical data
student_read_only_if_ever_completed	Student can't edit if application ever completed	Lock submitted data

3.4 Behavior Implementation Notes

Current Implementation: Behaviors are stored as an array in the database, allowing for future multi-behavior support.

Methods Available:

• behavior?(behavior) - Check if behavior is set
• set_behavior(behavior) - Add a behavior
• clear_behavior(behavior) - Remove a behavior
• alter_behavior(behavior, value) - Toggle behavior based on value

New Implementation Requirement: Support multiple simultaneous behaviors per field (e.g., a field can be both required and hide_from_student_after_completion).

---

4. CSS Classes

Optional CSS classes for field layout and styling.

CSS Class	Description	Effect
line-break-before	Insert line break before field	Forces field to new row
additional-space-before	Add extra spacing before field	Visual separation
right-justify	Right-align field content	Numeric/currency fields

---

5. Additional Field Attributes

5.1 Field Configuration Attributes

Attribute	Type	Description
internal_name	String	Unique identifier for the field (required)
display_name	String	Label shown to users (required)
hint_text	String	Help text/description shown near field
placeholder	String	Placeholder text inside input
default_value	String/JSON	Default value when field is created
allowed_values	JSON/Method	Array, hash, or helper method name for options
maximum_length	Integer	Maximum character length
minimum_length	Integer	Minimum character length
display_size	Integer	Display width for input field
include_in_reports	Boolean	Whether to include in exports/reports

5.2 Field Associations

Association	Description
associated_field_id	Link to related field for two-way association
confirmation_field_id	Field that must match this field's value
api_option_id	Link to API option for dynamic data loading

---

6. Implementation Requirements for New Form Builder

6.1 Must Support

• ✅ All current field types and UI types
• ✅ All backend and frontend validation methods from ValidationMethods module
• ✅ Multiple behaviors per field (enhancement from current single behavior)
• ✅ All current field attributes and associations
• ✅ CSS class options for layout control
• ✅ Tooltips/hint text for field-level help

6.2 Must Be Extensible

• ✅ Pattern for adding new field types without code changes
• ✅ Pattern for adding new validation methods
• ✅ Pattern for adding new behaviors
• ✅ Documentation for extending each component

6.3 Must Be Reusable

• ✅ Leverage existing ValidationMethods module
• ✅ Maintain compatibility with existing data structures
• ✅ Support both student applications and Active Flow workflows

6.4 Form Builder Dictionary (Critical Requirement)

Critical Requirement: A comprehensive, machine-readable dictionary of all field types, validations, and behaviors that serves as the single source of truth for both the UI and automated tools.

Purpose - Dual Consumption:

1. Human Consumption (Form Builder UI):

   • Display available field types to users building forms
   • Show applicable validations for each field type
   • Present configurable behaviors with descriptions
   • Provide help text and tooltips
   • Enable intelligent form builder interface

2. Machine Consumption (Tools & Migration):

   • Enable automated migration from fixture-based colleges
   • Allow AI-powered tools to understand system capabilities
   • Provide programmatic queryability
   • Support validation and testing tools

The Dictionary Concept:

This isn't just documentation - it's the authoritative data source. The form builder UI doesn't have field types "hard-coded" - it reads them from the dictionary. When we add a new validation method, we add it to the dictionary, and both the UI and migration tools immediately understand it exists.

Similar to how local options work in the current system (centralized data configuration), the dictionary is a structured data source that defines the system's capabilities.

Key Characteristics:

• Structured Data Format: Machine-readable format that can be queried programmatically

• Comprehensive Coverage: All field types, UI types, validations, and behaviors defined with:

  • Human-readable descriptions for UI display
  • Compatibility rules (which validations work with which field types)
  • Conflict rules (which behaviors can't be combined)
  • Role-specific attributes where applicable

• Version Controlled: Part of the codebase, updated when capabilities change

• Queryable: The form builder UI queries it to populate dropdowns and configurators; migration tools query it to validate mappings

• Self-Documenting: Descriptions in the dictionary serve as both UI help text and technical documentation

Usage Scenarios:

In the Form Builder UI: When a user drags a text field onto their form and clicks to configure validations, the UI shows only validations that apply to text fields - populated from the dictionary. Tooltips and help text come from the dictionary descriptions.

In Migration Tools: When analyzing custom code that uses email validation on a text field, the tool queries the dictionary to confirm this is a supported combination before creating the mapping.

Deliverable Requirements:

• Dictionary data in a structured, machine-readable format (vendor's choice of implementation)
• Programmatic interface for querying dictionary contents
• UI components that consume the dictionary to drive field pickers, validation selectors, and behavior configurators
• Documentation on extending the dictionary when new capabilities are added
• Validation mechanism to ensure dictionary accurately reflects implemented capabilities

6.5 Validation Pattern Example

# Example from ValidationMethods module that should be preserved
def valid_email(email)
  return true unless email.present?
  !!(email =~ /\A[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
end

# JavaScript conversion for frontend validation
regexp_to_javascript(/\A[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
# => "^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"

---

7. Data Compatibility Requirements

The new form builder must maintain compatibility with existing data:

• ApplicationField records and their attributes
• ApplicationFieldValue records storing student data
• ApplicationFieldGroup organization
• Existing fixture files during migration period
• Backwards compatibility mode for colleges not yet migrated

---

8. Future Enhancements (Out of Scope for Initial Implementation)

These are potential future additions that should be considered in the architecture but not required for initial delivery:

• Rich text editor field type
• File upload with preview and drag-drop
• Digital signature capture
• Calculated/computed fields
• Conditional field visibility based on complex rules
• Field dependency visual mapping
• Custom regex validation builder
• Multi-step form wizards with progress indicators
• Field templates/presets for common patterns

---

Document Version: 1.0 Last Updated: 2025-10-04 Related Document: Request for Proposal - Dynamic Form Builder for Student Applications

dynamic-form-builder-rfp.md

Request for Proposal: Dynamic Form Builder for Student Applications

1. Executive Summary

1.1 Project Overview

We are seeking a Ruby on Rails development partner to build a comprehensive Dynamic Form Builder system that will replace our current custom student application implementation. This system will allow us to create and manage student application forms through a UI interface instead of writing custom fixture files and theme overrides.

1.2 Current State

• Custom College Student Applications built via fixture files
• Limited field types with custom HTML/JavaScript overrides in app/views/themes/<college>/
• Logic handled in CollegeStudentApplicationsController
• Performance optimizations in place that must be maintained
• Manual version control processes for form definitions

1.3 Desired Outcome

• Modern, UI-driven form builder
• Backwards compatibility with existing applications
• Expanded field types and functionality
• Version control for forms with audit trail (whodunnit)
• Improved maintainability and reduced custom code

2. Technical Requirements

2.1 Architecture Requirements

2.1.1 Backwards Compatibility

• New implementation must coexist with existing system
• Controlled rollout via college-specific local options
• Existing data models must remain functional
• Current CollegeStudentApplicationsController preserved for legacy colleges

2.1.2 Data Model Extensions

• Build on existing models: CollegeStudentApplication, CollegeStudentApplicationPage, ApplicationField, ApplicationFieldGroup, ApplicationFieldValue
• Add metadata tables for new functionality without breaking existing structure
• Code Reuse: All existing code should be leveraged where possible, but must be properly refactored and integrated
• Reference implementation available in db/fixtures/192_ivytech.rb

2.1.3 Performance Requirements

• No performance regressions from current optimized controller
• Maintain existing query optimization patterns
• Consider caching strategies for form definitions

2.2 Core Functionality

2.2.1 Dynamic Form Builder UI (Student Applications)

• Page Management: Create, edit, and organize multiple pages within an application
• Field Management:
  • Simple interface for adding fields to a specific page
  • Drag-and-drop interface for arranging and positioning fields on the page
• Field Type Selection: UI-driven field type picker populated from Form Builder Dictionary
• Multi-Column Layout Support:
  • Flexible row and column arrangement for fields
  • Common patterns: 3-field rows (First Name, Middle Name, Last Name)
  • Responsive grid system for optimal field grouping
  • Visual layout tools for arranging short fields on same row
• Field Configuration: Individual field settings, validation rules, display options
  • Validation selector showing only applicable validations for selected field type
  • Behavior configurator with descriptions and help text
  • All options driven by Form Builder Dictionary (see Appendix A Section 6.4)
• Preview Mode: Real-time preview of student-facing form with mobile/desktop views

2.2.2 Field Types, Validations, and Behaviors

See Appendix A for complete technical specifications.

Current Implementation Requirements:

• All existing field types (6 data types, 12 UI types) must be supported - see Appendix A Section 1
• All validation methods must be preserved and leveraged from existing ValidationMethods module - see Appendix A Section 2
• Field behaviors must support multiple simultaneous behaviors (enhancement from current single behavior) - see Appendix A Section 3
• All field configuration attributes and associations must be maintained - see Appendix A Section 5

Required Analysis: Comprehensive audit of existing custom implementations in app/views/themes/ folders to identify common patterns that should become standard field types.

Enhanced Features (beyond current capabilities):

• Enhanced Select2 Components - Support for large datasets and dynamic data sources:

  • Ajax lazy loading for performance with large lists
  • Autocomplete/search functionality
  • Multi-select capability
  • EthosAPI Integration: Direct integration with existing EthosAPI endpoints (our app already fetches data from Ethos; form builder should allow selecting these as data sources for dropdowns)
  • CSV Dataset Support: Allow administrators to populate large option lists via CSV import (id, value pairs)
  • Configurable data source per field (static list, CSV-imported list, or EthosAPI resource)

• Static text/HTML content blocks

• Confirmation dialogs/popups

• Advanced file upload with preview

• Calculated/computed fields

• Tooltips: Configurable help tooltips for individual fields

• Multi-column layout support in form rendering

2.2.3 Field Dependencies

• Show/hide fields based on other field values
• Dynamic required field status (field becomes required only if certain conditions are met)
• Support for multiple conditions (AND/OR logic - e.g., show field if option A is selected AND field B is filled)
• Visual dependency mapping in builder interface

2.2.4 Version Control System

• Draft/Published states for form definitions
• Rollback capabilities for form definitions
• Change tracking and audit trail for form modifications
• Authorship Tracking (Whodunnit): Complete audit trail of who made what changes to form definitions
• Preview unpublished versions before making them live

2.2.5 Extensibility Framework

Critical Requirement: Design patterns for future field type additions must be documented and implemented.

• Clear interface/pattern for adding new field types
• Extensible validation framework
• Plugin-like architecture for custom fields
• Documentation for adding new field types independently
• Validation rule extension system

2.2.6 Active Flow Integration (Future Phase - Out of Scope)

Note: Active Flow workflow integration is outside the scope of this project. However, the core form builder should be designed with extensibility in mind to enable future integration with workflow systems.

Future Vision: The form builder could eventually be extended to support:

• Form execution outside student application context
• Integration with Active Flow workflow system
• Form rendering within workflow steps

Current Project: Focus is exclusively on student application forms.

2.3 Integration Requirements

2.3.1 Existing System Integration

• Maintain CollegeStudentApplicationSchemaPresenter compatibility
• Support existing K6 performance testing metadata endpoints
• Preserve current authorization patterns (CanCanCan)
• Active Admin Integration: Form builder data must be visible and browsable through Active Admin interface (read-only views, no edit functionality required)

2.3.2 UI/UX Standards

• Use existing Rails component library
• Maintain current design system consistency
• Mobile-Responsive Design - Critical Requirement:
  • New application layout required: Current layout does not support mobile devices correctly and must be redesigned
  • Mobile-responsive for both administrator (form builder) interface AND student-facing forms
  • Full mobile compatibility for students completing applications on mobile devices
  • Touch-friendly interface elements throughout
  • Responsive grid system that adapts multi-column layouts to mobile screens
  • Optimized form flow for mobile completion
• Cross-Device Compatibility: Consistent experience across desktop, tablet, and mobile
• Accessibility Compliance (WCAG 2.1 AA): Our application was recently audited and validated for accessibility. All new pages and functionality must maintain this compliance level.

2.4 Data Protection & Validation

• Prevent deletion of fields with existing student data
• Warning system for field modifications with data impact
• Backup and recovery procedures

3. Technical Constraints

3.1 Technology Stack

• Ruby on Rails (current version in use)
• Existing database schema (PostgreSQL)
• Current authentication/authorization system
• Existing CSS/JavaScript frameworks

3.2 Code Quality Standards

• Follow existing Ruby style guide (2-space indentation, snake_case)
• RuboCop Integration: Consider using RuboCop for automated style guide enforcement
• RSpec Test Coverage: Comprehensive test suite required for all controllers and models
• Minimum 90% test coverage for new code
• Code review process compliance
• Documentation standards

3.3 Deployment Requirements

• Zero-downtime deployment capability
• Database migration safety
• Feature flag compatibility
• Staging environment testing

4. Deliverables

4.1 Technical Deliverables

• Complete form builder UI application
• Form Builder Dictionary (machine-readable YAML/JSON) - See Appendix A Section 6.4
  • Defines all field types, validations, and behaviors
  • Drives UI field pickers and configurators
  • Enables future migration tools
  • Single source of truth for capabilities
• Database migrations and schema updates
• Comprehensive test suite (RSpec)
• API documentation
• Admin interface integration
• Performance optimization report

4.2 Documentation Deliverables

• Technical architecture documentation
• User guide for form builders
• Developer guide for extending field types, validations, and behaviors (per Appendix A requirements)
• Migration guide from legacy system
• API reference documentation
• Deployment guide

4.3 Analysis Deliverables

• Custom field type audit report
• Performance impact analysis
• Security assessment report
• Browser compatibility matrix

5. Suggested Project Phases

Note: Vendors should propose their own timeline and project duration based on their assessment of the requirements.

Phase 1: Analysis & Planning

• Codebase analysis for custom field patterns
• Technical architecture design
• Database schema planning
• Performance benchmarking baseline

Phase 2: Core Infrastructure

• New controller implementation
• Database schema updates
• Basic form builder UI
• Local option integration

Phase 3: Field Type Implementation

• Standard field types development
• Custom field types from analysis
• Field dependency system
• Validation framework

Phase 4: Versioning & Advanced Features

• Version control system
• Publishing workflow
• Data protection measures
• Performance optimization

Phase 5: Integration & Testing

• Backwards compatibility testing
• Performance testing
• Security testing
• Comprehensive QA by vendor team
• User acceptance testing

Phase 6: Documentation & Deployment

• Documentation completion (including extensibility patterns)
• Production deployment
• Knowledge transfer
• Post-launch support

6. Proposal Requirements

6.1 Technical Response

Please provide:

• Technical approach and architecture
• Performance optimization strategy
• Testing approach and coverage plans
• Risk assessment and mitigation strategies

6.2 Team & Experience

• Team composition and roles
• Ruby on Rails experience (years, project examples)
• Similar form builder project experience
• Availability and time commitment
• Communication and project management approach

6.3 Timeline & Budget

• Proposed project timeline and duration (vendors must provide their own estimates)
• Detailed project schedule with milestones
• Resource allocation plan
• Fixed price or time & materials pricing
• Payment schedule proposal
• Maintenance and support options

6.4 Quality Assurance

Critical Requirement: Complete QA workflow must be provided by vendor before delivery.

• Full QA Coverage: Vendor must provide comprehensive QA testing before delivery to us
• QA Bottleneck Solution: We require a complete testing workflow as QA is currently a bottleneck
• Testing Requirements:
  • Comprehensive RSpec test suite (controllers and models)
  • Manual testing across all browsers and devices
  • Performance testing and benchmarking
  • Security testing and vulnerability assessment
  • User acceptance testing simulation
• Delivery Standards: All features must be fully tested and QA-approved before handoff
• Code review processes
• Bug fixing and warranty terms
• Performance guarantees
• Security compliance measures

7. Evaluation Criteria

Proposals will be evaluated on:

• Technical Approach: Architecture, scalability, performance
• Experience & Capability: Team expertise, similar projects
• Timeline & Budget: Realistic schedule, competitive pricing
• Quality Assurance: Testing approach, code quality
• Communication & Support: Project management, ongoing support

8. Next Steps

1. Proposal submission and initial review
2. Technical interviews with shortlisted vendors
3. Reference checks and due diligence
4. Final selection and contract negotiation
5. Project kickoff and onboarding

---

Appendices

Appendix A: Technical Specifications - Field Types, Validations, and Behaviors

• Available in: appendix-a-technical-specifications.md
• Contains detailed specifications for all current field types, UI types, validation methods, and behaviors
• Required reading for all vendors to understand the complete technical scope

---

This RFP represents a strategic investment in modernizing our student application system. We look forward to partnering with a development team that shares our commitment to quality, performance, and user experience.

internal-proposal-dynamic-form-builder.md

Internal Proposal: Dynamic Form Builder System

Modernizing College Student Application Management

Document Type: Internal Strategic Proposal Date: October 4, 2025 Prepared By: Development Team Status: Draft for Executive Review

---

Executive Summary

The Problem

We currently build custom student applications for each college by:

• Writing fixture files (code-based configuration)
• Creating custom HTML/JavaScript for each college in theme folders
• Manual version control with no audit trail
• Time-consuming development cycle for each new college

Impact: High development costs, slow onboarding for new colleges, difficult maintenance, no self-service capability.

The Solution

Build a Dynamic Form Builder - a UI-driven system that allows us to create and manage student application forms through a web interface instead of writing code.

Project Approach

Phase 1: Form Builder Implementation (This Proposal)

• Build the core form builder system
• Target: Enable onboarding new colleges without custom code
• Timeline: ~3 months (vendor estimate pending)
• Deliverable: Working form builder for new college implementations

Phase 2: Migration Tool (Separate Future Proposal)

• Tool to migrate existing colleges from fixture files to form builder
• Addresses concern about maintaining dual systems long-term
• Enables gradual migration of existing colleges

Key Benefits

• ✅ No JIRA tickets for application changes: Our staff can configure applications directly through the UI, eliminating development workflow bottleneck
• ✅ Faster college onboarding: Hours instead of weeks for new colleges
• ✅ Self-service capability: Future potential for colleges to manage their own forms
• ✅ Better version control: Built-in audit trails for form definition changes and rollback capability
• ✅ Maintainability: Centralized codebase, not scattered custom implementations

Investment

• Vendor development costs: TBD (seeking proposals)
• Internal time: Architecture review, QA validation, documentation
• Timeline: Approximately 3 months for Phase 1

Recommendation

Proceed with RFP process to solicit vendor proposals for Phase 1 (Form Builder Implementation). Phase 2 (Migration Tool) to be evaluated after Phase 1 completion.

---

1. Current State Analysis

1.1 How We Build Applications Today

For each new college, we:

1. Write Fixture Files (db/fixtures/192_ivytech.rb)

   • Define application structure in Ruby code
   • Configure field types, validations, behaviors
   • No UI, requires developer knowledge

2. Create Custom Theme Overrides (app/views/themes/<college>/)

   • Custom HTML for unique layouts
   • Custom JavaScript for special behaviors
   • College-specific styling

3. Deploy and Test

   • Manual testing required
   • No preview capability for stakeholders
   • Changes require code deployment

1.2 Current Limitations

Issue	Impact	Frequency
No Version Control	Can't preview changes before publishing	When changes needed
No Audit Trail	Can't track who made what changes to form definitions	Ongoing
Code-Based Configuration	Requires JIRA ticket and developer for every change	Every college, every change
Manual Testing	Slow feedback loop	Every change
No Preview Mode	Stakeholders can't review before launch	Every new college
Scattered Customizations	Hard to find and maintain college-specific code	Ongoing maintenance

1.3 Existing Technical Debt

• ~100 college-specific theme folders with custom code
• Limited field types requiring custom implementations per college
• No reusable patterns for common form elements
• Performance optimizations scattered across custom code
• Validation logic duplicated across implementations

---

2. Proposed Solution: Dynamic Form Builder

2.1 What Is It?

A web-based form builder that allows us to:

• Visually design application forms with drag-and-drop
• Configure fields through UI instead of code
• Preview forms in real-time before publishing
• Version control form definitions (work on drafts, publish when ready)
• Track changes with complete audit trail of form definition modifications
• Publish on demand when ready for students

2.2 Key Capabilities

Form Design

• Visual page builder with multi-column layouts
• Field library (text, select, date, file upload, etc.)
• Drag-and-drop field arrangement
• Field dependencies (show/hide based on values)
• Configure validation rules for each field (email format, required, phone number, etc.)

Version Management

• Draft/published states for form definitions
• Work-in-progress versions can be developed without affecting live forms
• Preview unpublished versions
• Rollback capability for form definitions
• Change tracking (who modified form definition, what changed, when)

Technical Features

• Mobile-responsive student experience
• Performance optimized (no regression from current system)
• Backwards compatible (existing colleges unaffected)
• Extensible (easy to add new field types)
• Reuses existing validation logic

2.3 How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Form Builder UI                           │
│  (Used by our team to configure college applications)       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Form Configuration                         │
│         (Stored in database, not code files)                │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│               Student-Facing Application                     │
│        (Rendered dynamically from configuration)            │
└─────────────────────────────────────────────────────────────┘

---

3. Project Scope

3.1 Phase 1: Form Builder Implementation (This Project)

Goal: Build form builder system usable for all new college onboarding.

In Scope:

• ✅ Visual form builder UI
• ✅ All current field types (text, select, date, etc.)
• ✅ All current validation rules (SSN, email, phone, etc.)
• ✅ Field behaviors (required, visibility, read-only)
• ✅ Multi-column layouts
• ✅ Version control and publishing workflow
• ✅ Audit trail (whodunnit)
• ✅ Mobile-responsive student forms
• ✅ Backwards compatibility with existing fixture-based colleges
• ✅ Performance parity with current system
• ✅ Comprehensive testing and QA
• ✅ Documentation for extending system (adding new field types)

Out of Scope for Phase 1:

• ❌ Active Flow workflow integration (separate future phase)
• ❌ Migration of existing colleges from fixtures (Phase 2)
• ❌ College self-service (future capability)
• ❌ Advanced features (digital signatures, calculated fields) - nice-to-have only

Success Criteria:

1. Can build a complete college application using only the form builder UI
2. No custom code or JIRA tickets required for standard college application configuration
3. Performance matches or exceeds current fixture-based approach
4. Our staff can make application changes directly without developer involvement

3.2 Phase 2: Migration Tool (Future Project - Separate Proposal)

Goal: Migrate existing fixture-based colleges to form builder.

Why Separate?:

• Phase 1 proves the form builder works for new colleges
• Gives us operational experience before migrating production colleges
• Different risk profile (production vs. new implementations)
• Allows us to refine form builder based on real usage

To Be Detailed In Separate Document:

• Migration strategy and approach
• Risk assessment and mitigation
• Pilot college selection
• Rollback procedures
• Timeline and resources

9. Success Metrics

9.1 Project Success Criteria

Functionality:

• ✅ All current field types supported
• ✅ All validation rules working
• ✅ Version control operational
• ✅ Mobile responsive
• ✅ Can build complete application without code

Performance:

• ✅ Form rendering time ≤ current system
• ✅ No increase in database queries
• ✅ Page load times within 10% of current

Quality:

• ✅ 90%+ test coverage
• ✅ Zero critical bugs at launch
• ✅ Cross-browser compatibility (Chrome, Safari, Firefox, Edge)

9.2 Business Success Metrics (6 months post-launch)

Primary Goal: Move Application Configuration Out of Development Workflow

• No JIRA tickets required for application creation or standard configuration changes
• Our staff can configure applications directly through the UI
• Zero custom code deployments for standard form changes
• 100% of new colleges using form builder
• Developer time freed for actual feature development (not custom implementations)

---

10. Future Opportunities

10.1 Phase 2: Migration Tool

Migrate existing fixture-based colleges to form builder (separate proposal to follow).

10.2 Phase 3: Active Flow Integration

Extend form builder to workflow steps, eliminating fixture files for workflow configuration.

10.3 Phase 4: College Self-Service

Enable colleges to manage their own application forms with our oversight (future capability).

10.4 Additional Enhancements

• A/B testing for form optimization
• Analytics on field completion rates
• Conditional logic visual designer
• Form templates library
• Multi-language support

migration-approach.md

Phase 2: Migration to Form Builder

Strategic Approach

Document Type: Strategic Concept - Internal Date: October 4, 2025 Status: Draft for Discussion Prerequisite: Phase 1 (Form Builder Implementation) must be complete

---

Executive Summary

After Phase 1 delivers the form builder, we'll have two systems: the new UI-driven form builder for new colleges, and the legacy fixture-based system for existing colleges. This document outlines a strategic approach to eventually migrate existing colleges to the form builder.

The Opportunity: An AI-powered migration approach that can analyze existing custom implementations and automatically map them to form builder capabilities.

The Decision Point: When and whether to migrate specific colleges will be a management decision based on business priorities.

---

1. The Migration Challenge

1.1 Current State

We have 60+ colleges with applications defined through:

• Fixture files (structured data, easy to migrate)
• Custom theme views (HTML/CSS/JavaScript requiring analysis)
• Active View fragments (admin-editable content)

1.2 The Complexity

Some colleges use only standard fields and have minimal customization. Others have extensive custom code implementing college-specific behaviors. The migration challenge isn't the data - it's understanding what the custom code does and mapping it to form builder capabilities.

---

2. AI-Powered Migration Concept

2.1 The Core Idea

Using AI (Claude) with properly crafted instructions and prompts, we can analyze a college's custom implementation and:

1. Automatically implement what's already supported in the form builder
2. Provide recommendations for implementing missing features in a general, reusable way

The AI doesn't just copy code - it understands intent by reading:

• Custom theme files (what was implemented)
• Git commit history (when and why changes were made)
• JIRA tickets (business requirements that drove the customization)
• Form Builder Dictionary (what capabilities exist in the new system)

2.2 Why This Works

Modern AI can perform semantic analysis. It understands that custom JavaScript implementing conditional field visibility is the same pattern across colleges, even if the code looks different. With the Form Builder Dictionary as reference, it can:

• Recognize patterns
• Map to existing capabilities
• Identify gaps where new features are needed
• Distinguish between reusable patterns and one-off workarounds

2.3 The Output

For each college, the AI generates:

• Migration plan with automatic mappings
• Warnings about unsupported features requiring decisions
• Recommendations for new form builder features when patterns appear across multiple colleges

---

3. When to Migrate

3.1 Likely Approach

Migration will probably occur on-demand when:

• A college requests changes to their application
• It's a good opportunity to migrate rather than maintain custom code
• Business value justifies the migration effort

Rather than proactively migrating all colleges, we migrate as needs arise.

3.2 Management Decision

Whether to:

• Migrate colleges opportunistically (when they request changes)
• Migrate colleges proactively (our initiative)
• Or some combination

This is a business decision to be made by management, not predetermined by this proposal.

---

4. Example: Conditional Field Logic

Current Reality: Multiple colleges implement custom JavaScript for conditional logic - showing or hiding fields based on other field values.

Form Builder Requirement: This is common enough that conditional field visibility should be a core form builder feature in Phase 1, not something to migrate later.

Migration Impact: If the form builder supports conditional fields from the start, migrating colleges that use this pattern becomes straightforward - the AI maps their custom code to the built-in feature.

This illustrates why the Form Builder Dictionary is critical: it documents what's supported, so migration tooling knows what's available.

---

5. The Migration Process (High-Level)

5.1 Analysis Phase

AI analyzes the college's implementation:

• Reads all custom theme files
• Analyzes git history for context
• Reads JIRA tickets for business requirements
• Consults Form Builder Dictionary for available capabilities

5.2 Mapping Phase

AI categorizes each customization:

• Supported: Direct mapping to form builder capability
• Unsupported but common: Recommend adding as new form builder feature
• Unsupported and unique: Flag for manual review/decision

5.3 Execution Phase

Based on the migration plan:

• Automatic implementations created where mapping is clear
• Recommendations presented for decision
• Manual review for flagged items

---

6. Benefits of This Approach

Flexibility: Migrate colleges when it makes business sense, not on a fixed schedule

Learning: Each migration improves our understanding of common patterns and missing features

Feature Discovery: Migration surfaces opportunities to enhance the form builder with capabilities that benefit all colleges

Risk Reduction: AI-assisted rather than fully automated means human oversight on complex cases

---

7. Prerequisites

7.1 From Phase 1

• Form builder fully functional and proven with new colleges
• Form Builder Dictionary complete and comprehensive
• Extensibility framework for adding new capabilities
• Common patterns already implemented (like conditional field visibility)

7.2 For Migration

• AI integration (Claude API or similar capability)
• Access to git history and JIRA tickets (already available)
• Clear decision process for approving new features identified during migration

---

8. Success Indicators

We'll know the migration approach is viable when:

• AI can successfully analyze a pilot college
• Automatic mappings are accurate (requiring minimal correction)
• Recommendations for new features are sensible and reusable
• Migration is faster than manual rebuilding

---

9. Open Questions

These strategic decisions remain open:

1. Migration Timing: Opportunistic (when colleges request changes) vs. proactive (our initiative)?
2. Prioritization: If proactive, what criteria determine migration order?
3. Resource Allocation: How much effort to invest in migration vs. new features?
4. Feature Approval: Who decides which AI-recommended features to implement?

---

10. Next Steps

Not Now: This is Phase 2 - we don't start until Phase 1 is complete and proven.

When Phase 1 Completes:

1. Evaluate if migration is still a priority
2. Test AI analysis with one pilot college
3. Assess feasibility based on actual results
4. Make strategic decisions about timing and approach
5. Allocate resources if proceeding

---

Conclusion

AI-powered migration is a viable approach that offers flexibility and learning opportunities. The key is having the Form Builder Dictionary from Phase 1 as the source of truth about capabilities. When and how extensively we migrate is a strategic decision to be made later, based on business priorities and proven results from Phase 1.

---

Document Version: 1.0 Last Updated: 2025-10-04 Author: Development Team Status: Strategic Concept for Discussion