# varadarajan-m/form-craft architecture

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

- Interactive diagram: https://gitdiagram.com/varadarajan-m/form-craft
- Repository: https://github.com/varadarajan-m/form-craft

## Overview

##### Primary components and layers

- Frontend (Client UI):
- Next.js application (found in src/app) which includes pages for the dashboard, form builder, form viewer, landing page, sign-in/up flows, etc.
- Specialized UI zones such as “Dashboard”, “Builder”, and “Form Viewer”. Note the components for analytics, data visualization (charts, cards) and the drag-and-drop builder functionality.
- Shared UI modules and common components (in src/components/ui and src/components/common).

- Backend (API & Server Logic):
- API endpoints under src/app/api. These endpoints respond to callbacks (from Airtable and Google), refresh tokens, webhook calls, and form-related tasks (like AI prompt handling).
- Business logic and controllers in the src/backend directory (actions, models, and database connection) which handle form submissions, analytics, integrations, and CRUD operations.

- Database or Data Persistence Layer:
- While the explicit database technology isn’t mentioned, the presence of src/backend/db/connection.ts and models indicates a data persistence layer for storing forms, submissions, templates, and analytics data.

- Third-Party Integrations:
- External services such as Airtable, Google (including Sheets integration), and webhooks.
- For integrations, illustrate both the callback API endpoints and any dedicated integration modules (in src/app/api/callback/* and inside builder integrations).

- Additional Utilities and State Management:
- Usage of utilities, hooks (e.g., useDebounceEffect, useFeatureAnnouncer) and the Zustand-based state management (in src/zustand) that help manage the client-side state.
- Utility libraries for functions like form validation, date/time, and common helper methods (in src/lib).

- Data Flow:
- API/backend to external services (Airtable, Google, Webhook) via clearly marked integration connectors representing the callbacks and communication routes.

- Communication Patterns:
- REST or serverless API pattern implemented in “src/app/api” for asynchronous requests.
- Real-time analytics requests from frontend components to the backend actions.

##### Architectural Patterns and Key Design Principles

- Modular Separation:
- The project cleanly separates concerns by placing UI components (for rendering and interactivity) in the frontend, and the business logic and integrations in the backend.
- The builder (drag-and-drop interface) seems to have a dedicated folder structure, emphasizing component reusability and separation of the left pane, center pane, and right pane for configuration.

- Layered Architecture:
- Use layers to indicate that the system is divided into Presentation (Next.js pages and components), Application Logic (API routes, backend actions/models), and Data Persistence (database connection and models).

- Extensibility:
- The presence of numerous integration modules (airtable, google-sheets, webhook) implies that the architecture is designed to easily add new third-party integrations.

- React and Next.js Conventions:
- Recognize file-based routing (Next.js pages), which is reflected in the organization of src/app and API routes. Also note the use of middleware and providers for global configurations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Level 0: User
    Browser["User's Browser/Client"]:::user

    %% Level 1: Frontend Layer
    subgraph "Next.js Frontend"
        FE["Next.js Frontend (Client UI)"]:::frontend
        DM["Dashboard Module"]:::frontend
        FB["Form Builder (Drag-And-Drop UI)"]:::frontend
        FV["Form Viewer"]:::frontend
        UI1["Shared UI Components (UI)"]:::frontend
        UI2["Common UI Components"]:::frontend
    end

    %% Level 1.5: Utilities & State Management (side branch)
    subgraph "Utilities & State Management"
        UTIL["Utilities"]:::utility
        HOOK["Custom Hooks"]:::utility
        ZST["Zustand State Management"]:::utility
    end

    %% Level 2: API Layer
    FEapi["API Endpoints"]:::api
    CE["Callback API Endpoints"]:::api

    %% Level 3: Backend Business Logic
    BL["Business Logic & Controllers"]:::backend

    %% Level 4: Data Persistence
    DB["Database / Data Store"]:::database

    %% Level 4: Third-Party Integrations
    subgraph "Third-Party Integrations"
        Airtable["Airtable"]:::integration
        GoogleSheets["Google Sheets"]:::integration
        Webhook["Webhook"]:::integration
        IM["Integration Modules"]:::integration
    end

    %% Interactions
    Browser -->|"Interactions"| FE
    FE -->|"API_Calls"| FEapi
    FEapi -->|"IntegrationCallback"| CE
    CE -->|"Process_Callbacks"| BL
    FEapi -->|"Process_Requests"| BL
    BL -->|"CRUD_Operations"| DB
    BL -->|"Calls"| Airtable
    BL -->|"Calls"| GoogleSheets
    BL -->|"Calls"| Webhook
    FB -->|"Uses"| IM
    FE -->|"Uses"| UTIL
    FE -->|"Uses"| HOOK
    FE -->|"Uses"| ZST

    %% Styles
    classDef user fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#ccf2ff,stroke:#0066cc,stroke-width:2px;
    classDef api fill:#d1ffc6,stroke:#0f9d58,stroke-width:2px;
    classDef backend fill:#fff3cd,stroke:#ffcc00,stroke-width:2px;
    classDef database fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
    classDef integration fill:#fcd1d1,stroke:#cc3300,stroke-width:2px;
    classDef utility fill:#d1e0ff,stroke:#3366ff,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/varadarajan-m/form-craft/tree/main/src/app"
    click DM "https://github.com/varadarajan-m/form-craft/tree/main/src/app/(dashboard)"
    click FB "https://github.com/varadarajan-m/form-craft/tree/main/src/app/builder"
    click FV "https://github.com/varadarajan-m/form-craft/tree/main/src/app/form"
    click UI1 "https://github.com/varadarajan-m/form-craft/tree/main/src/components/ui"
    click UI2 "https://github.com/varadarajan-m/form-craft/tree/main/src/components/common"
    click FEapi "https://github.com/varadarajan-m/form-craft/tree/main/src/app/api"
    click CE "https://github.com/varadarajan-m/form-craft/tree/main/src/app/api/callback"
    click BL "https://github.com/varadarajan-m/form-craft/tree/main/src/backend"
    click DB "https://github.com/varadarajan-m/form-craft/tree/main/src/backend/db"
    click IM "https://github.com/varadarajan-m/form-craft/tree/main/src/app/builder/_components/left-pane/form-integrations"
    click UTIL "https://github.com/varadarajan-m/form-craft/tree/main/src/lib"
    click HOOK "https://github.com/varadarajan-m/form-craft/tree/main/src/hooks"
    click ZST "https://github.com/varadarajan-m/form-craft/tree/main/src/zustand"
    click Airtable "https://github.com/varadarajan-m/form-craft/tree/main/src/app/api/callback/airtable"
    click GoogleSheets "https://github.com/varadarajan-m/form-craft/tree/main/src/app/api/callback/google"
    click Webhook "https://github.com/varadarajan-m/form-craft/tree/main/src/app/api/callback/webhook"
```
