# antoinepinto/docu-talk architecture

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

- Interactive diagram: https://gitdiagram.com/antoinepinto/docu-talk
- Repository: https://github.com/antoinepinto/docu-talk

## Overview

##### Project type and purpose
- Docu Talk is a full-stack, cloud-native web application that lets users upload documents and spin up AI chatbots against them.
- The front end is a React SPA; the back end is a FastAPI service. The system integrates with external services like MongoDB Atlas, Google Cloud Storage, a Gemini LLM, AWS SES, and OAuth providers (Google/Microsoft).

##### File structure
- Top-level:
- backend/ – FastAPI app (routers, config, credentials, docu_talk package, mailing, database code, machine learning agents)
- frontend/ – React + TypeScript + Vite (components for auth, chat, settings, dashboard)
- deploy/ – shell scripts for deploying front- and back-end containers
- Notice routers (auth, chatbots, settings), utilities (auth, parsing, file_io), and the docu_talk “agents” subpackage (chatbot and predictor) in the back end.
- Configuration files: Dockerfiles, pyproject.toml/requirements.txt, package.json, tsconfig.json, and environment examples.

##### README for additional insights
- Network architecture calls out Cloud Run hosting, a VPC/NAT setup to communicate safely with MongoDB Atlas, Cloud Storage for PDF files (signed URLs), and AWS SES for transactional email.
- Authentication via email/password + OAuth 2.0 (Google, Microsoft).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User"
        direction TB
        Browser["Web Browser/Mobile"]:::user
    end

    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        ReactSPA["React SPA"]:::frontend
        AuthContext["AuthContext"]:::frontend
        SocialButtons["SocialAuthButtons"]:::frontend
        PrivateRoute["PrivateRoute"]:::frontend
        CreatePage["CreateChatbot Page"]:::frontend
        DashboardPage["Dashboard Page"]:::frontend
        ChatPage["Chat Page"]:::frontend
        FileUploader["FileUploader"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI API)"
        direction TB
        FastAPIAPI["FastAPI API"]:::backend
        AuthRouter["auth.py Router"]:::backend
        CreateChatbotRouter["create_chatbot.py Router"]:::backend
        ChatbotsRouter["chatbots.py Router"]:::backend
        ChatbotSettingsRouter["chatbot_settings.py Router"]:::backend
        StorageAgent["storage.py Agent"]:::backend
        FileIO["file_io.py Util"]:::backend
        ChatbotAgent["chatbot.py Agent"]:::backend
        Generator["generator.py"]:::backend
        PredictorAgent["predictor.py Agent"]:::backend
        PredictorModels["Predictor Models"]:::backend
        DatabaseLayer["database.py Layer"]:::backend
        DBJobs["database jobs"]:::backend
        MailingBot["mailing_bot.py"]:::backend
        SESWrapper["aws_ses.py"]:::backend
        EmailTemplates["email templates"]:::backend
        ConfigLoader["config.py Loader"]:::backend
        ConfigJSON["config.json"]:::backend
        CredentialsStore["credentials"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB Atlas"]:::datastore
        CloudStorage["Google Cloud Storage"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["OAuth Providers (Google/Microsoft)"]:::external
        Gemini["Gemini LLM"]:::external
        SES["AWS SES"]:::external
    end

    %% Deploy Scripts
    subgraph "Deployment"
        direction TB
        DeployFE["deploy-frontend.sh"]:::deploy
        DeployBE["deploy-backend.sh"]:::deploy
    end

    %% Connections
    Browser -->|"HTTPS"| ReactSPA
    ReactSPA -->|"API Calls"| FastAPIAPI
    ReactSPA -->|"OAuth Redirects"| OAuth
    FastAPIAPI -->|"CRUD"| MongoDB
    FastAPIAPI -->|"Upload/Retrieve"| CloudStorage
    FastAPIAPI -->|"Generate"| Gemini
    FastAPIAPI -->|"Send Email"| SES
    FastAPIAPI -->|"Telemetry Logs"| MongoDB

    %% Frontend structure arrows
    ReactSPA --> AuthContext
    ReactSPA --> SocialButtons
    ReactSPA --> PrivateRoute
    ReactSPA --> CreatePage
    ReactSPA --> DashboardPage
    ReactSPA --> ChatPage
    CreatePage --> FileUploader

    %% Backend structure arrows
    FastAPIAPI --> AuthRouter
    FastAPIAPI --> CreateChatbotRouter
    FastAPIAPI --> ChatbotsRouter
    FastAPIAPI --> ChatbotSettingsRouter
    FastAPIAPI --> StorageAgent
    StorageAgent --> FileIO
    FastAPIAPI --> ChatbotAgent
    ChatbotAgent --> Generator
    FastAPIAPI --> PredictorAgent
    PredictorAgent --> PredictorModels
    FastAPIAPI --> DatabaseLayer
    DatabaseLayer --> DBJobs
    FastAPIAPI --> MailingBot
    MailingBot --> SESWrapper
    MailingBot --> EmailTemplates
    FastAPIAPI --> ConfigLoader
    ConfigLoader --> ConfigJSON
    ConfigLoader --> CredentialsStore

    %% Deployment arrows
    DeployFE --> ReactSPA
    DeployBE --> FastAPIAPI

    %% Click Events
    click ReactSPA "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/main.tsx"
    click AuthContext "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/components/auth/AuthContext.tsx"
    click SocialButtons "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/components/auth/SocialAuthButtons.tsx"
    click PrivateRoute "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/components/auth/PrivateRoute.tsx"
    click CreatePage "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/pages/CreateChatbot.tsx"
    click DashboardPage "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/pages/Dashboard.tsx"
    click ChatPage "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/pages/Chat.tsx"
    click FileUploader "https://github.com/antoinepinto/docu-talk/blob/master/frontend/src/components/create-chatbot/FileUploader.tsx"
    click FastAPIAPI "https://github.com/antoinepinto/docu-talk/blob/master/backend/main.py"
    click AuthRouter "https://github.com/antoinepinto/docu-talk/blob/master/backend/routers/auth.py"
    click CreateChatbotRouter "https://github.com/antoinepinto/docu-talk/blob/master/backend/routers/create_chatbot.py"
    click ChatbotsRouter "https://github.com/antoinepinto/docu-talk/blob/master/backend/routers/chatbots.py"
    click ChatbotSettingsRouter "https://github.com/antoinepinto/docu-talk/blob/master/backend/routers/chatbot_settings.py"
    click StorageAgent "https://github.com/antoinepinto/docu-talk/blob/master/backend/docu_talk/agents/storage.py"
    click FileIO "https://github.com/antoinepinto/docu-talk/blob/master/backend/utils/file_io.py"
    click ChatbotAgent "https://github.com/antoinepinto/docu-talk/blob/master/backend/docu_talk/agents/chatbot/chatbot.py"
    click Generator "https://github.com/antoinepinto/docu-talk/blob/master/backend/docu_talk/agents/chatbot/generator.py"
    click PredictorAgent "https://github.com/antoinepinto/docu-talk/blob/master/backend/docu_talk/agents/predictor/predictor.py"
    click PredictorModels "https://github.com/antoinepinto/docu-talk/tree/master/backend/docu_talk/agents/predictor/models/"
    click DatabaseLayer "https://github.com/antoinepinto/docu-talk/blob/master/backend/docu_talk/database/database.py"
    click DBJobs "https://github.com/antoinepinto/docu-talk/tree/master/backend/docu_talk/database/jobs/"
    click MailingBot "https://github.com/antoinepinto/docu-talk/blob/master/backend/mailing/mailing_bot.py"
    click SESWrapper "https://github.com/antoinepinto/docu-talk/blob/master/backend/mailing/aws_ses.py"
    click EmailTemplates "https://github.com/antoinepinto/docu-talk/tree/master/backend/mailing/templates/"
    click ConfigLoader "https://github.com/antoinepinto/docu-talk/blob/master/backend/config/config.py"
    click ConfigJSON "https://github.com/antoinepinto/docu-talk/blob/master/backend/config/config.json"
    click CredentialsStore "https://github.com/antoinepinto/docu-talk/tree/master/backend/credentials/"
    click DeployFE "https://github.com/antoinepinto/docu-talk/blob/master/deploy/deploy-frontend.sh"
    click DeployBE "https://github.com/antoinepinto/docu-talk/blob/master/deploy/deploy-backend.sh"

    %% Classes
    classDef user fill:#CCCCCC,stroke:#333,stroke-width:1px;
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef backend fill:#DFFFE0,stroke:#28A745,stroke-width:1px;
    classDef datastore fill:#FFEFD5,stroke:#FF8C00,stroke-width:1px;
    classDef external fill:#F3E0FF,stroke:#6F42C1,stroke-width:1px;
    classDef deploy fill:#F0F0F0,stroke:#888,stroke-width:1px;
```
