# dopamine-max/agentic-sync-coordinator architecture

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

- Interactive diagram: https://gitdiagram.com/dopamine-max/agentic-sync-coordinator
- Repository: https://github.com/dopamine-max/agentic-sync-coordinator

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Agentic Sync Coordinator”) combining a React/Vite frontend and a FastAPI backend.
- Its goal is to provide a natural-language chat interface that invokes Google Workspace tools (Calendar, Drive, Gmail, Tasks, Contacts) via a simple API layer.

##### File Structure Analysis
- Top-level directories:
- Backend/ – FastAPI application entry point (main.py), Python dependency config (pyproject.toml), lock file.
- Frontend/ – Vite/React project with package.json, Tailwind CSS, and rich UI component library under src/components.
- Frontend/src/lib contains wrappers for API calls (api.ts, auth.ts, utils.ts).
- No persistent database directory—conversation history lives in backend memory.
- Standard config files: ESLint, Tailwind, TypeScript, Vite, PostCSS.

##### README Takeaways
- Frontend uses Axios to call three endpoints:
- GET /query – process user queries and invoke tools.
- GET /ping – health check & trigger auth flow.
- POST /reset – clear conversation buffer.
- Backend orchestrates calls to Google Workspace via tool modules (calendar_tools.py, drive_tools.py, etc.).
- Planned cloud deployment will delegate OAuth to frontend issuing Bearer tokens.

##### Main Components
a. Frontend Application
– React/Vite UI, Axios-based HTTP client, component library, Tailwind CSS styling.
– Pages: Landing, Chat, NotFound; components for chat header, messages, input, protected routes.
b. Backend API Server
– FastAPI app (main.py) exposing /query, /ping, /reset.
– In-memory conversation manager.
c. Tool Orchestrator Modules (MCP)
– Python packages for Calendar, Drive, Gmail, Tasks, Contacts.
– Each module implements tool functions (list, create, modify, delete).
d. External Services
– Google Workspace REST APIs (OAuth 2.0, Gmail API, Calendar API, Drive API, Tasks API, Contacts API).

##### Relationships and Data Flow
1. User → React UI
- User types query.
2. React UI → FastAPI (/query)
- Axios GET /query?q=…
3. FastAPI → Tool Orchestrator
- Conversation buffer updated → AI/NLP processing → tool function calls.
4. Tool Orchestrator → Google Workspace APIs
- Authenticated HTTP calls to Google endpoints.
5. Responses bubble back (Google → Orchestrator → FastAPI → React)
- UI renders chat message and tool metadata.
6. Authentication Flow
- React triggers /ping to start OAuth, receives redirect URL or token, stores Bearer token for subsequent calls.
7. Reset Flow
- React POST /reset to clear the in-memory buffer.

##### Architectural Patterns and Design Principles
- Separation of concerns: UI layer, API layer, tool-specific modules.
- Stateless frontend, stateful backend (in memory).
- Modular tool design for easy extension (add new Google tools or 3rd-party services).
- Clear layers: Presentation → Orchestration → External API.

##### Essential Elements without Overthinking
- Stateful vs. stateless components (memory buffer, UI store).

## Diagram (Mermaid)

