# ai-ml-eidiko/eidiko_chatbot architecture

> Architecture diagram of the GitHub repository ai-ml-eidiko/eidiko_chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-ml-eidiko/eidiko_chatbot
- Repository: https://github.com/ai-ml-eidiko/eidiko_chatbot

## Overview

EIDIKO is a local chatbot for finding documents and metadata in a user’s Google account, with optional, explicitly confirmed email, calendar, and Sheets writes. The main flow runs from chat UI through Flask query routing, safety checks/redaction, Google search, and LLM-assisted summaries back to result cards. The graph also shows attachment downloads and the separate confirm-before-write path. The README documents product capabilities not fully visible in the excerpts; their links are cited to the README rather than implying uninspected implementation details.

Main entry points: [`app.py`](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py) (Flask API), [`app.js`](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.js) (Chat UI), [`google_client.py`](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py) (Gmail search), [`claude_client.py`](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/claude_client.py) (Query and summary LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_chat_ui["Chat UI<br/>[app.js]"]
  node_page["Chat page<br/>[index.html]"]
  node_result_cards["Result cards<br/>[app.js]"]
end

subgraph group_routing["Request handling"]
  node_flask["Flask API<br/>[app.py]"]
  node_query_router["Query routing<br/>[app.py]"]
  node_write_confirm["Write confirmation<br/>[app.py]"]
  node_attachment_download["Attachment download<br/>[app.py]"]
end

subgraph group_services["Google and language services"]
  node_google_auth["Google OAuth<br/>[google_client.py]"]
  node_gmail_search["Gmail search<br/>[google_client.py]"]
  node_drive_search["Drive search<br/>[google_client.py]"]
  node_calendar["Calendar search and writes<br/>[google_client.py]"]
  node_sheets["Sheets search and writes<br/>[google_client.py]"]
  node_email_send["Email sending<br/>[google_client.py]"]
  node_llm["Query and summary LLM<br/>[claude_client.py]"]
end

subgraph group_safety["Privacy controls"]
  node_redaction["Text redaction<br/>[redact.py]"]
  node_blocked_query["Secret-query blocking<br/>[redact.py]"]
end

node_user(("User"))
node_google{{"Google APIs"}}
node_groq{{"Groq API"}}
node_browser_downloads(("Browser downloads"))

node_user -->|"asks or confirms"| node_chat_ui
node_page -->|"hosts"| node_chat_ui
node_chat_ui -->|"sends chat requests"| node_flask
node_flask -->|"routes requests"| node_query_router
node_query_router -->|"checks query"| node_blocked_query
node_query_router -->|"proposes writes"| node_write_confirm
node_write_confirm -->|"returns confirmation prompt"| node_chat_ui
node_chat_ui -->|"submits confirmation"| node_flask
node_write_confirm -->|"executes confirmed action"| node_email_send
node_write_confirm -->|"executes confirmed action"| node_calendar
node_write_confirm -->|"executes confirmed action"| node_sheets
node_query_router -->|"uses credentials"| node_google_auth
node_flask -->|"searches account"| node_gmail_search
node_flask -->|"searches account"| node_drive_search
node_flask -->|"searches events"| node_calendar
node_flask -->|"searches sheets"| node_sheets
node_flask -->|"scrubs retrieved text"| node_redaction
node_flask -->|"extracts or summarizes"| node_llm
node_llm -->|"requests completions"| node_groq
node_gmail_search -->|"reads metadata"| node_google
node_drive_search -->|"reads metadata"| node_google
node_calendar -->|"reads or writes events"| node_google
node_sheets -->|"reads or writes cells"| node_google
node_email_send -->|"sends email"| node_google
node_flask -->|"routes download"| node_attachment_download
node_attachment_download -->|"fetches attachment bytes"| node_gmail_search
node_attachment_download -->|"streams file"| node_browser_downloads
node_flask -->|"returns search results"| node_result_cards
node_result_cards -->|"shows links and metadata"| node_user

click node_chat_ui "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.js"
click node_page "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/index.html"
click node_flask "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py"
click node_query_router "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py"
click node_write_confirm "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py"
click node_attachment_download "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py"
click node_google_auth "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_gmail_search "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_drive_search "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_calendar "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_sheets "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_email_send "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py"
click node_llm "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/claude_client.py"
click node_redaction "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/redact.py"
click node_blocked_query "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/redact.py"
click node_result_cards "https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_ui,node_page,node_result_cards,node_user,node_browser_downloads toneBlue
class node_flask,node_query_router,node_write_confirm,node_attachment_download toneAmber
class node_google_auth,node_gmail_search,node_drive_search,node_calendar,node_sheets,node_email_send,node_llm,node_google,node_groq toneMint
class node_redaction,node_blocked_query toneRose
```

## Components

### Chat interface

- [Chat UI](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.js): `app.js`
- [Chat page](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/index.html): `index.html`
- [Result cards](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.js): `app.js`

### Request handling

- [Flask API](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py): `app.py`
- [Query routing](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py): `app.py`
- [Write confirmation](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py): `app.py`
- [Attachment download](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/app.py): `app.py`

### Google and language services

- [Google OAuth](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Gmail search](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Drive search](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Calendar search and writes](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Sheets search and writes](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Email sending](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/google_client.py): `google_client.py`
- [Query and summary LLM](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/claude_client.py): `claude_client.py`

### Privacy controls

- [Text redaction](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/redact.py): `redact.py`
- [Secret-query blocking](https://github.com/ai-ml-eidiko/eidiko_chatbot/blob/main/redact.py): `redact.py`

### Other components

- **User**
- **Google APIs**
- **Groq API**
- **Browser downloads**

## Connections

- User → Chat UI: asks or confirms (evidence: `README.md`)
- Chat page → Chat UI: hosts (evidence: `app.js`)
- Chat UI → Flask API: sends chat requests (evidence: `app.js`)
- Flask API → Query routing: routes requests (evidence: `README.md`)
- Query routing → Secret-query blocking: checks query (evidence: `README.md`)
- Query routing → Write confirmation: proposes writes (evidence: `app.py`)
- Write confirmation → Chat UI: returns confirmation prompt (evidence: `app.py`)
- Chat UI → Flask API: submits confirmation (evidence: `app.js`)
- Write confirmation → Email sending: executes confirmed action (evidence: `README.md`)
- Write confirmation → Calendar search and writes: executes confirmed action (evidence: `app.py`)
- Write confirmation → Sheets search and writes: executes confirmed action (evidence: `README.md`)
- Query routing → Google OAuth: uses credentials (evidence: `app.py`)
- Flask API → Gmail search: searches account (evidence: `README.md`)
- Flask API → Drive search: searches account (evidence: `README.md`)
- Flask API → Calendar search and writes: searches events (evidence: `README.md`)
- Flask API → Sheets search and writes: searches sheets (evidence: `app.py`)
- Flask API → Text redaction: scrubs retrieved text (evidence: `app.py`)
- Flask API → Query and summary LLM: extracts or summarizes (evidence: `app.py`)
- Query and summary LLM → Groq API: requests completions (evidence: `claude_client.py`)
- Gmail search → Google APIs: reads metadata (evidence: `README.md`)
- Drive search → Google APIs: reads metadata (evidence: `README.md`)
- Calendar search and writes → Google APIs: reads or writes events (evidence: `README.md`)
- Sheets search and writes → Google APIs: reads or writes cells (evidence: `README.md`)
- Email sending → Google APIs: sends email (evidence: `README.md`)
- Flask API → Attachment download: routes download (evidence: `README.md`)
- Attachment download → Gmail search: fetches attachment bytes (evidence: `app.py`)
- Attachment download → Browser downloads: streams file (evidence: `README.md`)
- Flask API → Result cards: returns search results (evidence: `app.py`)
- Result cards → User: shows links and metadata (evidence: `README.md`)
