# jainyash0614/ai-doctor-appointment-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/jainyash0614/ai-doctor-appointment-assistant
- Repository: https://github.com/jainyash0614/ai-doctor-appointment-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack AI-powered doctor appointment booking system.
- Frontend: React/TypeScript SPA for patient & doctor portals.
- Backend: FastAPI service handling chat, booking logic, Google OAuth, and database operations.
- Database: PostgreSQL via SQLAlchemy.
- External services: Mistral AI for natural-language processing, Google Calendar & Gmail APIs for scheduling & notifications.

##### Main Components
- **User Interface**
- React App (App.tsx, pages, Chat component)
- Routes: Landing, PatientChat, DoctorChat
- **API Layer (Backend)**
- FastAPI application (main.py)
- Authentication module (auth.py)
- Chat endpoints & conversation flow (/chat, /doctors, /appointments, /health)
- **Business Logic / Tool Server**
- MCP Server (mcp_server.py): implements booking/checking logic
- Mistral AI clients (mistral_client.py, simple_mistral_client.py)
- **Data Layer**
- Database module (database.py)
- SQLAlchemy models (models.py)
- PostgreSQL instance (local or Docker)
- **External Integrations**
- Mistral AI API
- Google Calendar API
- Gmail API
- **Infrastructure / Deployment**
- Dockerfiles (frontend, backend)
- Optional docker-compose.yml for PostgreSQL

##### Relationships & Data Flows
1. **User** → interacts with **React UI** in browser
2. **React** uses Axios → **FastAPI frontend endpoints**
3. **FastAPI** hands off to **Mistral client** for NLP intent detection
4. **MCP Server** executes domain logic (availability checks, booking)
5. **Database** reads/writes appointment & doctor data
6. **Google Calendar & Gmail APIs** create events & send confirmations
7. **FastAPI** returns natural-language response to **React** → **User**

##### Architectural Patterns & Design Principles
- **Layered Architecture:** UI, API, business logic, data, external services
- **Separation of Concerns:** distinct modules for auth, chat, data access, AI clients
- **Tool Integration (MCP Protocol):** treat booking logic as a microservice within backend
- **API‐First Design:** Swagger docs auto-generated by FastAPI (/docs)
- **Dockerized Components:** repeatable dev & prod environments

##### Key Technologies & Frameworks
- Frontend: React 18, TypeScript, React Router, Axios
- Backend: FastAPI, Uvicorn, SQLAlchemy
- Database: PostgreSQL
- AI: Mistral API (via custom client)
- External APIs: Google Calendar & Gmail (via OAuth)
- DevOps: Docker, (optional) docker-compose

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User & Browser"
        direction TB
        User["User"]:::external
        Browser["Browser"]:::external
        User -->|"interacts via HTTP"| Browser
    end

    %% Frontend Layer
    subgraph "Frontend (Docker port 3000)"
        direction TB
        FE["React SPA"]:::ui
        App["App.tsx"]:::ui
        Chat["Chat.tsx"]:::ui
        Landing["Landing.tsx"]:::ui
        PatientChat["PatientChat.tsx"]:::ui
        DoctorChat["DoctorChat.tsx"]:::ui

        FE -->|uses| App
        App -->|renders| Chat
        App -->|routes to| Landing
        App -->|routes to| PatientChat
        App -->|routes to| DoctorChat

        Browser -->|visits| FE
    end

    %% Backend Layer
    subgraph "Backend API & Toolserver (Docker port 8000)"
        direction TB
        API["FastAPI (main.py)"]:::api
        Auth["auth.py"]:::api
        MCP["mcp_server.py"]:::logic
        MistralClientFull["mistral_client.py"]:::external
        MistralClientSimple["simple_mistral_client.py"]:::external
        DBModule["database.py"]:::db
        Models["models.py"]:::db

        API -->|handles auth| Auth
        API -->|chat & booking endpoints| MCP
        API -->|calls NLP intents| MistralClientFull
        API -->|calls NLP intents| MistralClientSimple
        API -->|reads/writes| DBModule
        DBModule -->|defines| Models
    end

    %% Database Layer
    subgraph "PostgreSQL (port 5432)"
        direction TB
        PostgresDB["PostgreSQL"]:::db
        DBModule -->|connects| PostgresDB
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MistralAI["Mistral AI API"]:::external
        GoogleCalendar["Google Calendar API"]:::external
        GmailAPI["Gmail API"]:::external

        MCP -->|HTTP JSON| GoogleCalendar
        MCP -->|HTTP JSON| GmailAPI
        API -->|HTTP JSON| MistralAI
    end

    %% Data Flows
    Browser -->|Axios HTTP JSON| API
    API -->|JSON responses| Browser
    MCP -->|SQL queries| PostgresDB
    API -->|calls /docs| API

    %% Click Events
    click FE "https://github.com/jainyash0614/ai-doctor-appointment-assistant/tree/main/frontend/src"
    click App "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/src/App.tsx"
    click Chat "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/src/components/Chat.tsx"
    click Landing "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/src/pages/Landing.tsx"
    click PatientChat "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/src/pages/PatientChat.tsx"
    click DoctorChat "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/src/pages/DoctorChat.tsx"
    click API "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/main.py"
    click Auth "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/auth.py"
    click MCP "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/mcp_server.py"
    click MistralClientFull "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/mistral_client.py"
    click MistralClientSimple "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/simple_mistral_client.py"
    click DBModule "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/database.py"
    click Models "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/app/models.py"
    click BackendDockerfile "https://github.com/jainyash0614/ai-doctor-appointment-assistant/tree/main/backend/Dockerfile"
    click FrontendDockerfile "https://github.com/jainyash0614/ai-doctor-appointment-assistant/tree/main/frontend/Dockerfile"
    click README "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/README.md"
    click Prompts "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/prompts.md"
    click Scenarios "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/backend/scenario2.md"
    click PackageJSON "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/package.json"
    click TSConfig "https://github.com/jainyash0614/ai-doctor-appointment-assistant/blob/main/frontend/tsconfig.json"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px
    classDef logic fill:#98FB98,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
