# ozcancelik/nextjs-14-mail-form architecture

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

- Interactive diagram: https://gitdiagram.com/ozcancelik/nextjs-14-mail-form
- Repository: https://github.com/ozcancelik/nextjs-14-mail-form

## Overview

##### Project type and purpose
- This is a full-stack Next.js 14 template for a contact form.
- It provides a React-based frontend (in `src/app`), uses Next.js Server Actions (in `src/app/actions.ts`) for form submission, validates input with Zod, protects from spam with reCAPTCHA, formats emails with Handlebars (`src/templates/contact.ts`), and sends mail via Nodemailer through a custom Node.js server (`server.js`).

##### File structure
- Top‐level files:
- `server.js` – custom Node HTTP server that mounts Next.js
- `next.config.mjs` – Next.js configuration
- `.env.example` – environment variables for SMTP, reCAPTCHA, port
- `package.json`, build/config files (Tailwind, PostCSS, ESLint, TS)
- `public/` – static assets (e.g., favicon, robots.txt)
- `src/app/` – Next.js App Router: layouts, global CSS, `page.tsx` (UI) and `actions.ts` (Server Actions)
- `src/components/` – UI components (form, toast notifications)
- `src/lib/utils.ts` – shared helper functions
- `src/templates/` – Handlebars email templates

##### README for architecture clues
- Confirms stack: Next.js Server Actions, React Hook Form, Zod, reCAPTCHA v2, Handlebars, Nodemailer, Tailwind CSS, TypeScript.
- Notes that `@/app/actions.ts` contains `sendContactForm` which:
1. Validates form data via Zod
2. Verifies reCAPTCHA server-side
3. Uses Handlebars to render HTML email
4. Sends email via Nodemailer to external SMTP

##### Essential details
- Handlebars template engine reading `contact.ts` and producing HTML.
- Don’t overthink—break the system into these discrete components for clarity.
- Flows (success and error) are represented, even if simply noted as “error path.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Browser and UI
    Browser("Browser (User)"):::external

    subgraph "Frontend: Next.js App Router"
        direction TB
        FrontendApp("Next.js Frontend<br/>(src/app/)"):::frontend
        Layout("Layout<br/>src/app/layout.tsx"):::frontend
        Page("Page Component<br/>src/app/page.tsx"):::frontend
        GlobalsCSS("Global Styles<br/>src/app/globals.css"):::frontend
        Form("Contact Form Component<br/>src/components/form.tsx"):::frontend
        Toast1("Toast UI Component<br/>src/components/ui/toast.tsx"):::frontend
        Toast2("Toaster UI Component<br/>src/components/ui/toaster.tsx"):::frontend
        Toast3("useToast Hook<br/>src/components/ui/use-toast.ts"):::frontend
    end

    %% Server and Backend
    subgraph "Server: Node.js & Next.js Custom Server"
        direction TB
        ServerJS("Custom Server<br/>server.js"):::backend
        ServerAction("Server Action:<br/>sendContactForm<br/>src/app/actions.ts"):::backend
        Utils("Shared Utils<br/>src/lib/utils.ts"):::backend
        Template("Handlebars Template<br/>src/templates/contact.ts"):::backend
        NodemailerClient("Nodemailer SMTP Client"):::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Recaptcha("reCAPTCHA API (Google)"):::external
        SMTPHost("SMTP Host (Gmail/Other)"):::external
    end

    %% Configuration
    subgraph "Config & Env"
        direction TB
        Env(".env.example"):::config
        NextConfig("next.config.mjs"):::config
        Tailwind("tailwind.config.ts"):::config
        PostCSS("postcss.config.mjs"):::config
        TSConfig("tsconfig.json"):::config
    end

    %% Flows
    Browser -->|"loads"| FrontendApp
    FrontendApp --> Layout
    Layout --> Page
    Page --> GlobalsCSS
    Page --> Form
    Page --> Toast1
    Page --> Toast2
    Page --> Toast3

    Form -->|"onSubmit"| ServerAction
    ServerAction -->|"uses utils"| Utils
    ServerAction -->|"validate (Zod) & verify token"| Recaptcha
    ServerAction -->|"render email"| Template
    Template --> ServerAction
    ServerAction -->|"send email"| NodemailerClient
    NodemailerClient -->|"SMTP"| SMTPHost
    ServerAction -->|"response (success/error)"| Browser

    Env --> ServerJS
    NextConfig --> ServerJS
    Tailwind --> ServerJS
    PostCSS --> ServerJS
    TSConfig --> ServerJS

    ServerJS --> ServerAction

    %% Click Events
    click FrontendApp "https://github.com/ozcancelik/nextjs-14-mail-form/tree/main/src/app/"
    click Layout "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/app/layout.tsx"
    click Page "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/app/page.tsx"
    click GlobalsCSS "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/app/globals.css"
    click Form "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/components/form.tsx"
    click Toast1 "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/components/ui/toast.tsx"
    click Toast2 "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/components/ui/toaster.tsx"
    click Toast3 "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/components/ui/use-toast.ts"
    click ServerAction "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/app/actions.ts"
    click Template "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/templates/contact.ts"
    click ServerJS "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/server.js"
    click Utils "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/src/lib/utils.ts"
    click Env "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/.env.example"
    click NextConfig "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/next.config.mjs"
    click Tailwind "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/tailwind.config.ts"
    click PostCSS "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/ozcancelik/nextjs-14-mail-form/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#000000
    classDef backend fill:#DFFFE0,stroke:#339900,color:#000000
    classDef external fill:#FFE5B4,stroke:#CC6600,color:#000000
    classDef config fill:#F0F0F0,stroke:#888888,color:#000000
```
