bulk-questionnaire-upload/frontend/README.md

mForm Bulk Upload Frontend

About the Frontend

This frontend is a modern Angular application for bulk uploading, validating, parsing, and managing questionnaire forms (in Excel format). It provides a user-friendly interface for users to drag-and-drop or browse files, validate them, parse them for preview, upload them to the backend, and view/manage parsed forms and their details.

Main Features

• Bulk Upload: Drag-and-drop or select multiple Excel files for upload.
• Parse Only: Parse Excel files to preview JSON schema without saving to database.
• Validation: Validate all selected files before uploading to ensure correct format and content.
• Form Management: View a list of all uploaded forms, search by title, and delete individual or all forms.
• Form Details: Click on a form to view its questions, options, and metadata in a modal dialog.
• Schema Viewer: Interactive modal for viewing parsed form schemas with structured display.
• Update Form: Update an existing form by selecting a new Excel file, preserving its ID and history.
• Responsive UI: Built with Angular Material for a clean, modern, and responsive user experience.
• Progress Tracking: Real-time progress bars for validation, parsing, uploading, and deletion operations.
• Error Handling: Comprehensive error messages with suggestions for fixing issues.

Key Components

• Navbar: Displays the application title and navigation bar.
• Search: Allows searching forms by title.
• Upload: Handles file selection, validation, parsing, upload, and displays the list of forms and their details.

Project Structure

• src/app/components/navbar/ - Navigation bar component
• src/app/components/search/ - Search bar component
• src/app/components/upload/ - Main upload and form management component
• src/app/services/ - Services for form parsing, preview, and backend API communication
• src/app/models/ - TypeScript interfaces for form and question data

Backend Integration Points

This document outlines where and how the frontend communicates with the backend API for easy maintenance and future updates.

Main Integration Service

FormService (src/app/services/form.service.ts)

This Angular service encapsulates all HTTP communication with the backend API. It is the single source of truth for API endpoints used by the frontend.

Endpoints Used:

• POST /api/validate — Validate a form file before upload
• POST /api/forms/parse — Parse Excel file and return JSON schema without saving
• POST /api/upload — Upload a form file (single or multiple)
• GET /api/forms — Fetch all uploaded forms
• GET /api/forms/:formId — Fetch details for a specific form
• PUT /api/forms/:formId/update — Update a specific form with a new file
• DELETE /api/forms/:formId — Delete a specific form
• DELETE /api/forms — Delete all forms

Service Methods:

• validateFile(file: File)
• parseFile(file: File)
• uploadFile(file: File)
• uploadFiles(files: File[])
• getAllForms()
• getFormById(formId: string)
• updateForm(formId: string, file: File)
• deleteForm(formId: string)
• deleteAllForms()

Components Using Backend Integration

UploadComponent (src/app/components/upload/upload.component.ts)

• Uses FormService to:
  • Validate files before upload
  • Parse files for schema preview
  • Upload files
  • Fetch the list of forms
  • Update a form with a new file (update button, file picker, and update logic)
  • Delete individual forms
  • Delete all forms
  • Fetch form details for preview

Schema Viewer Modal

• Interactive modal component for viewing parsed schemas
• Displays form metadata, questions structure, and raw JSON
• Provides copy to clipboard and download functionality
• Keyboard shortcuts (ESC to close)

NavbarComponent (src/app/components/navbar/navbar.component.ts)

• Indirectly uses backend data via FormPreviewService, which is populated by UploadComponent using FormService.

How to Update Backend Endpoints

• All backend API URLs are defined in FormService as apiUrl.
• To change the backend base URL or endpoints, update FormService accordingly.
• If new endpoints are added to the backend, add corresponding methods to FormService and use them in components as needed.

Maintenance Tips

• Keep all backend API calls centralized in FormService for consistency and easy updates.
• Avoid direct HTTP calls in components; always use the service.
• Update this documentation whenever new integration points are added.

Update Flow

To update an existing form:

• Click the yellow update (refresh) icon next to a form in the list.
• Select a new Excel file (XLS/XLSX) from your computer.
• The file is sent to the backend, which updates the form in place (preserving its ID and history).
• The UI will reload the form list and show the updated details.

This feature uses the backend endpoint PUT /api/forms/:formId/update and the updateForm method in FormService.

Parse Only Flow

To preview a form schema without saving:

• Select Excel files using drag-and-drop or file browser.
• Click the "Parse Only" button to parse files without saving to database.
• View parsed results with structured information display.
• Use "View Schema" button to open detailed modal with interactive schema viewer.
• Download JSON schema or copy to clipboard from the modal.

This feature uses the backend endpoint POST /api/forms/parse and the parseFile method in FormService.