# yingtu35/gmail-cleaning-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/yingtu35/gmail-cleaning-scheduler
- Repository: https://github.com/yingtu35/gmail-cleaning-scheduler

## Overview

##### Main Components
- Frontend (Presentation Layer):
– Contains the “app” directory which includes pages (landing, dashboard, tasks, statistics) and UI components (e.g., auth components, sidebar, buttons, dashboards).
– Implements the user interface elements and hooks (e.g., useDropdown, useMultiStepForm) to facilitate user interactions.

- API/Backend (Server/Business Logic Layer):
– The “app/api” directory (with subfolders such as “auth” using Next‑Auth) exposes API endpoints to handle tasks like authentication and task scheduling requests.
– Business logic that orchestrates features like email filtering and task creation including integration with the AI assistant and AWS services.

- Data Persistence Layer:
– The “app/drizzle” folder holds database connection logic, migrations, and schema files that connect the application to a PostgreSQL database using Drizzle ORM.
– Utility functions in “app/utils/database.ts” further support data operations.

- AWS Integration Layer:
– The “app/aws” directory contains modules (client.ts, scheduler.ts, sns.ts) to interact with AWS services. These components likely handle serverless task scheduling (via Lambda and EventBridge Scheduler) and sending notifications using Amazon SNS.

- OpenAI Integration:
– The “app/openai” folder encapsulates the logic for communicating with the OpenAI API to facilitate the AI assistant feature for creating and reviewing Gmail deletion schedules.

- Authentication and External Integrations:
– Files like “auth.config.ts” and the “app/api/auth/[...nextauth]/route.ts” denote the use of Next‑Auth for handling user authentication.
– While Gmail isn’t explicitly represented in the file tree, the product’s purpose implies that there is an integration point (likely through user authentication and external API calls) for Gmail interaction.

##### Relationships and Interactions Between Components
- The Frontend sends user interactions (such as configuring filters or scheduling tasks) via HTTP requests to the API endpoints.
- The API/Backend layer processes these requests; it invokes business logic routines (possibly including calls to the OpenAI API) and interacts with AWS modules for scheduling.
- For data storage and retrieval, business logic utilizes the Drizzle ORM to execute SQL migrations and conduct operations on the PostgreSQL database.
- AWS modules (Lambda, EventBridge, SNS) are used to execute scheduled tasks asynchronously (e.g., perform Gmail cleaning, send notifications).
- Authentication flows are managed through the Next‑Auth API endpoints which secure the different parts of the system.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinct directories for API endpoints (business logic), UI components, database operations, AWS integrations, and third‑party API integration help isolate responsibilities.
- Serverless and Event‑Driven Components: The AWS integration modules illustrate a move toward serverless operations and scheduled tasks.
- Modular Structure: Using separate folders for OpenAI, AWS, Drizzle (database), and components reflects a modular design that supports maintenance and scalability.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: React, NextJS, Tailwind CSS, and shadcn‑ui.
- Backend/API: Next‑Auth, API routing in NextJS.
- Database: PostgreSQL with Drizzle ORM.
- AWS Services: AWS Lambda, Amazon EventBridge Scheduler, Amazon SNS.
- AI Assistant: OpenAI API.

##### Elements
- Configuration, hooks, or middleware as supplemental notes if they play a significant role in data handling or user request processing.

- That components such as “app/api/auth”, “app/aws”, “app/drizzle”, “app/openai”, and the UI directories are clearly labeled.
- Keep the design clear, simple, but detailed enough to capture the essential operational flow and integration points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    U("User"):::external

    %% Frontend UI Layer
    subgraph "Frontend UI"
        F_App("Main App"):::frontend
        F_Components("Components"):::frontend
        F_Hooks("Hooks"):::frontend
        F_Page("Page"):::frontend
        F_Statistics("Statistics Page"):::frontend
        F_Tasks("Tasks"):::frontend
        F_App -- "contains" --> F_Components
        F_App -- "uses" --> F_Hooks
        F_App -- "renders" --> F_Page
        F_App -- "renders" --> F_Statistics
        F_App -- "includes" --> F_Tasks
    end

    %% API / Backend Layer
    subgraph "API/Backend"
        B_API("API Endpoints"):::backend
        B_AuthAPI("Auth API"):::backend
        B_AuthConfig("Auth Config"):::auth
        B_API -- "handles" --> B_AuthAPI
        B_AuthAPI -- "configured_by" --> B_AuthConfig
    end

    %% Data Persistence (Database) Layer
    subgraph "Database"
        DB_Drizzle("Drizzle ORM"):::database
        DB_Utils("Database Utils"):::database
        DB_Drizzle -- "uses" --> DB_Utils
    end

    %% AWS Integration Layer
    subgraph "AWS Integration"
        AWS("AWS Integration"):::aws
        AWS_Client("AWS Client"):::aws
        AWS_Scheduler("AWS Scheduler"):::aws
        AWS_SNS("AWS SNS"):::aws
        AWS_Config("AWS Config"):::aws
        AWS -- "manages" --> AWS_Client
        AWS -- "triggers" --> AWS_Scheduler
        AWS -- "sends" --> AWS_SNS
        AWS -- "configured_by" --> AWS_Config
    end

    %% OpenAI Integration Layer
    subgraph "OpenAI Integration"
        OAI("OpenAI Integration"):::openai
        OAI_Chat("OpenAI Chat"):::openai
        OAI_Client("OpenAI Client"):::openai
        OAI -- "provides" --> OAI_Chat
        OAI -- "manages" --> OAI_Client
    end

    %% Main Data Flow
    U -->|"initiates"| F_App
    F_App -->|"HTTP"| B_API
    B_API -->|"data query"| DB_Drizzle
    B_API -->|"schedule"| AWS_Scheduler
    B_API -->|"AI request"| OAI_Chat
    B_API -->|"auth call"| B_AuthAPI

    %% Styling Classes
    classDef external fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef aws fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef openai fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef auth fill:#FFFFE0,stroke:#000,stroke-width:2px;

    %% Click Events for Frontend Components
    click F_App "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app"
    click F_Components "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/components"
    click F_Hooks "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/hooks"
    click F_Page "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/page.tsx"
    click F_Statistics "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/statistics/page.tsx"
    click F_Tasks "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/tasks"

    %% Click Events for API / Backend Components
    click B_API "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/api"
    click B_AuthAPI "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/api/auth/[...nextauth]/route.ts"
    click B_AuthConfig "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/auth.config.ts"

    %% Click Events for Database Components
    click DB_Drizzle "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/drizzle"
    click DB_Utils "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/utils/database.ts"

    %% Click Events for AWS Integration Components
    click AWS "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/aws"
    click AWS_Client "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/aws/client.ts"
    click AWS_Scheduler "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/aws/scheduler.ts"
    click AWS_SNS "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/aws/sns.ts"
    click AWS_Config "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/aws/config.ts"

    %% Click Events for OpenAI Integration Components
    click OAI "https://github.com/yingtu35/gmail-cleaning-scheduler/tree/main/app/openai"
    click OAI_Chat "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/openai/chat.ts"
    click OAI_Client "https://github.com/yingtu35/gmail-cleaning-scheduler/blob/main/app/openai/client.ts"
```
