# gitpugal/forms architecture

> Architecture diagram of the GitHub repository gitpugal/forms, 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/forms
- Repository: https://github.com/gitpugal/forms

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (app directory uses Next 13’s App Router), React/TypeScript, Prisma, Firebase, NextAuth, and various third-party integrations (Stripe, Google Sheets, Notion, SMTP mail).
- Its domain: a form-builder and form-management platform supporting user auth, workspace/org management, embedded forms, campaign workflows, and integrations.

##### File structure
- Top-level “app” directory holds both UI pages (React server/client components) and API routes (app/api/**).
- Key sub-directories under app:
- (auth), (dashboard), (campaign), (embed), (onboard), (site) – these group related page routes and layouts.
- app/api/** – Next.js Route Handlers implementing RESTful endpoints for auth, forms, workspaces, invitations, payments, integrations, webhooks, etc.
- “components” directory houses reusable React UI components (including Editor.js form-builder tools).
- “lib” contains core configuration/utilities: Prisma client, Firebase config, queue utilities, auth options.
- “services” wraps calls to Firebase, workspace/form/org logic.
- Prisma schema at schema.prisma drives the relational data model.
- Config files: next.config.mjs, tailwind.config.ts, postcss.config.mjs, tsconfig.json.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser / Client)" 
        Browser["Browser / Client (React UI & Pages)"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server"
        AppRouter["App Router & Layouts"]:::backend
        Middleware["middleware.ts"]:::backend
    end

    %% API Layer
    subgraph "API Layer"
        AuthAPI["Auth Routes"]:::backend
        FormAPI["Form Routes"]:::backend
        WorkspaceAPI["Workspace Routes"]:::backend
        OtherAPI["Other API Endpoints"]:::backend
    end

    %% Service / Domain Layer
    subgraph "Service Layer"
        FirebaseSvc["FirebaseServices.ts"]:::service
        FormsSvc["forms.ts"]:::service
        OrgSvc["organization.ts"]:::service
        WSvc["workspace.ts"]:::service
        Utils["utils.ts"]:::service
        Queue["queue.ts"]:::service
    end

    %% Persistence Layer
    subgraph "Database"
        PrismaClient["Prisma Client"]:::database
        Schema["schema.prisma"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        StripeCheckout["Stripe Checkout API"]:::external
        StripeCancel["Stripe Cancel API"]:::external
        StripeWebhooks["Stripe Webhooks"]:::external
        GoogleConnect["Google Sheets Connect API"]:::external
        GoogleCallback["Google Sheets Callback API"]:::external
        NotionAPI["Notion API"]:::external
        NotionSave["Notion Save-DB API"]:::external
        SMTP["SMTP Mail Service"]:::external
        DailyMail["Daily-Update Mail Job"]:::external
    end

    %% Relationships
    Browser -->|"HTTP Request"| AppRouter
    AppRouter -->|routes to| AuthAPI
    AppRouter -->|routes to| FormAPI
    AppRouter -->|routes to| WorkspaceAPI
    AppRouter -->|routes to| OtherAPI

    AuthAPI -->|uses| FirebaseSvc
    FormAPI -->|uses| FormsSvc
    WorkspaceAPI -->|uses| WSvc
    OtherAPI -->|uses| OrgSvc
    OtherAPI -->|uses| Utils

    AuthAPI -->|writes/reads| PrismaClient
    FormAPI -->|reads/writes| PrismaClient
    WorkspaceAPI -->|reads/writes| PrismaClient
    OtherAPI -->|reads/writes| PrismaClient

    FormAPI -->|enqueue jobs| Queue
    Queue -->|executes tasks| FirebaseSvc
    Queue -->|executes tasks| FormsSvc
    Queue -->|executes tasks| WSvc

    FormsSvc -->|queries| PrismaClient
    WSvc -->|queries| PrismaClient
    OrgSvc -->|queries| PrismaClient

    %% External Service Calls
    FormAPI -->|Stripe Checkout| StripeCheckout
    FormAPI -->|Stripe Cancel| StripeCancel
    OtherAPI -->|Stripe Webhooks| StripeWebhooks
    OtherAPI -->|Google Sheets Connect| GoogleConnect
    OtherAPI -->|Google Sheets Callback| GoogleCallback
    OtherAPI -->|Notion API Call| NotionAPI
    OtherAPI -->|Notion Save| NotionSave
    OtherAPI -->|Send Email| SMTP
    Queue -->|Daily Job| DailyMail

    %% Click Events
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(auth)"
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(dashboard)"
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(campaign)"
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(embed)"
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(onboard)"
    click Browser "https://github.com/gitpugal/forms/tree/main/app/(site)"
    click Browser "https://github.com/gitpugal/forms/tree/main/components/"
    click AppRouter "https://github.com/gitpugal/forms/blob/main/app/layout.tsx"
    click Middleware "https://github.com/gitpugal/forms/blob/main/middleware.ts"
    click AuthAPI "https://github.com/gitpugal/forms/blob/main/app/api/auth/[...nextauth]/route.ts"
    click FormAPI "https://github.com/gitpugal/forms/tree/main/app/api/form/"
    click WorkspaceAPI "https://github.com/gitpugal/forms/tree/main/app/api/workspace/"
    click OtherAPI "https://github.com/gitpugal/forms/tree/main/app/api/"
    click FirebaseSvc "https://github.com/gitpugal/forms/blob/main/app/services/FirebaseServices.ts"
    click FormsSvc "https://github.com/gitpugal/forms/blob/main/app/services/forms.ts"
    click OrgSvc "https://github.com/gitpugal/forms/blob/main/app/services/organization.ts"
    click WSvc "https://github.com/gitpugal/forms/blob/main/app/services/workspace.ts"
    click Utils "https://github.com/gitpugal/forms/blob/main/lib/utils.ts"
    click Queue "https://github.com/gitpugal/forms/blob/main/lib/queue.ts"
    click PrismaClient "https://github.com/gitpugal/forms/blob/main/lib/prisma.ts"
    click Schema "https://github.com/gitpugal/forms/blob/main/schema.prisma"
    click StripeCheckout "https://github.com/gitpugal/forms/blob/main/app/api/stripe/checkout/route.ts"
    click StripeCancel "https://github.com/gitpugal/forms/blob/main/app/api/stripe/cancel/route.ts"
    click StripeWebhooks "https://github.com/gitpugal/forms/blob/main/app/api/webhooks/checkout/route.ts"
    click GoogleConnect "https://github.com/gitpugal/forms/blob/main/app/api/google-sheet/connect/route.ts"
    click GoogleCallback "https://github.com/gitpugal/forms/blob/main/app/api/google-sheet/callback/route.ts"
    click NotionAPI "https://github.com/gitpugal/forms/blob/main/app/api/integrations/notion/route.ts"
    click NotionSave "https://github.com/gitpugal/forms/blob/main/app/api/integrations/save-notion-db/route.ts"
    click SMTP "https://github.com/gitpugal/forms/blob/main/app/api/mail-services/smtp/route.ts"
    click DailyMail "https://github.com/gitpugal/forms/blob/main/app/api/mail-services/daily-update/route.ts"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFF5E3,stroke:#28a745,color:#28a745;
    classDef service fill:#E8F0FE,stroke:#3357FF,color:#3357FF;
    classDef database fill:#FFE7A2,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F5E6FF,stroke:#9C27B0,color:#9C27B0;
```
