# tanujkumar24/personal-ai-agent-n8n architecture

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

- Interactive diagram: https://gitdiagram.com/tanujkumar24/personal-ai-agent-n8n
- Repository: https://github.com/tanujkumar24/personal-ai-agent-n8n

## Overview

##### Project type and purpose
- This is a low-code workflow automation project (built on n8n) that acts as an AI-powered personal assistant.
- It orchestrates multiple JSON-defined workflows to handle email management, calendar events, database operations, and RAG (Retrieval-Augmented Generation) using Pinecone + Groq LLMs, all exposed via a Telegram bot.

##### File structure
- Top-level JSON files (GET_CALANDER.json, SEND_EMAIL_WORKFLOW.json, etc.) are n8n workflow exports. Each represents one automation pipeline (e.g., “Get Calendar,” “Summarize Database”).
- There’s no “src” folder or code: the “source” is the collection of workflows.
- Configuration is through environment variables (.env) for API keys.
- README.md provides the high-level architecture and tech stack.

##### README for additional insights
- Core technologies: n8n (workflow engine), Pinecone (vector DB), Groq LLM (AI model), Telegram Bot API, Email & Calendar APIs.
- Use cases: automating business processes, AI-driven customer support, RAG queries.

a. Main components:
- User Interface: Telegram client (user’s chat app)
- Workflow Orchestrator: n8n server with JSON workflows
- Vector Store: Pinecone vector database
- LLM Service: Groq API
- External APIs: Email provider API, Calendar API
- (Optional) Metadata Store: where n8n persists workflow state (e.g., SQLite or Postgres)

b. Relationships & interactions:
1. User sends a message → Telegram Bot API
2. n8n “Telegram Trigger” node pulls the message
3. n8n processes the workflow JSON (e.g., “SUMMARIZE_DATABASE.json”)
– If it’s a RAG task:
· n8n “Pinecone Node” queries vector DB
· n8n “Groq Node” sends prompt + context to LLM
– If it’s email/calendar:
· n8n “HTTP Request” nodes call the Email/Calendar APIs
4. n8n collects responses, formats a reply, and sends it back via Telegram Bot API

c. Architectural patterns & principles:
- Event-driven integration: each workflow starts from a trigger node (Telegram or schedule).
- Single-responsibility JSON workflows: each file defines one pipeline.
- Clear separation between orchestration (n8n), AI services, and external data sources.

d. Key technologies & libraries:
- n8n: workflow automation engine
- Pinecone: vector search for RAG
- Groq API: AI language model for generation
- Telegram Bot API: user interface
- Email & Calendar REST APIs

##### Elements
- Clear labels: “Telegram Bot,” “n8n Workflow Engine,” “Pinecone Vector DB,” “Groq LLM Service,” “Email API,” “Calendar API,” “Workflow JSON Files.”
- From “User” to “Telegram Bot”
- From “Telegram Bot” to “n8n” (Trigger Node)
- From “n8n” to each external service (Pinecone, Groq, Email, Calendar)
- Orange for data stores (Pinecone, optional metadata DB)
- Grey for user interface (Telegram)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef internal fill:#D0E8FF,stroke:#005B9E,color:#000
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef datastore fill:#FEEFB3,stroke:#9F6000,color:#000
    classDef ui fill:#E0E0E0,stroke:#666,color:#000

    USER["User"]:::ui
    TELEGRAM["Telegram Bot API"]:::external
    CAL_API["Calendar API"]:::external
    EMAIL_API["Email API"]:::external
    PINECONE["Pinecone Vector DB"]:::datastore
    GROQ["Groq LLM Service"]:::external
    META_DB["Metadata Store (SQLite/Postgres)"]:::datastore

    USER -->|sends message| TELEGRAM
    TELEGRAM -->|"Telegram Trigger"| PERSONAL

    subgraph "n8n Workflow Engine" 
        direction TB
        ENV[".env Variables"]:::internal
        PERSONAL["PERSONAL_ASSISTANT.json"]:::internal
        GET["GET_CALANDER.json"]:::internal
        SET["SET_CALENDER.json"]:::internal
        SEND["SEND_EMAIL_WORKFLOW.json"]:::internal
        GGT["GGT_EMAIL_WORKFLOW.json"]:::internal
        SUM["SUMMARIZE_DATABASE.json"]:::internal
        UPD["UPDATE_DATABASE.json"]:::internal
        PUSH["PushData.json"]:::internal
        ENV --> PERSONAL
        PERSONAL --> GET
        PERSONAL --> SET
        PERSONAL --> SEND
        PERSONAL --> GGT
        PERSONAL --> SUM
        PERSONAL --> UPD
        PERSONAL --> PUSH
    end

    GET -->|query| CAL_API
    SET -->|update| CAL_API
    SEND -->|send email| EMAIL_API
    GGT -->|email ops| EMAIL_API
    SUM -->|vector query| PINECONE
    SUM -->|LLM call| GROQ
    UPD -->|store metadata| META_DB
    PUSH -->|push data| META_DB

    CAL_API -->|response| PERSONAL
    EMAIL_API -->|response| PERSONAL
    PINECONE -->|results| PERSONAL
    GROQ -->|generated text| PERSONAL
    META_DB -->|data| PERSONAL

    PERSONAL -->|reply| TELEGRAM
    TELEGRAM -->|delivers message| USER

    click PERSONAL "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/PERSONAL_ASSISTANT.json"
    click GET "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/GET_CALANDER.json"
    click SET "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/SET_CALENDER.json"
    click SEND "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/SEND_EMAIL_WORKFLOW.json"
    click GGT "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/GGT_EMAIL_WORKFLOW.json"
    click SUM "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/SUMMARIZE_DATABASE.json"
    click UPD "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/UPDATE_DATABASE.json"
    click PUSH "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/PushData.json"
    click README "https://github.com/tanujkumar24/personal-ai-agent-n8n/blob/main/README.md"
    click LICENSE "https://github.com/tanujkumar24/personal-ai-agent-n8n/tree/main/LICENSE"

    class USER,TELEGRAM,MAIL_API,EMAIL_API,ADDRESS external
    class CAL_API,EMAIL_API,PINECONE,MEDIA external
    class PERSONAL,GET,SET,SEND,GGT,SUM,UPD,PUSH,ENV internal
    class META_DB,PINECONE datastore
```
