How smarthg/harper-form-tool works
Project Overview
• The project is a full-stack web application designed for real-time, voice-controlled editing of insurance forms (e.g., ACORD 125, ACORD 126). Its core functionality includes natural language voice command processing, dynamic form editing, PDF generation, and secure user authentication.
• The underlying technology stack includes a React/TypeScript frontend (using Tailwind CSS and shadcn/ui), an Express.js backend (with in-memory storage), integrations with external APIs such as Anvil (for PDF generation) and OpenAI (for voice recognition fallback), and Clerk for authentication.
Main Components
a. Frontend:
• Client Directory: Contains the React application (entry point in client/index.html and main.tsx).
• Components: Includes various reusable UI elements (e.g., Acord125Form, Acord126Form, Header, VoiceInterface, ActivityLog, etc.) and UI libraries (under client/src/components/ui).
• Pages & Hooks: Includes pages (e.g., FormEditor, SignIn, SignUp) and custom hooks (e.g., use-mobile, use-toast) that manage state and interactions.
• Libraries: Utility functions and service wrappers (e.g., openaiService.ts, anvilService.ts inside client/src/lib).
• Assets: Uploaded files and static templates (located in client/public).
b. Backend:
• Server Directory: Contains the Express.js server with its entry point (server/index.ts) and routing (server/routes.ts).
• Services: Contains business logic/special services like anvilService.ts (for PDF generation) and formMappingService.ts.
• Form Data and Definitions: There are files related to form definitions, including definitions for multiple ACORD forms (in server/formDefinitions and shared/formTypes).
• Data Storage: Implements in-memory storage (server/storage.ts) that holds form data during runtime.
• API Endpoints: Exposes endpoints for fetching/updating form data, generating PDFs, and retrieving form definitions.
c. Shared/External:
• Shared Code: Located in the “shared” folder (shared/schema.ts and shared/formTypes for ACORD forms) to enforce consistency between frontend and backend.
• External Services: Integration with Clerk for authentication, OpenAI API (and optionally LLAMAPARSE) for NLP and voice command processing, and Anvil API for PDF generation.
• Documentation: The project includes extensive docs (README, API_DOCUMENTATION.md, etc.) that detail API contracts and usage for external integrations.
Relationships & Data Flow
• User Interaction begins at the client’s UI components (voice interface, form fields, command history).
• Voice commands are captured via the Web Speech API, possibly combined with an OpenAI service for transcription/NLP (referenced in the client/src/lib/openaiService.ts).
• Updated form data travels from the client to the backend over REST API endpoints (e.g., PATCH /api/form-data, GET /api/form-definitions/:formType).
• The Express server receives these requests, processes them (using services and in-memory storage) and potentially invokes the Anvil API to generate PDF documents, thereby creating filled forms which are served back to the frontend.
• Shared schema and form definitions ensure consistent data handling between client and server.
• Authentication and request guarding (via Clerk and AuthGuard components) protect the flow.