# mouadbra/ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mouadbra/ai-agent
- Repository: https://github.com/mouadbra/ai-agent
- Video tour (about a minute): https://gitdiagram.com/mouadbra/ai-agent/video

## Overview

This is a chat-based executive assistant: users connect Google, ask for calendar or email actions, and receive an AI-generated reply. The frontend loads and resets conversation history and sends chat and OAuth-token requests to the FastAPI backend. The chat handler invokes the agent loop, which loads and saves the thread, calls Azure OpenAI, and dispatches any requested tool to Google Calendar or Gmail functions. OAuth credentials and conversation threads persist in SQLite on a Modal volume. The README documents all five tools; sampled backend code confirms their dispatch and integrations.

Main entry points: [`backend_service/src/modal_app/main.py`](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/main.py) (HTTP endpoints), [`frontend_service/src/App.tsx`](https://github.com/mouadbra/ai-agent/blob/main/frontend_service/src/App.tsx) (Chat and OAuth UI), [`backend_service/src/modal_app/agent.py`](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/agent.py) (Agent loop), [`backend_service/src/modal_app/functions.py`](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/functions.py) (Calendar and Gmail tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat frontend"]
  node_ui["Chat and OAuth UI<br/>[App.tsx]"]
end

subgraph group_api["Backend API"]
  node_api_routes["HTTP endpoints<br/>[main.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_agent_loop["Agent loop<br/>[agent.py]"]
  node_azure{{"Azure OpenAI"}}
  node_dispatcher["Tool dispatcher<br/>[functions.py]"]
end

subgraph group_integrations["Integrations and state"]
  node_google_tools["Calendar and Gmail tools<br/>[functions.py]"]
  node_google_apis{{"Google Calendar and Gmail"}}
  node_google_oauth{{"Google OAuth"}}
  node_sqlite[("SQLite database<br/>[main.py]")]
  node_modal_volume[("Modal volume<br/>[common.py]")]
end

node_user(("User"))

node_user -->|"sends requests"| node_ui
node_ui -->|"calls chat/history/reset"| node_api_routes
node_ui -->|"requests access token"| node_google_oauth
node_google_oauth -->|"returns token"| node_ui
node_ui -->|"posts token"| node_api_routes
node_api_routes -->|"processes chat"| node_agent_loop
node_agent_loop -->|"requests completion"| node_azure
node_agent_loop -->|"dispatches tool call"| node_dispatcher
node_dispatcher -->|"calls selected tool"| node_google_tools
node_google_tools -->|"reads credentials"| node_sqlite
node_google_tools -->|"calls Calendar/Gmail"| node_google_apis
node_agent_loop -->|"loads and saves thread"| node_sqlite
node_api_routes -->|"reads history; stores token"| node_sqlite
node_api_routes -->|"deletes thread"| node_sqlite
node_api_routes -->|"reloads and commits"| node_modal_volume

click node_ui "https://github.com/mouadbra/ai-agent/blob/main/frontend_service/src/App.tsx"
click node_api_routes "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/main.py"
click node_agent_loop "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/agent.py"
click node_dispatcher "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/functions.py"
click node_google_tools "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/functions.py"
click node_sqlite "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/main.py"
click node_modal_volume "https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/common.py"

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_ui,node_user toneBlue
class node_api_routes toneAmber
class node_agent_loop,node_azure,node_dispatcher toneMint
class node_google_tools,node_google_apis,node_google_oauth,node_sqlite,node_modal_volume toneRose
```

## Components

### Chat frontend

- [Chat and OAuth UI](https://github.com/mouadbra/ai-agent/blob/main/frontend_service/src/App.tsx): `frontend_service/src/App.tsx`

### Backend API

- [HTTP endpoints](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/main.py): `backend_service/src/modal_app/main.py`

### Agent orchestration

- [Agent loop](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/agent.py): `backend_service/src/modal_app/agent.py`
- **Azure OpenAI**
- [Tool dispatcher](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/functions.py): `backend_service/src/modal_app/functions.py`

### Integrations and state

- [Calendar and Gmail tools](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/functions.py): `backend_service/src/modal_app/functions.py`
- **Google Calendar and Gmail**
- **Google OAuth**
- [SQLite database](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/main.py): `backend_service/src/modal_app/main.py`
- [Modal volume](https://github.com/mouadbra/ai-agent/blob/main/backend_service/src/modal_app/common.py): `backend_service/src/modal_app/common.py`

### Other components

- **User**

## Connections

- User → Chat and OAuth UI: sends requests
- Chat and OAuth UI → HTTP endpoints: calls chat/history/reset
- Chat and OAuth UI → Google OAuth: requests access token
- Google OAuth → Chat and OAuth UI: returns token
- Chat and OAuth UI → HTTP endpoints: posts token
- HTTP endpoints → Agent loop: processes chat
- Agent loop → Azure OpenAI: requests completion
- Agent loop → Tool dispatcher: dispatches tool call
- Tool dispatcher → Calendar and Gmail tools: calls selected tool
- Calendar and Gmail tools → SQLite database: reads credentials
- Calendar and Gmail tools → Google Calendar and Gmail: calls Calendar/Gmail
- Agent loop → SQLite database: loads and saves thread
- HTTP endpoints → SQLite database: reads history; stores token
- HTTP endpoints → SQLite database: deletes thread
- HTTP endpoints → Modal volume: reloads and commits