# smarthg/harper-form-tool architecture

> Architecture diagram of the GitHub repository smarthg/harper-form-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smarthg/harper-form-tool
- Repository: https://github.com/smarthg/harper-form-tool

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U("User"):::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Frontend Application"):::frontend
        FE1("UI Components"):::frontend
        FE2("Client Libraries"):::frontend
        FE3("Pages & Hooks"):::frontend
        FE4("Asset Management"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE("Backend API Server"):::backend
        BE1("Backend Services"):::backend
        BE2("Storage & Form Definitions"):::backend
    end

    %% Shared Modules
    SM("Shared Schemas & Form Types"):::shared

    %% External Services
    ES("External Integrations (Clerk, Anvil API, OpenAI)"):::external

    %% Relationships & Data Flow
    U -->|"interacts"| FE
    FE -->|"sendsAPICalls"| BE
    BE -->|"processes"| BE1
    BE -->|"handlesData"| BE2
    FE2 -->|"wrapsAPI"| ES
    BE1 -->|"integrates"| ES
    FE ---|"uses"| SM
    BE2 ---|"references"| SM

    %% Click Events
    click FE "https://github.com/smarthg/harper-form-tool/tree/main/client/"
    click FE1 "https://github.com/smarthg/harper-form-tool/tree/main/client/src/components/"
    click FE2 "https://github.com/smarthg/harper-form-tool/tree/main/client/src/lib/"
    click FE3 "https://github.com/smarthg/harper-form-tool/blob/main/client/src/pages/FormEditor.tsx"
    click FE4 "https://github.com/smarthg/harper-form-tool/tree/main/client/public/"
    click BE "https://github.com/smarthg/harper-form-tool/tree/main/server/"
    click BE1 "https://github.com/smarthg/harper-form-tool/tree/main/server/services/"
    click BE2 "https://github.com/smarthg/harper-form-tool/blob/main/server/storage.ts"
    click SM "https://github.com/smarthg/harper-form-tool/tree/main/shared/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#343a40,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef user fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
