# vj-e/automation-workflow architecture

> Architecture diagram of the GitHub repository vj-e/automation-workflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vj-e/automation-workflow
- Repository: https://github.com/vj-e/automation-workflow

## Overview

##### What this project is (type + purpose)

This is a **single Next.js 15 (App Router) application** that contains:
- A **visual workflow builder UI** (React + React Flow) where users compose automation workflows by connecting nodes.
- A minimal **backend execution endpoint** (Next.js API Route) that likely accepts a workflow definition and runs it (trigger → AI processing → integrations).
- Multiple **integration “node types”** (Gmail trigger, Gemini AI processor, Discord webhook, Google Sheets append, SMTP email sender).
- **No separate backend service** and **no database layer visible** in the tree (state is likely in-memory/client-side, and workflows are probably executed on-demand via the API route).

So architecturally, treat it as a **monolithic web app** with a **client-heavy editor** and a **server-side runner** that calls external services.

##### File tree interpretation (what maps to architecture)

Key directories/files and what they imply:

##### Backend/API
- `app/api/run/route.ts`
- The primary server-side “workflow execution” entrypoint. This is your “Orchestrator/Runner API”.

##### UI components (editor + runtime UX)
- `components/WorkflowEditor.tsx`
- The React Flow canvas, nodes/edges, graph editing.
- `components/NodeConfigPanel.tsx`
- Configuration UI for the selected node (credentials/parameters).
- `components/ExecutionConsole.tsx`
- Displays execution logs / run status (likely streaming/polling in UI).
- `components/Sidebar.tsx`, `components/TopBar.tsx`
- Supporting layout/navigation.

##### Node types
- `components/nodes/*Node.tsx`
- Frontend node renderers and likely node-specific configuration schemas/UX:
- `GmailTriggerNode.tsx` (IMAP trigger)
- `ProcessNode.tsx` (Gemini AI step)
- `DiscordNode.tsx` (Discord webhook)
- `GoogleSheetsNode.tsx` (Sheets API + auth)
- `EmailNode.tsx` (SMTP via Nodemailer)

##### Misc
- `check-models.js`
- Likely a helper script to validate Gemini models / connectivity. Consider it “dev tooling”, not core runtime.
- `next.config.ts`, `tsconfig.json`, `eslint.config.mjs`, `postcss.config.mjs`
- Build/tooling, not runtime components.

##### README-derived architectural constraints / integrations

- **Google Gemini API** (AI summarization/transform)
- **Gmail IMAP** (trigger) via `imap-simple`
- **SMTP** (email sending) via `nodemailer`
- **Discord Webhooks**
- **Google Sheets API** (append rows) with **Google Auth / Service Account** (`service-account.json`)

**environment/config**:
- `.env.local` variables: `GEMINI_API_KEY`, `EMAIL_USER`, `EMAIL_PASS`
- Service account JSON in root: `service-account.json`

##### Clear labels for each component
Use explicit names tied to the repo:
- “WorkflowEditor.tsx (React Flow Canvas)”
- “NodeConfigPanel.tsx”
- “ExecutionConsole.tsx”
- “API: /app/api/run/route.ts (Workflow Runner)”
- “Node Executors: GmailTrigger / Process(Gemini) / Discord / Sheets / Email”

- “Workflow JSON (nodes, edges, configs)”
- “Execution logs / step outputs”
- “Email body / subject”
- “Prompt + context”
- “Webhook payload”
- “Append row request”

##### Checklist to ensure you didn’t miss essential elements

- [ ] Credentials placement is correct (server-side).
- [ ] Data passed between nodes is depicted as “context” flowing through the runner (Email → AI → Discord/Sheets/Email).
- [ ] Logging path is shown (Runner → ExecutionConsole).

