# kimthangg/neura_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/kimthangg/neura_assistant
- Repository: https://github.com/kimthangg/neura_assistant

## Overview

##### Project type and purpose
- Neura is a full-stack AI personal assistant: web frontend (chat UI) + Python/Flask backend.
- It orchestrates natural-language requests to Google Calendar/Gmail APIs and an LLM service, persisting conversation data in MongoDB.

##### File structure to high-level components
- **Frontend** (app/static, app/templates) → HTML/CSS/JS chat UI served by Flask.
- **Web Server** (app/app.py) → Flask app, defines `/chat` and `/execute` endpoints.
- **Bot Module** (bot/)
- agent/ → Intent‐driven “agents” (agent_calendar, agent_gmail, agent_manager)
- handler/ → Message ingestor & retrieval logic
- agent_intent/ → Prompt & tool definitions for intent extraction
- **Feature Plugins** (features/) → Domain-specific handlers/prompts/tools
- calendar_features/*
- gmail_features/*
- schedule_features
- **Services** (services/)
- llm/ → LLM config (e.g., Gemini 2.0 calls)
- embedding_model/ → Embedding logic for retrieval
- **Data Access** (db/) → MongoDB managers (chat_manager, email_manager, schedule_manager, etc.)
- **Configuration** (config/) → Google API credentials and auth logic
- **Utilities & Tests** (utils/, tests/)

##### Refine with README insights
- Two primary layers: Frontend (browser chat) ↔ Backend (Flask + Bot Module).
- External dependencies: Google Calendar API, Gmail API, Gemini 2.0 (LLM), MongoDB.

##### Relationships & data flows
1. User types message → Web UI
2. Web UI → POST JSON → Flask `/chat`
3. Flask Handler → Agent Manager
4. Agent Manager → selects Agent → invokes feature prompt/tools → calls LLM Service
5. LLM response → Agent processes → may call external API (Calendar/Gmail)
6. External API → result → Agent formats reply → Handler
7. Handler → stores conversation via db/chat_manager → returns JSON to UI
8. UI displays reply; on “Execute” button click → Flask `/execute` → repeat steps for real action

##### Architectural patterns & design principles
- Layered architecture: Presentation → API layer (Flask) → Business logic (Bot Module) → Data layer (DB)
- Plug-in module pattern for features (each calendar/email feature lives in its own folder)
- Separation of concerns: intent extraction, routing, API integration, data persistence
- Single Responsibility: one class per API/feature

##### Technologies, frameworks & libraries
- Frontend: HTML5, CSS3, vanilla JavaScript
- Backend: Python 3.10+, Flask
- LLM integration: custom wrapper in services/llm (Gemini 2.0)
- Database: MongoDB (accessed via db/db_manager and specialized managers)
- Authentication: Google OAuth2 (config/auth_gg.py)
- Testing: pytest (tests/…)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ChatUI["Chat UI\n(HTML/CSS/JS)"]:::frontend
    end

    %% Backend Core
    subgraph "Backend Layer"
        direction TB
        FlaskApp["Flask App\n(/chat, /execute)"]:::backend

        subgraph "Bot Engine"
            direction TB
            subgraph "Handler"
                direction TB
                MessageHandler["Message Handler"]:::backend
                RetrievalHandler["Retrieval Handler"]:::backend
            end
            AgentManager["Agent Manager"]:::backend
            subgraph "Agents"
                direction TB
                AgentCalendar["Agent Calendar"]:::backend
                AgentGmail["Agent Gmail"]:::backend
                AgentSchedule["Schedule Task"]:::backend
                BotTelegram["Bot Telegram"]:::backend
            end
            subgraph "Intent Extraction"
                direction TB
                IntentPrompt["Prompt"]:::backend
                IntentTools["Tools"]:::backend
            end
        end
    end

    %% Services & External
    subgraph "Cloud Services"
        direction TB
        LLMService["LLM Service\n(Gemini 2.0)"]:::external
        EmbeddingService["Embedding Service"]:::external
        ExternalCalendar["Google Calendar API"]:::external
        ExternalGmail["Gmail API"]:::external
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        DBManagers["DB Managers\n(MongoDB)"]:::database
    end

    %% Flows
    ChatUI -->|HTTP/JSON| FlaskApp
    FlaskApp -->|payload| MessageHandler
    FlaskApp -->|retrieval request| RetrievalHandler
    MessageHandler -->|intent JSON| AgentManager
    RetrievalHandler -->|context| AgentManager
    AgentManager -->|route| AgentCalendar
    AgentManager -->|route| AgentGmail
    AgentManager -->|route| AgentSchedule
    AgentManager -->|route| BotTelegram

    AgentCalendar -->|uses| IntentPrompt
    AgentCalendar -->|uses| IntentTools
    AgentGmail -->|uses| IntentPrompt
    AgentGmail -->|uses| IntentTools
    AgentSchedule -->|uses| IntentPrompt
    AgentSchedule -->|uses| IntentTools
    BotTelegram -->|uses| IntentPrompt
    BotTelegram -->|uses| IntentTools

    AgentCalendar -->|LLM request| LLMService
    AgentGmail -->|LLM request| LLMService
    AgentSchedule -->|LLM request| LLMService
    BotTelegram -->|LLM request| LLMService

    LLMService -->|response| AgentCalendar
    LLMService -->|response| AgentGmail
    LLMService -->|response| AgentSchedule
    LLMService -->|response| BotTelegram

    AgentCalendar -->|API call| ExternalCalendar
    AgentGmail -->|API call| ExternalGmail

    AgentCalendar -->|store| DBManagers
    AgentGmail -->|store| DBManagers
    AgentSchedule -->|store| DBManagers
    MessageHandler -->|save chat| DBManagers

    MessageHandler -->|response JSON| FlaskApp
    FlaskApp -->|HTTP/JSON| ChatUI

    %% Optional embedding
    MessageHandler -->|semantic search| EmbeddingService
    RetrievalHandler -->|embedding| EmbeddingService

    %% Click Events
    click ChatUI "https://github.com/kimthangg/neura_assistant/blob/main/app/templates/index.html"
    click FlaskApp "https://github.com/kimthangg/neura_assistant/blob/main/app/app.py"
    click MessageHandler "https://github.com/kimthangg/neura_assistant/blob/main/bot/handler/message.py"
    click RetrievalHandler "https://github.com/kimthangg/neura_assistant/blob/main/bot/handler/retrieval_infomation.py"
    click AgentManager "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent/agent_manager.py"
    click AgentCalendar "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent/agent_calendar.py"
    click AgentGmail "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent/agent_gmail.py"
    click AgentSchedule "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent/schedule_task.py"
    click BotTelegram "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent/bot_telegram.py"
    click IntentPrompt "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent_intent/prompt.py"
    click IntentTools "https://github.com/kimthangg/neura_assistant/blob/main/bot/agent_intent/tools.py"
    click LLMService "https://github.com/kimthangg/neura_assistant/blob/main/services/llm/llm_config.py"
    click EmbeddingService "https://github.com/kimthangg/neura_assistant/blob/main/services/embedding_model/embedding.py"
    click DBManagers "https://github.com/kimthangg/neura_assistant/blob/main/db/db_manager.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef external fill:#FFF4D6,stroke:#DAA520,color:#DAA520;
    classDef database fill:#FFF0D9,stroke:#CC8400,color:#CC8400;
```
