# gitpugal/formsx architecture

> Architecture diagram of the GitHub repository gitpugal/formsx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gitpugal/formsx
- Repository: https://github.com/gitpugal/formsx

## Overview

##### Project Type and Purpose
- This is a full-stack, serverless-style form-building and management platform built with Next.js (App Router), TypeScript, Prisma, Tailwind CSS, and NextAuth.
- Users can sign up/log in, create and manage forms and campaigns, embed forms into third-party sites (iframe/popup), integrate with external services (Google Sheets, Notion, Stripe, SMTP mail), and collaborate in workspaces.

##### File Structure
- app/
– (auth), (campaign), (dashboard), (embed), (onboard), (site): segregated UI/route segments using Next.js layouts & pages.
– app/api/: ~120 RESTful API route handlers (Next.js route.ts) for authentication, form CRUD, workspace management, integrations (Google Sheets, Notion), payments (Stripe), email/webhooks, etc.
- lib/: Prisma client (lib/prisma.ts), Firebase configuration, auth options, a job queue, utility functions.
- services/: client-side wrappers around Firebase, form/org/workspace calls.
- public/: static assets (scripts, images).
- prisma/schema.prisma: database schema.
- config files: next.config.mjs, tailwind.config.ts, postcss.config.mjs, tsconfig.json.

