# arunstha21/sendgrid-mailer architecture

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

- Interactive diagram: https://gitdiagram.com/arunstha21/sendgrid-mailer
- Repository: https://github.com/arunstha21/sendgrid-mailer

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (React) on the frontend and Node.js/TypeScript on the backend.
- Purpose: manage users and events, compose/send emails via SendGrid, import match data, and display results.

##### Main Components
A. Frontend (Next.js App)
- Pages & Routing (src/app/**)
- /login (src/app/page.tsx)
- /adduser (src/app/adduser/page.tsx)
- /dashboard (src/app/dashboard/[path]/page.tsx) – new email, import, results tabs
- /results (event-specific results pages)
- /settings (user/event feature settings)
- UI Components (src/components & src/components/ui)
- Styling: Tailwind CSS (tailwind.config.ts, globals.css)

B. Backend API (Next.js API Routes + Custom Server)
- Next.js API Routes (src/server/*.ts invoked via /api/*)
- user.ts – auth, JWT token issuance/validation
- database.ts – CRUD operations against DB
- match.ts – import/validate match data
- publicResult.ts – serve public result pages
- sendgrid.ts – wrap SendGrid REST calls
- Middleware (src/middleware.ts) – JWT validation, role-based access

C. Database Layer
- Connection & Schema (src/lib/database/connect.tsx, schema.tsx)
- Database: PostgreSQL (or similar SQL DB) accessed via TypeORM/Prisma/knex (implied)

D. External Services
- SendGrid API – send transactional emails
- Storage (local .csv/.xlsx upload, or optional S3 for large files)

##### Relationships & Data Flows
- User → Frontend (React UI)
- Frontend → API Routes (HTTP/HTTPS, JSON)
- API Routes → Middleware → Authentication/Authorization → Database
- API Routes → Database Layer → Persistent Storage
- API Routes → SendGrid Service → Email Delivery
- File Upload → match.ts → CSV/XLSX parser → Database

##### Architectural Patterns
- Layered Architecture:
- Presentation Layer (Next.js pages & components)
- Application/API Layer (Next.js API routes + middleware)
- Data Access Layer (database connect & schema)
- External Integration Layer (SendGrid)
- Component-Based UI (React + Tailwind)
- Server-Side Rendering (Next.js) with API routes
- JWT-Based Authentication & Role-Based Authorization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and Frontend
    Browser[[Browser]]:::external
    subgraph "Next.js Frontend"
        PagesRouting["Pages & Routing"]:::frontend
        LoginPage["Login Page"]:::frontend
        AddUserPage["Add User Page"]:::frontend
        DashboardPages["Dashboard Pages"]:::frontend
        ResultsPages["Results Pages"]:::frontend
        SettingsPages["Settings Pages"]:::frontend
        UIComponents["UI Components"]:::frontend
        StylingConfig["Styling Config"]:::frontend
    end

    %% Server and Backend
    subgraph "Server"
        subgraph "API Routes" 
            UserAuthAPI["Auth API"]:::backend
            DatabaseAPI["Database CRUD API"]:::backend
            MatchImportAPI["Match Import API"]:::backend
            PublicResultsAPI["Public Results API"]:::backend
            SendGridAPI["SendGrid Integration API"]:::backend
        end
        Middleware["JWT/Auth Middleware"]:::backend
        DBConnect["DB Connection"]:::db
        DBSchema["DB Schema"]:::db
        Utils["Utils (CSV/XLSX Parser)"]:::util
    end

    %% Datastore and External
    Database[(Database)]:::db
    SendGrid((SendGrid API)):::external
    FileStorage[[File Storage]]:::util

    %% Flows
    Browser -->|"HTTPS"| PagesRouting
    PagesRouting -->|"POST /api/user/login"| UserAuthAPI
    PagesRouting -->|"GET/POST /api/database"| DatabaseAPI
    PagesRouting -->|"POST /api/match"| MatchImportAPI
    PagesRouting -->|"GET /api/publicResult"| PublicResultsAPI
    PagesRouting -->|"POST /api/sendgrid"| SendGridAPI
    PagesRouting -->|"File Upload"| FileStorage

    UserAuthAPI -->|"auth check"| Middleware
    DatabaseAPI -->|"auth check"| Middleware
    MatchImportAPI -->|"auth check"| Middleware
    SendGridAPI -->|"auth check"| Middleware
    PublicResultsAPI -->|"public access"| Middleware

    Middleware -->|"establish connection"| DBConnect
    DBConnect -->|"use schema"| DBSchema
    DBConnect -->|"SQL queries"| Database
    MatchImportAPI -->|"parse"| Utils
    Utils -->|"parsed data"| DBConnect

    SendGridAPI -->|"SendGrid REST call"| SendGrid
    FileStorage -->|"deliver file"| MatchImportAPI

    %% Click Events
    click PagesRouting "https://github.com/arunstha21/sendgrid-mailer/tree/main/src/app"
    click LoginPage "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/app/page.tsx"
    click AddUserPage "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/app/adduser/page.tsx"
    click DashboardPages "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/app/dashboard/[path]/page.tsx"
    click ResultsPages "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/app/results/page.tsx"
    click SettingsPages "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/app/settings/page.tsx"
    click UIComponents "https://github.com/arunstha21/sendgrid-mailer/tree/main/src/components"
    click StylingConfig "https://github.com/arunstha21/sendgrid-mailer/blob/main/tailwind.config.ts"
    click UserAuthAPI "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/server/user.ts"
    click DatabaseAPI "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/server/database.ts"
    click MatchImportAPI "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/server/match.ts"
    click PublicResultsAPI "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/server/publicResult.ts"
    click SendGridAPI "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/server/sendgrid.ts"
    click Middleware "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/middleware.ts"
    click DBConnect "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/lib/database/connect.tsx"
    click DBSchema "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/lib/database/schema.tsx"
    click Utils "https://github.com/arunstha21/sendgrid-mailer/blob/main/src/lib/utils.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef db fill:#fff3cd,stroke:#ffc107,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef util fill:#f8f9fa,stroke:#adb5bd,stroke-width:1px
```
