# kalluru498/vertex_ai_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/kalluru498/vertex_ai_chatbot
- Repository: https://github.com/kalluru498/vertex_ai_chatbot

## Overview

##### Project type and purpose
- This is a full-stack web application (“AI Chat Assistant”) with:
- A single-page application (SPA) frontend built with TypeScript/React (Vite).
- A Python/Flask backend exposing HTTP endpoints.
- Integration with Google Cloud Vertex AI (PaLM/Gemini) for AI chat.
- Containerization via Docker and deployment on Google Cloud Run.

##### File structure
- Top-level config files:
- Dockerfile, .env.example, requirements.txt, package.json, tsconfig.json
- config.py loads environment variables.
- Backend code:
- app.py: Flask app, HTTP routes for chat.
- ai_service.py: wrapper around Google Vertex AI calls.
- templates/index.html: Flask serves initial HTML (or fallback).
- key.json: GCP service account key.
- Frontend code:
- src/ (Vite/React) – App.tsx, main.tsx, index.css.
- static/css, static/js/chat.js – supplemental styles and vanilla-JS chat logic.
- Build & tooling:
- vite.config.ts, tailwind.config.js, postcss.config.js, eslint.config.js
- Deployment:
- Dockerfile to build container.
- Cloud Run commands in README for pushing to GCR and deploying.

##### README for additional insights
- Describes clean chat UI, theme support, typing animations.
- Describes using Flask + Google Vertex AI SDK.
- Outlines local dev steps and GCP deployment to Cloud Run.

##### Main components and their interactions
a. Components
1. Browser SPA (React/Vite)
2. Static assets (CSS, JS)
3. Flask backend (app.py + ai_service.py)
4. Google Cloud Vertex AI service
5. Docker container / Cloud Run host
6. GCP IAM / Service-account for authentication
b. Relationships / data flows
1. User opens SPA in browser → initial HTML/CSS/JS served either by Flask or a static host.
2. SPA renders chat UI, user types message.
3. Frontend sends HTTP POST /chat to Flask (fetch or axios).
4. Flask endpoint receives payload, calls ai_service.py.
5. ai_service.py authenticates (key.json + GOOGLE_APPLICATION_CREDENTIALS) → sends request to Vertex AI API.
6. Vertex AI returns AI response.
7. Flask wraps result → sends JSON back to frontend.
8. Frontend renders AI reply in chat UI.
c. Architectural patterns / design principles
- 3-tier architecture (Client – Server – External AI Service).
- Separation of concerns: ai_service.py isolates AI calls; config.py handles env vars; templates + static for view layer.
- Infrastructure as Code: Dockerfile defines runtime; Cloud Run for serverless deployment.
d. Key technologies / frameworks
- Frontend: React, Vite, TypeScript, Tailwind CSS
- Backend: Flask, Python 3.7+, gunicorn (implicitly via Cloud Run)
- AI SDK: google-cloud-aiplatform
- Deployment: Docker, Google Cloud Run, GCR

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Browser SPA (React/Vite)"
        direction TB
        App["src/App.tsx"]:::frontend
        Main["src/main.tsx"]:::frontend
        CSSf["src/index.css"]:::frontend
        TSC["tsconfig.json"]:::frontend
        ViteCfg["vite.config.ts"]:::frontend
        TSCapp["tsconfig.app.json"]:::frontend
        TSCnode["tsconfig.node.json"]:::frontend
        EnvDts["vite-env.d.ts"]:::frontend
    end

    subgraph "Static Assets"
        direction TB
        SCSS["static/css/styles.css"]:::frontend
        SJ["static/js/chat.js"]:::frontend
    end

    %% Application Layer
    subgraph "Flask Backend"
        direction TB
        AppPy["app.py"]:::backend
        ConfigPy["config.py"]:::backend
        Req["requirements.txt"]:::backend
        PyCache["__pycache__/"]:::backend
    end

    subgraph "AI Service Wrapper"
        direction TB
        AIWrapper["ai_service.py"]:::backend
    end

    subgraph "HTML Templates"
        direction TB
        Templates["templates/index.html"]:::backend
        Fallback["index.html"]:::backend
    end

    subgraph "Credentials / IAM"
        direction TB
        Key["key.json"]:::backend
        EnvExample[".env.example"]:::backend
    end

    subgraph "Build & Tooling Configs"
        direction TB
        Pkg["package.json"]:::tooling
        PkgLock["package-lock.json"]:::tooling
        Postcss["postcss.config.js"]:::tooling
        Tailwind["tailwind.config.js"]:::tooling
        Eslint["eslint.config.js"]:::tooling
    end

    subgraph "Containerization / Deployment"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        README["README.md"]:::infra
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        Vertex["Google Vertex AI"]:::external
        GCR["GCR Registry"]:::infra
        CloudRun["Cloud Run"]:::infra
    end

    %% Data Flows
    App -->|"HTTP POST /chat"| AppPy
    SCSS --> App
    SJ --> App
    AppPy -->|"calls ai_service"| AIWrapper
    AIWrapper -->|"gRPC/REST"| Vertex
    Dockerfile --> Build["Docker Build"]:::infra
    Build -->|"push image"| GCR
    GCR -->|"deploy image"| CloudRun
    CloudRun -->|"hosts service"| AppPy

    %% Click Events
    click App "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/src/App.tsx"
    click Main "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/src/main.tsx"
    click CSSf "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/src/index.css"
    click TSC "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/tsconfig.json"
    click ViteCfg "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/vite.config.ts"
    click TSCapp "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/tsconfig.app.json"
    click TSCnode "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/tsconfig.node.json"
    click EnvDts "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/vite-env.d.ts"
    click SCSS "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/static/css/styles.css"
    click SJ "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/static/js/chat.js"
    click AppPy "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/app.py"
    click ConfigPy "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/config.py"
    click Req "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/requirements.txt"
    click PyCache "https://github.com/kalluru498/vertex_ai_chatbot/tree/main/__pycache__/"
    click AIWrapper "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/ai_service.py"
    click Templates "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/templates/index.html"
    click Fallback "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/index.html"
    click Key "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/key.json"
    click EnvExample "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/.env.example"
    click Dockerfile "https://github.com/kalluru498/vertex_ai_chatbot/tree/main/Dockerfile"
    click README "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/README.md"
    click Pkg "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/package.json"
    click PkgLock "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/package-lock.json"
    click Postcss "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/postcss.config.js"
    click Tailwind "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/tailwind.config.js"
    click Eslint "https://github.com/kalluru498/vertex_ai_chatbot/blob/main/eslint.config.js"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef tooling fill:#f0e68c,stroke:#000,stroke-width:1px
```