##### README
- It’s a boilerplate README template and doesn’t describe architecture. The file structure is the primary source of truth.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        AuthSegment["Auth Segment"]:::frontend
        DashboardSegment["Dashboard Segment"]:::frontend
        CampaignSegment["Campaign Segment"]:::frontend
        EmbedSegment["Embed Segment"]:::frontend
        OnboardSegment["Onboard Segment"]:::frontend
        SiteSegment["Public Site Segment"]:::frontend
        subgraph "Shared UI & Form Builder"
            direction TB
            UIComponents["Primitive UI Components"]:::frontend
            ReusableComponents["Reusable Components"]:::frontend
            EditorTools["Editor.js Form Builder Tools"]:::frontend
        end
    end

    %% API Layer
    subgraph "Next.js API Routes" 
        direction TB
        APILayer["All REST Endpoints"]:::api
        AuthAPI["NextAuth Route"]:::api
        FormAPI["Form CRUD API"]:::api
        WorkspaceAPI["Workspace & Org API"]:::api
        InviteAPI["Invitations & Members API"]:::api
        IntegrationsAPI["Integrations API"]:::api
    end

    %% Database & ORM
    subgraph "Database & ORM"
        direction TB
        PrismaSchema["Prisma Schema"]:::db
        PrismaClient["Prisma Client"]:::db
    end

    %% Auth & Session Config
    AuthConfig["NextAuth Options"]:::internal

    %% Firebase Services
    subgraph "Firebase Services"
        direction TB
        FirebaseConfig["Firebase Config"]:::internal
        FirebaseClient["Firebase Client Wrapper"]:::internal
    end

    %% Client-side Services
    subgraph "Client-side Services"
        direction TB
        FormsService["Forms Service"]:::internal
        OrgService["Organization Service"]:::internal
        WorkspaceService["Workspace Service"]:::internal
    end

    %% Background & Utils
    subgraph "Background Jobs & Utilities"
        direction TB
        JobQueue["Job Queue"]:::internal
        Utils["Utility Functions"]:::internal
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        StripeCheckout["Stripe Checkout & Cancel"]:::external
        StripeWebhook["Stripe Webhook"]:::external
        GoogleConnect["Google Sheets Connect & Callback"]:::external
        NotionIntegration["Notion Integration & Save"]:::external
        SMTPService["SMTP Mail Service & Daily Update"]:::external
    end

    %% Config Files
    subgraph "Configuration"
        direction TB
        TailwindConfig["Tailwind CSS Config"]:::internal
        NextConfig["Next.js Config"]:::internal
    end

    %% Connections
    AuthSegment -->|fetch| APILayer
    DashboardSegment -->|fetch| APILayer
    CampaignSegment -->|fetch| APILayer
    EmbedSegment -->|fetch| APILayer
    OnboardSegment -->|fetch| APILayer
    SiteSegment -->|fetch| APILayer
    UIComponents -->|used by| AuthSegment
    ReusableComponents -->|used by| DashboardSegment
    EditorTools -->|used by| CampaignSegment

    APILayer -->|routes auth| AuthAPI
    APILayer -->|routes form| FormAPI
    APILayer -->|routes workspace| WorkspaceAPI
    APILayer -->|routes invite| InviteAPI
    APILayer -->|routes integrate| IntegrationsAPI

    AuthAPI -->|uses| AuthConfig
    APILayer -->|queries| PrismaClient
    PrismaClient -->|defined by| PrismaSchema
    APILayer -->|enqueue| JobQueue
    APILayer -->|calls| FirebaseClient
    AuthSegment -->|real-time| FirebaseClient

    IntegrationsAPI -->|calls| StripeCheckout
    IntegrationsAPI -->|calls| StripeWebhook
    IntegrationsAPI -->|calls| GoogleConnect
    IntegrationsAPI -->|calls| NotionIntegration
    IntegrationsAPI -->|calls| SMTPService

    FormsService -->|wraps| APILayer
    OrgService -->|wraps| APILayer
    WorkspaceService -->|wraps| APILayer

    JobQueue -->|uses| Utils

    TailwindConfig --- UIComponents
    NextConfig --- AuthSegment

    %% Click Events - Frontend
    click AuthSegment "https://github.com/gitpugal/formsx/tree/main/app/(auth)"
    click DashboardSegment "https://github.com/gitpugal/formsx/tree/main/app/(dashboard)"
    click CampaignSegment "https://github.com/gitpugal/formsx/tree/main/app/(campaign)"
    click EmbedSegment "https://github.com/gitpugal/formsx/tree/main/app/(embed)"
    click OnboardSegment "https://github.com/gitpugal/formsx/tree/main/app/(onboard)"
    click SiteSegment "https://github.com/gitpugal/formsx/tree/main/app/(site)"
    click UIComponents "https://github.com/gitpugal/formsx/tree/main/components/ui"
    click ReusableComponents "https://github.com/gitpugal/formsx/tree/main/components/"
    click EditorTools "https://github.com/gitpugal/formsx/tree/main/components/Editorjs"
    click EditorTools "https://github.com/gitpugal/formsx/tree/main/components/Formbuilder"

    %% Click Events - API Layer
    click APILayer "https://github.com/gitpugal/formsx/tree/main/app/api"
    click AuthAPI "https://github.com/gitpugal/formsx/blob/main/app/api/auth/[...nextauth]/route.ts"
    click FormAPI "https://github.com/gitpugal/formsx/blob/main/app/api/form/route.ts"
    click FormAPI "https://github.com/gitpugal/formsx/blob/main/app/api/form/[id]/route.ts"
    click WorkspaceAPI "https://github.com/gitpugal/formsx/blob/main/app/api/workspace/route.ts"
    click WorkspaceAPI "https://github.com/gitpugal/formsx/blob/main/app/api/workspace/[id]/route.ts"
    click InviteAPI "https://github.com/gitpugal/formsx/blob/main/app/api/accept-invitation/route.ts"
    click InviteAPI "https://github.com/gitpugal/formsx/blob/main/app/api/fetchOrganisationMembers/route.ts"
    click InviteAPI "https://github.com/gitpugal/formsx/blob/main/app/api/send-invitation/route.ts"

    %% Click Events - Integrations API
    click StripeCheckout "https://github.com/gitpugal/formsx/blob/main/app/api/stripe/checkout/route.ts"
    click StripeCheckout "https://github.com/gitpugal/formsx/blob/main/app/api/stripe/cancel/route.ts"
    click StripeWebhook "https://github.com/gitpugal/formsx/blob/main/app/api/webhooks/checkout/route.ts"
    click GoogleConnect "https://github.com/gitpugal/formsx/blob/main/app/api/google-sheet/connect/route.ts"
    click GoogleConnect "https://github.com/gitpugal/formsx/blob/main/app/api/google-sheet/callback/route.ts"
    click NotionIntegration "https://github.com/gitpugal/formsx/blob/main/app/api/integrations/notion/route.ts"
    click NotionIntegration "https://github.com/gitpugal/formsx/blob/main/app/api/integrations/save-notion-db/route.ts"
    click SMTPService "https://github.com/gitpugal/formsx/blob/main/app/api/mail-services/smtp/route.ts"
    click SMTPService "https://github.com/gitpugal/formsx/blob/main/app/api/mail-services/daily-update/route.ts"

    %% Click Events - Database & ORM
    click PrismaSchema "https://github.com/gitpugal/formsx/blob/main/prisma/schema.prisma"
    click PrismaClient "https://github.com/gitpugal/formsx/blob/main/lib/prisma.ts"

    %% Click Events - Auth & Firebase & Services
    click AuthConfig "https://github.com/gitpugal/formsx/blob/main/lib/authOptions.ts"
    click FirebaseConfig "https://github.com/gitpugal/formsx/blob/main/lib/firebaseconfig.ts"
    click FirebaseClient "https://github.com/gitpugal/formsx/blob/main/app/services/FirebaseServices.ts"
    click FormsService "https://github.com/gitpugal/formsx/blob/main/app/services/forms.ts"
    click OrgService "https://github.com/gitpugal/formsx/blob/main/app/services/organization.ts"
    click WorkspaceService "https://github.com/gitpugal/formsx/blob/main/app/services/workspace.ts"

    %% Click Events - Background & Utilities
    click JobQueue "https://github.com/gitpugal/formsx/blob/main/lib/queue.ts"
    click Utils "https://github.com/gitpugal/formsx/blob/main/lib/utils.ts"

    %% Click Events - Config
    click TailwindConfig "https://github.com/gitpugal/formsx/blob/main/tailwind.config.ts"
    click NextConfig "https://github.com/gitpugal/formsx/blob/main/next.config.mjs"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef api fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef db fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef external fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef internal fill:#f5f5f5,stroke:#9e9e9e,color:#424242

    %% Legend
    subgraph Legend
        direction TB
        L1["Frontend (Blue)"]:::frontend
        L2["API (Green)"]:::api
        L3["Database (Orange)"]:::db
        L4["External (Purple)"]:::external
        L5["Internal (Gray)"]:::internal
    end
```
