mirror of
https://github.com/vee1e/bulk-questionnaire-upload.git
synced 2026-09-01 09:50:06 +00:00
refactor: update README files for backend and frontend with enhanced documentation and structure
- Renamed backend README to reflect "Bulk Questionnaire Upload" focus. - Expanded backend documentation to include detailed architecture, API references, and error handling strategies. - Updated frontend README to include new features, installation instructions, and API integration details. - Improved project structure descriptions and added sections for testing, deployment, and future enhancements.
This commit is contained in:
parent
63307cab65
commit
69047a1bdd
2 changed files with 817 additions and 311 deletions
|
|
@ -1,113 +1,387 @@
|
|||
# mForm Bulk Upload Frontend
|
||||
|
||||
## About the Frontend
|
||||
A modern, full-stack Angular application for bulk uploading, validating, parsing, and managing questionnaire forms. Built with Angular 19, featuring server-side rendering, comprehensive error handling, and a sleek dark theme interface.
|
||||
|
||||
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.
|
||||
## Quick Start
|
||||
|
||||
### 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.
|
||||
### Prerequisites
|
||||
- Node.js 18+
|
||||
- Angular CLI 19+
|
||||
- Backend API server running
|
||||
|
||||
### 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.
|
||||
### Installation
|
||||
|
||||
### 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
|
||||
```bash
|
||||
# Navigate to frontend directory
|
||||
cd frontend
|
||||
|
||||
# Backend Integration Points
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
This document outlines where and how the frontend communicates with the backend API for easy maintenance and future updates.
|
||||
# Start development server
|
||||
npm start
|
||||
|
||||
## Main Integration Service
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
### 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.
|
||||
# Start SSR server
|
||||
npm run serve:ssr:mform-upload
|
||||
```
|
||||
|
||||
**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
|
||||
### Development Commands
|
||||
|
||||
**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()`
|
||||
```bash
|
||||
npm start # Development server on http://localhost:4200
|
||||
npm run build # Production build
|
||||
npm run watch # Watch mode build
|
||||
npm run test # Run tests with Vitest
|
||||
npm run test:run # Run tests once
|
||||
```
|
||||
|
||||
## Components Using Backend Integration
|
||||
## Architecture & Tech Stack
|
||||
|
||||
### 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
|
||||
### Core Technologies
|
||||
- **Angular 19** - Latest Angular with standalone components
|
||||
- **TypeScript 5.7** - Full type safety and modern features
|
||||
- **Angular Material** - UI component library with custom dark theme
|
||||
- **Server-Side Rendering** - SEO-friendly and fast initial loads
|
||||
- **Vitest** - Modern testing framework (replaces Jasmine/Karma)
|
||||
- **Express.js** - SSR server backend
|
||||
|
||||
### 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)
|
||||
### Key Features
|
||||
|
||||
### NavbarComponent (`src/app/components/navbar/navbar.component.ts`)
|
||||
- Indirectly uses backend data via FormPreviewService, which is populated by UploadComponent using FormService.
|
||||
#### Bulk File Operations
|
||||
- **Drag & Drop Interface** - Intuitive file selection with visual feedback
|
||||
- **Multi-file Upload** - Process multiple Excel files simultaneously
|
||||
- **Progress Tracking** - Real-time progress bars with color-coded operations
|
||||
- **Batch Validation** - Validate all files before upload with detailed error reports
|
||||
|
||||
## 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.
|
||||
#### Form Management
|
||||
- **Excel Parsing** - Convert XLS/XLSX files to structured JSON schemas
|
||||
- **Form Preview** - Interactive form details with question/option navigation
|
||||
- **Search & Filter** - Real-time search across all uploaded forms
|
||||
- **Form Updates** - In-place form updates preserving history and IDs
|
||||
|
||||
## 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.
|
||||
#### User Experience
|
||||
- **Dark Theme** - Custom black/white Material Design theme
|
||||
- **Keyboard Shortcuts** - Power user features for efficient navigation
|
||||
- **Responsive Design** - Works seamlessly on desktop and mobile
|
||||
- **Accessibility** - ARIA support and keyboard navigation
|
||||
|
||||
## Update Flow
|
||||
#### Performance & Reliability
|
||||
- **Server-Side Rendering** - Fast initial page loads and SEO benefits
|
||||
- **Error Recovery** - Comprehensive error handling with user-friendly messages
|
||||
- **Offline Support** - Graceful degradation and connection status
|
||||
- **Memory Management** - Efficient file handling and cleanup
|
||||
|
||||
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.
|
||||
## Project Structure
|
||||
|
||||
This feature uses the backend endpoint `PUT /api/forms/:formId/update` and the `updateForm` method in FormService.
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── navbar/ # Navigation with form preview
|
||||
│ │ │ ├── search/ # Search functionality
|
||||
│ │ │ └── upload/ # Core upload/management logic
|
||||
│ │ ├── models/ # TypeScript interfaces
|
||||
│ │ ├── services/ # API and state management
|
||||
│ │ ├── app.component.ts # Root component
|
||||
│ │ ├── app.config.ts # Application configuration
|
||||
│ │ ├── app.routes.ts # Routing (currently single-page)
|
||||
│ │ └── main.ts # Bootstrap
|
||||
│ ├── server.ts # SSR server configuration
|
||||
│ ├── main.server.ts # SSR bootstrap
|
||||
│ └── styles.scss # Global dark theme styles
|
||||
├── public/ # Static assets
|
||||
├── angular.json # Angular CLI configuration
|
||||
├── vitest.config.ts # Testing configuration
|
||||
└── package.json # Dependencies and scripts
|
||||
```
|
||||
|
||||
## Parse Only Flow
|
||||
## Core Components
|
||||
|
||||
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.
|
||||
### UploadComponent
|
||||
**Location:** `src/app/components/upload/upload.component.ts`
|
||||
|
||||
This feature uses the backend endpoint `POST /api/forms/parse` and the `parseFile` method in FormService.
|
||||
The main component handling all file operations and form management:
|
||||
|
||||
```typescript
|
||||
// Key features implemented:
|
||||
- Drag & drop file handling
|
||||
- Multi-file validation and parsing
|
||||
- Real-time progress tracking
|
||||
- Form list management
|
||||
- Schema preview modal
|
||||
- Error handling and user feedback
|
||||
```
|
||||
|
||||
**Key Methods:**
|
||||
- `onDragOver/onDrop` - File drag & drop handling
|
||||
- `validateFiles()` - Batch file validation
|
||||
- `uploadFiles()` - Multi-file upload with progress
|
||||
- `parseFilesOnly()` - Preview parsing without saving
|
||||
- `showFormDetails()` - Form preview integration
|
||||
|
||||
### NavbarComponent
|
||||
**Location:** `src/app/components/navbar/navbar.component.ts`
|
||||
|
||||
Navigation with integrated form preview system:
|
||||
|
||||
```typescript
|
||||
// Features:
|
||||
- Form preview panel with slide animation
|
||||
- Keyboard navigation (Ctrl+J/K, Shift+Ctrl+J/K)
|
||||
- Question-by-question navigation
|
||||
- Real-time form data display
|
||||
```
|
||||
|
||||
### SearchComponent
|
||||
**Location:** `src/app/components/search/search.component.ts`
|
||||
|
||||
Intelligent search functionality:
|
||||
|
||||
```typescript
|
||||
// Capabilities:
|
||||
- Real-time form title search
|
||||
- Keyboard shortcut (Shift+K) focus
|
||||
- Debounced search for performance
|
||||
- Visual feedback and accessibility
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
### FormService
|
||||
**Location:** `src/app/services/form.service.ts`
|
||||
|
||||
Centralized API communication layer:
|
||||
|
||||
```typescript
|
||||
@Injectable({ providedIn: 'root' })
|
||||
export class FormService {
|
||||
private readonly apiUrl = 'http://localhost:8000/api';
|
||||
|
||||
// Core API methods
|
||||
validateFile(file: File): Observable<FormValidation>
|
||||
parseFile(file: File): Observable<ParsedSchema>
|
||||
uploadFiles(files: File[]): Observable<any[]>
|
||||
getAllForms(): Observable<FormsResponse>
|
||||
getFormById(formId: string): Observable<FormDetails>
|
||||
updateForm(formId: string, file: File): Observable<FormDetails>
|
||||
deleteForm(formId: string): Observable<{ message: string }>
|
||||
deleteAllForms(): Observable<{ message: string }>
|
||||
}
|
||||
```
|
||||
|
||||
### Backend Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/validate` | Validate Excel file format and content |
|
||||
| POST | `/api/forms/parse` | Parse Excel to JSON schema (no save) |
|
||||
| POST | `/api/upload` | Upload and save form to database |
|
||||
| GET | `/api/forms` | Retrieve all uploaded forms |
|
||||
| GET | `/api/forms/:id` | Get specific form details |
|
||||
| PUT | `/api/forms/:id/update` | Update existing form with new file |
|
||||
| DELETE | `/api/forms/:id` | Delete specific form |
|
||||
| DELETE | `/api/forms` | Delete all forms |
|
||||
|
||||
## Styling & Theming
|
||||
|
||||
### Dark Theme Implementation
|
||||
**Location:** `src/styles.scss`
|
||||
|
||||
Custom Material Design dark theme with:
|
||||
- Black background with glassmorphism effects
|
||||
- White text and borders for high contrast
|
||||
- Custom color palette for buttons and states
|
||||
- Responsive design with mobile-first approach
|
||||
|
||||
### Component Styling Strategy
|
||||
- **Inline styles** in component decorators for encapsulation
|
||||
- **Global overrides** in `styles.scss` for consistency
|
||||
- **CSS custom properties** for theme flexibility
|
||||
- **SCSS nesting** for maintainable component styles
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Vitest Configuration
|
||||
**Location:** `vitest.config.ts`
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
include: ['tests/frontend/**/*.spec.ts'],
|
||||
globals: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Test Structure
|
||||
**Location:** `tests/frontend/`
|
||||
|
||||
- **form.service.spec.ts** - API service testing
|
||||
- Unit tests for components and services
|
||||
- Integration tests for critical user flows
|
||||
- E2E test coverage for upload workflows
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
npm run test # Watch mode
|
||||
npm run test:run # Single run
|
||||
```
|
||||
|
||||
## Deployment & Production
|
||||
|
||||
### Build Configuration
|
||||
**Location:** `angular.json`
|
||||
|
||||
Key production settings:
|
||||
- **SSR enabled** for better performance
|
||||
- **Budget limits** for bundle size optimization
|
||||
- **Asset optimization** and hashing
|
||||
- **Source maps** for debugging
|
||||
|
||||
### Production Build
|
||||
```bash
|
||||
npm run build
|
||||
# Output: dist/mform-upload/
|
||||
```
|
||||
|
||||
### SSR Deployment
|
||||
```bash
|
||||
npm run serve:ssr:mform-upload
|
||||
# Starts Express server on port 4000
|
||||
```
|
||||
|
||||
## Configuration & Environment
|
||||
|
||||
### Angular Configuration
|
||||
**Location:** `src/app/app.config.ts`
|
||||
|
||||
```typescript
|
||||
export const appConfig: ApplicationConfig = {
|
||||
providers: [
|
||||
provideZoneChangeDetection({ eventCoalescing: true }),
|
||||
provideRouter(routes),
|
||||
provideClientHydration(withEventReplay()),
|
||||
provideAnimations(),
|
||||
provideHttpClient(withFetch())
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
### Server-Side Rendering
|
||||
**Location:** `src/server.ts`
|
||||
|
||||
Express server with:
|
||||
- Static file serving with caching
|
||||
- Angular SSR integration
|
||||
- Production-ready error handling
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action | Context |
|
||||
|----------|--------|---------|
|
||||
| `Shift + K` | Focus search | Global |
|
||||
| `Ctrl + J` | Next form | Form list |
|
||||
| `Ctrl + K` | Previous form | Form list |
|
||||
| `Ctrl + Shift + J` | Next question | Form preview |
|
||||
| `Ctrl + Shift + K` | Previous question | Form preview |
|
||||
| `Esc` | Close modals/preview | Modal open |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Validation Error Types
|
||||
- **File Structure Errors** - Missing sheets, columns, invalid formats
|
||||
- **Data Validation Errors** - Type mismatches, missing values, duplicates
|
||||
- **Network Errors** - Connection issues, server errors, timeouts
|
||||
- **File Processing Errors** - Corrupted files, encoding issues
|
||||
|
||||
### Error Recovery
|
||||
- **User-friendly messages** with actionable suggestions
|
||||
- **Automatic retry** for network failures
|
||||
- **Graceful degradation** for non-critical features
|
||||
- **Detailed error logs** for debugging
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
1. **File Type Support** - Add CSV, JSON import capabilities
|
||||
2. **Real-time Collaboration** - Multi-user form editing
|
||||
3. **Advanced Analytics** - Form usage statistics and insights
|
||||
4. **Template System** - Pre-built form templates
|
||||
5. **Export Options** - Additional export formats (PDF, XML)
|
||||
6. **Offline Mode** - Full offline capability with sync
|
||||
7. **Internationalization** - Multi-language support
|
||||
8. **Performance Monitoring** - Application performance tracking
|
||||
|
||||
### Scalability Considerations
|
||||
- **Lazy Loading** - Implement route-based code splitting
|
||||
- **Service Workers** - Add PWA capabilities
|
||||
- **Caching Strategy** - Implement intelligent data caching
|
||||
- **Bundle Optimization** - Code splitting and tree shaking
|
||||
- **CDN Integration** - Static asset optimization
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Form Validation Response
|
||||
```typescript
|
||||
interface FormValidation {
|
||||
valid: boolean;
|
||||
message: string;
|
||||
errors?: ValidationError[];
|
||||
warnings?: ValidationWarning[];
|
||||
sheets?: SheetValidation[];
|
||||
form_metadata?: Record<string, any>;
|
||||
}
|
||||
```
|
||||
|
||||
### Form Data Structure
|
||||
```typescript
|
||||
interface FormData {
|
||||
id: string;
|
||||
title: string;
|
||||
language: string;
|
||||
version: string;
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Parsed Schema Structure
|
||||
```typescript
|
||||
interface ParsedSchema {
|
||||
id: string | null;
|
||||
title: { default: string };
|
||||
version: string;
|
||||
language: string;
|
||||
groups: any[];
|
||||
metadata: {
|
||||
questions_count: number;
|
||||
options_count: number;
|
||||
parse_time: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
### Development Guidelines
|
||||
1. **Code Style** - Follow Angular style guide and TypeScript best practices
|
||||
2. **Component Design** - Use standalone components with proper encapsulation
|
||||
3. **State Management** - Centralize state in services, avoid component coupling
|
||||
4. **Testing** - Write tests for new features and bug fixes
|
||||
5. **Documentation** - Update README and add JSDoc comments
|
||||
|
||||
### Code Quality
|
||||
- **ESLint** integration with Angular CLI
|
||||
- **Pre-commit hooks** for code quality checks
|
||||
- **Type checking** with strict TypeScript configuration
|
||||
- **Bundle analysis** for performance monitoring
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the terms specified in the root LICENSE file.
|
||||
|
||||
Note: This documentation is automatically generated and reflects the current state of the codebase. For the most up-to-date information, refer to the source code and tests.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue