How dopamine-max/agentic-sync-coordinator works
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).