```mermaid
graph TB
  %% Frontend Layer
  subgraph "Frontend Application"
    direction TB
    EntryPoint["main.tsx"]:::frontend
    MainUI["React UI"]:::frontend
    subgraph "Pages"
      ChatPage["Chat Page"]:::frontend
      LandingPage["Landing Page"]:::frontend
      NotFoundPage["404 Page"]:::frontend
    end
    subgraph "Components"
      ChatHeader["Chat Header"]:::frontend
      ChatMessage["Chat Message"]:::frontend
      MessageInput["Message Input"]:::frontend
      ToolCallDisplay["Tool Call Display"]:::frontend
      ProtectedRoute["Protected Route Handler"]:::frontend
    end
    subgraph "Lib"
      ApiWrapper["api.ts"]:::frontend
      AuthUtil["auth.ts"]:::frontend
      Utils["utils.ts"]:::frontend
      ApiClient["Axios HTTP Client"]:::frontend
      AuthStore["Auth Token Store"]:::frontend
    end
  end

  %% Backend Layer
  subgraph "Backend API Server"
    direction TB
    FastAPIRouter["FastAPI /query, /ping, /reset"]:::backend
    Conversation["Conversation Manager<br/>(In-Memory)"]:::database
    subgraph "Tool Orchestrator Modules"
      Calendar["Calendar Tools Module"]:::backend
      Drive["Drive Tools Module"]:::backend
      Gmail["Gmail Tools Module"]:::backend
      Tasks["Tasks Tools Module"]:::backend
      Contacts["Contacts Tools Module"]:::backend
    end
  end

  %% External Services
  subgraph "Google Workspace APIs"
    direction TB
    CalendarAPI["Calendar API"]:::external
    DriveAPI["Drive API"]:::external
    GmailAPI["Gmail API"]:::external
    TasksAPI["Tasks API"]:::external
    ContactsAPI["Contacts API"]:::external
  end

  %% User
  User(("User")):::external

  %% Flows
  User -->|"types query"| ChatPage
  ChatPage -->|"uses Axios"| ApiClient
  ApiClient -->|"GET /query"| FastAPIRouter
  FastAPIRouter -->|"update buffer"| Conversation
  FastAPIRouter -->|"invoke tool"| Calendar
  FastAPIRouter -->|"invoke tool"| Drive
  FastAPIRouter -->|"invoke tool"| Gmail
  FastAPIRouter -->|"invoke tool"| Tasks
  FastAPIRouter -->|"invoke tool"| Contacts

  Calendar -->|"calls"| CalendarAPI
  Drive -->|"calls"| DriveAPI
  Gmail -->|"calls"| GmailAPI
  Tasks -->|"calls"| TasksAPI
  Contacts -->|"calls"| ContactsAPI

  CalendarAPI --> Calendar
  DriveAPI --> Drive
  GmailAPI --> Gmail
  TasksAPI --> Tasks
  ContactsAPI --> Contacts

  Calendar --> FastAPIRouter
  Drive --> FastAPIRouter
  Gmail --> FastAPIRouter
  Tasks --> FastAPIRouter
  Contacts --> FastAPIRouter

  FastAPIRouter -->|"response"| ApiClient
  ApiClient --> ChatPage

  %% Auth Flow
  ChatPage -->|"trigger auth (GET /ping)"| ApiClient
  ApiClient -->|"GET /ping"| FastAPIRouter
  FastAPIRouter -->|"returns token/URL"| AuthStore
  AuthStore -->|"stores Bearer token"| ApiClient

  %% Reset Flow
  ChatPage -->|"POST /reset"| ApiClient
  ApiClient -->|"POST /reset"| FastAPIRouter
  FastAPIRouter -->|"clears"| Conversation

  %% Click Events Frontend
  click Frontend "https://github.com/dopamine-max/agentic-sync-coordinator/tree/main/Frontend/"
  click MainUI "https://github.com/dopamine-max/agentic-sync-coordinator/tree/main/Frontend/"
  click EntryPoint "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/main.tsx"
  click ChatPage "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/pages/Chat.tsx"
  click LandingPage "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/pages/Landing.tsx"
  click NotFoundPage "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/pages/NotFound.tsx"
  click ChatHeader "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/components/ChatHeader.tsx"
  click ChatMessage "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/components/ChatMessage.tsx"
  click MessageInput "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/components/MessageInput.tsx"
  click ToolCallDisplay "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/components/ToolCallDisplay.tsx"
  click ProtectedRoute "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/components/ProtectedRoute.tsx"
  click ApiWrapper "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/lib/api.ts"
  click AuthUtil "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/lib/auth.ts"
  click Utils "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Frontend/src/lib/utils.ts"

  %% Click Events Backend
  click FastAPIRouter "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/main.py"
  click Conversation "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/main.py"
  click Calendar "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/calendar_tools.py"
  click Drive "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/drive_tools.py"
  click Gmail "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/gmail_tools.py"
  click Tasks "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/tasks_tools.py"
  click Contacts "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/contacts_tools.py"
  click Backend "https://github.com/dopamine-max/agentic-sync-coordinator/tree/main/Backend/"
  click pyproject "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/pyproject.toml"
  click uvlock "https://github.com/dopamine-max/agentic-sync-coordinator/blob/main/Backend/uv.lock"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#024;stroke-width:1px
  classDef backend fill:#D0FFD6,stroke:#080;stroke-width:1px
  classDef external fill:#FFE0B2,stroke:#E80;stroke-width:1px
  classDef database fill:#FFF2CC,stroke:#AA0;stroke-width:1px
```
