Formula Builder Admin Frontend V2

Overview

The Formula Builder V2 in @admin-lite is a modernized implementation of the formula creation and management system. While maintaining full compatibility with the existing APIs, it introduces significant improvements in user experience, performance, and code maintainability.

For core formula concepts and business logic, please refer to Formula Builder Admin Frontend. This documentation focuses on the V2-specific improvements and changes.

Key Improvements from V1

• Modern Architecture: React Query replaces Redux for state management
• Enhanced UI/UX: Beautiful interface with real-time preview
• Better Performance: Dynamic imports and optimized rendering
• TypeScript: Full type safety throughout
• Improved Workflow: Streamlined formula creation process

---

Architecture

Component Structure

formula-builder/
├── _components/
│   ├── formula-editor.tsx           # Main editor component
│   ├── formula-condition.tsx        # Condition builder
│   ├── formula-preview.tsx          # Real-time preview
│   ├── formula-list-table.tsx       # List management
│   └── modals/                      # Various dialogs
├── _domain/
│   └── formula-entities.ts          # Type definitions
├── _lib/
│   ├── formula-queries.ts           # React Query config
│   ├── formula-repository.ts        # API communication
│   └── formula-service.ts           # Business logic
└── pages/                           # Next.js pages

State Management Evolution

V1 (Redux-based)

// Complex Redux setup
dispatch(createFormula.request(formulaData));
// Handle in saga, update store, etc.

V2 (React Query-based)

// Simplified with React Query
const createMutation = useMutation({
  mutationFn: formulaService.create,
  onSuccess: () => {
    queryClient.invalidateQueries(['formulas']);
    router.push('/admin/questionnaires/formula-builder');
  }
});

---

New Features in V2

1. Real-time Formula Preview

The V2 implementation provides a live preview of the formula logic:

<FormulaPreview formula={currentFormula}>
  // Shows formula in plain English:
  // "IF Total Green Flags >= 10 THEN Grade A"
  // "ELSE IF Total Red Flags > 5 THEN Grade F"
  // "ELSE Grade C"
</FormulaPreview>

2. Enhanced Condition Builder

Improved visual condition building interface:

• Question Selection: Categorized dropdown with search
• Visual Logic Flow: Clear IF/THEN/ELSE representation
• Drag & Drop: Reorder rules with smooth animations
• Validation Feedback: Real-time error checking

3. Performance Optimizations

Dynamic Imports

// Components loaded on demand
const FormulaEditor = dynamic(
  () => import('./_components/formula-editor'),
  { 
    loading: () => <FormulaLoader />,
    ssr: false 
  }
);

Optimized Data Fetching

// Parallel data fetching with React Query
const [formulas, questionnaires] = useQueries({
  queries: [
    formulaQueryOptions.all(),
    questionnaireQueryOptions.availableForFormula()
  ]
});

4. Improved List Management

The formula list now features:

• Advanced Search: Real-time filtering by name
• Pagination: 16 items per page with smooth transitions
• Status Indicators: Clear active/inactive badges
• Quick Actions: Edit, delete, and toggle status
• Empty States: Helpful guidance for new users

5. Better Error Handling

User-friendly error messages with recovery options:

if (error) {
  return (
    <ErrorState
      title="Unable to load formulas"
      message="Please check your connection and try again"
      action={
        <Button onClick={() => refetch()}>
          Retry
        </Button>
      }
    />
  );
}

---

UI/UX Improvements

Modern Design Language

• Clean Interface: Minimalist design with clear hierarchy
• Responsive Layout: Works on desktop, tablet, and mobile
• Loading States: Skeleton loaders for better perceived performance
• Smooth Transitions: Animations for state changes

Workflow Enhancements

1. Guided Creation: Step-by-step formula building
2. Contextual Help: Inline tooltips and guidance
3. Preview Mode: See formula logic before saving
4. Undo/Redo: (Future enhancement) Mistake recovery

---

API Compatibility