- Whether execution is synchronous vs async
- Whether logs are streamed (SSE) vs returned at end
- Whether Gmail is polled per request vs long-running listener

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Client / Browser
  %% =========================
  subgraph "Browser (Client)"
    direction TB

    UIEntry["Next.js App UI (App Router Pages)"]:::client
    LayoutShell["UI Shell (Layout + Styling)"]:::client
    Nav["Editor Navigation (Sidebar + TopBar)"]:::client

    Editor["WorkflowEditor (React Flow Canvas)"]:::client
    NodePanel["NodeConfigPanel (Selected Node Settings)"]:::client
    Console["ExecutionConsole (Logs / Status)"]:::client

    DAG["Workflow Definition (DAG JSON)\nNodes + Edges + Configs"]:::artifact
  end

  %% =========================
  %% Next.js App (Single deployable unit)
  %% =========================
  subgraph "Next.js 15 App (Server Runtime + API)"
    direction TB

    APIRun["API Route: /api/run\nWorkflow Runner Entry"]:::server

    Runner["Workflow Runner / Orchestrator\n(Executes DAG in order)"]:::server
    Context["Run Context\n(step outputs + shared data)"]:::artifact
    Logs["Execution Logs / Step Results"]:::artifact

    subgraph "Node Executors (Plugin-like Handlers)"
      direction TB
      ExecGmail["Gmail Trigger Executor\n(IMAP read/poll)"]:::server
      ExecGemini["AI Process Executor\n(Google Gemini)"]:::server
      ExecDiscord["Discord Executor\n(Webhook post)"]:::server
      ExecSheets["Sheets Executor\n(Append rows)"]:::server
      ExecEmail["Email Executor\n(SMTP send)"]:::server
    end

    Secrets["Secrets & Config Loader"]:::server
    EnvLocal[".env.local\nGEMINI_API_KEY, EMAIL_USER, EMAIL_PASS"]:::artifact
    ServiceAcct["service-account.json\n(Google Service Account)"]:::artifact

    OptionalNote["Note: No DB/Queue visible\nRuns likely on-demand per request"]:::note
  end

  %% =========================
  %% External Services
  %% =========================
  subgraph "External Services"
    direction TB

    GmailIMAP["Gmail IMAP Server\n(imap-simple)"]:::external
    GeminiAPI["Google Gemini API"]:::external
    DiscordWH["Discord Webhook Endpoint"]:::external
    GoogleAuth["Google Auth\n(Service Account)"]:::external
    SheetsAPI["Google Sheets API\n(append rows)"]:::external
    SMTPServer["SMTP Server\n(nodemailer)"]:::external
  end

  %% =========================
  %% Flows (Design-time and Run-time)
  %% =========================
  UIEntry -->|"renders_editor"| Editor
  LayoutShell -->|"wraps_pages"| UIEntry
  Nav -->|"controls_navigation"| UIEntry

  Editor -->|"select_node"| NodePanel
  NodePanel -->|"update_node_config"| Editor

  Editor -->|"builds"| DAG

  DAG -->|"Run_clicked: POST_workflow_JSON"| APIRun
  APIRun -->|"invoke"| Runner

  Secrets -->|"loads"| EnvLocal
  Secrets -->|"loads"| ServiceAcct
  Secrets -->|"provides_credentials"| Runner

  Runner -->|"initialize"| Context
  Runner -->|"emit_logs"| Logs
  Logs -->|"display"| Console

  Runner -->|"execute_step"| ExecGmail
  Runner -->|"execute_step"| ExecGemini
  Runner -->|"execute_step"| ExecDiscord
  Runner -->|"execute_step"| ExecSheets
  Runner -->|"execute_step"| ExecEmail

  %% External calls per executor
  ExecGmail <-->|"IMAP_read_unread_messages"| GmailIMAP
  ExecGemini -->|"prompt+context"| GeminiAPI
  GeminiAPI -->|"model_response"| ExecGemini

  ExecDiscord -->|"webhook_payload"| DiscordWH

  ExecSheets -->|"request_auth"| GoogleAuth
  GoogleAuth -->|"access_token"| ExecSheets
  ExecSheets -->|"append_row_request"| SheetsAPI

  ExecEmail -->|"send_email(subject/body)"| SMTPServer

  %% Return to client
  APIRun -->|"HTTP_response: logs+results"| Console

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click UIEntry "https://github.com/vj-e/automation-workflow/blob/main/app/page.tsx"
  click LayoutShell "https://github.com/vj-e/automation-workflow/blob/main/app/layout.tsx"
  click LayoutShell "https://github.com/vj-e/automation-workflow/blob/main/app/globals.css"

  click Editor "https://github.com/vj-e/automation-workflow/blob/main/components/WorkflowEditor.tsx"
  click NodePanel "https://github.com/vj-e/automation-workflow/blob/main/components/NodeConfigPanel.tsx"
  click Console "https://github.com/vj-e/automation-workflow/blob/main/components/ExecutionConsole.tsx"
  click Nav "https://github.com/vj-e/automation-workflow/blob/main/components/Sidebar.tsx"
  click Nav "https://github.com/vj-e/automation-workflow/blob/main/components/TopBar.tsx"

  click APIRun "https://github.com/vj-e/automation-workflow/blob/main/app/api/run/route.ts"

  click ExecGmail "https://github.com/vj-e/automation-workflow/blob/main/components/nodes/GmailTriggerNode.tsx"
  click ExecGemini "https://github.com/vj-e/automation-workflow/blob/main/components/nodes/ProcessNode.tsx"
  click ExecDiscord "https://github.com/vj-e/automation-workflow/blob/main/components/nodes/DiscordNode.tsx"
  click ExecSheets "https://github.com/vj-e/automation-workflow/blob/main/components/nodes/GoogleSheetsNode.tsx"
  click ExecEmail "https://github.com/vj-e/automation-workflow/blob/main/components/nodes/EmailNode.tsx"

  click OptionalNote "https://github.com/vj-e/automation-workflow/blob/main/check-models.js"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1px
  classDef server fill:#2e7d32,stroke:#1b5e20,color:#ffffff,stroke-width:1px
  classDef external fill:#fb8c00,stroke:#e65100,color:#111111,stroke-width:1px
  classDef artifact fill:#eceff1,stroke:#607d8b,color:#111111,stroke-width:1px
  classDef note fill:#f3e5f5,stroke:#6a1b9a,color:#111111,stroke-dasharray:4 3,stroke-width:1px
```