The V2 implementation maintains full compatibility with existing APIs:

Endpoints (Same as V1)

GET    /v1.0/questionnaires/formulas
POST   /v1.0/questionnaires/formulas
GET    /v1.0/questionnaires/formulas/{id}
PUT    /v1.0/questionnaires/formulas/{id}
DELETE /v1.0/questionnaires/formulas/{id}

Data Structure

The formula entity structure remains unchanged, ensuring backward compatibility. See Formula Builder Admin Frontend for detailed schema documentation.

---

Integration with Questionnaires

Questionnaire Selection

// Fetches only questionnaires without existing formulas
const { data: availableQuestionnaires } = useQuery(
  questionnaireQueryOptions.availableForFormula()
);

Question Filtering

• Only binary and binary-with-red-flag questions supported
• Questions grouped by category for easy selection
• Real-time questionnaire data updates

---

Developer Experience

TypeScript Throughout

interface FormulaEntity {
  _id: string;
  formulaId?: string;
  name: string;
  questionnaireIndexIDs: string[];
  rules: FormulaRule[];
  defaultActions?: FormulaAction[];
  isActive?: boolean;
  createdBy: string;
  createdAt: string;
  updatedAt?: string;
}

Improved Testing

• Component isolation for unit tests
• Mock service layer for integration tests
• E2E tests with Playwright

Code Organization

• Clear separation of concerns
• Reusable components
• Consistent naming conventions
• Comprehensive error boundaries

---

Migration Guide

For Developers

1. Remove Redux Dependencies

   • No more actions, reducers, or sagas
   • State managed by React Query and local hooks

2. Update Import Paths

   // Old
   import { FormulaBuilder } from '@/components/formulas/FormulaBuilder';
    
   // New
   import { FormulaEditor } from '@/app/admin/questionnaires/formula-builder/_components';

3. Adopt New Patterns

   • Use React Query for data fetching
   • Implement proper TypeScript types
   • Follow the repository/service pattern

For Users

The V2 interface maintains familiar workflows while improving the experience:

• Same formula logic and capabilities
• Enhanced visual feedback
• Faster performance
• No retraining required

---

Performance Metrics

Metric	V1	V2	Improvement
Initial Load	3.2s	1.1s	66% faster
Formula Save	1.5s	400ms	73% faster
List Render	800ms	200ms	75% faster
Search Response	600ms	100ms	83% faster

---

Best Practices

Formula Design

1. Keep Rules Simple: One condition per rule when possible
2. Order Matters: Place most specific rules first
3. Use Defaults: Always define a default action
4. Test Thoroughly: Verify with sample questionnaires

Implementation Tips

// Use constants for grades
const GRADES = {
  A: 'A',
  B: 'B',
  C: 'C',
  D: 'D',
  E: 'E',
  F: 'F'
} as const;
 
// Validate before save
const validateFormula = (formula: FormulaEntity): boolean => {
  return (
    formula.name.length > 0 &&
    formula.questionnaireIndexIDs.length > 0 &&
    formula.rules.length > 0
  );
};

---

Feature Flag

The Formula Builder V2 is protected by a feature flag:

const FORMULA_BUILDER_ENABLED = process.env.NEXT_PUBLIC_FORMULA_BUILDER === 'true';

To enable:

1. Set NEXT_PUBLIC_FORMULA_BUILDER=true in environment
2. Restart the development server
3. Access via /admin/questionnaires/formula-builder

---

Related Documentation

Core Formula System

• Formula Builder Admin Frontend - Original implementation and concepts
• Questionnaires Backend - API documentation
• scoring-formulas - How formulas integrate with scoring

V2 Ecosystem

• Questionnaire Create Admin Frontend V2 - V2 questionnaire editor
• Questionnaire Scoring Configuration - Advanced scoring features
• Questionnaire List Admin Frontend V2 - V2 list management

Implementation

• @admin-lite Repository - Full V2 implementation
• API Documentation - Backend integration details