# vishalv971/switch-it-up architecture

> Architecture diagram of the GitHub repository vishalv971/switch-it-up, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishalv971/switch-it-up
- Repository: https://github.com/vishalv971/switch-it-up

## Overview

##### Main Components
- Frontend UI: Represented by the Next.js “app” folder which includes routing (pages within [[...index]]), components (React components such as CallLogButton, GoogleCalendarIntegration, and NotionIntegration), and standard layout files.
- Backend API Server: Housed within the “api” directory which includes the entry point (index.py) and source code modules such as configuration, database (Supabase integration), routes (e.g., calendar_routes.py), and services (e.g., gcal_service.py, gemini_service.py).
- Database: Supabase is used for data storage.
- External Integrations: APIs and services such as Notion API, Google Calendar API, ElevenLabs for Voice AI, and Clerk for authentication.

##### Relationships and Interactions
- Within the backend layer, distinct modules (config, db, routes, services) show how data flows from the API entry point to various services and ultimately to the database (Supabase) or external APIs.

##### Important Architectural Patterns and Design Principles
- Clear Separation of Concerns: Frontend UI is decoupled from backend logic.
- Modular Design: The FastAPI backend is organized into modules (configuration, routes, services, db, integrations) which promotes maintainability.
- Microservices-like Interaction within the monorepo: Although housed together, the API layer is clearly segmented from the UI components.
- External API Integration Points: The system uses well-defined external endpoints for voice AI, calendar management, and task/note management.

##### Relevant Technologies and Frameworks
- Frontend: Next.js 14, React, TailwindCSS
- Backend: FastAPI (Python-based)
- Database: Supabase
- Authentication: Clerk
- External APIs: ElevenLabs Voice AI, Notion API, Google Calendar API

##### Essential Architectural Elements
- Detail as many architectural components as possible:
- The Next.js “app” folder separated into pages, API routes (if any specific ones exist), and shared components.
- The FastAPI “api” folder with its modules: configuration (calendar_config), database access (supabase), integrations (Notion and Google Calendar), and service layers.
- Be detailed in capturing interactions between modules to show how requests flow through routes, through service layers, and eventually to the database or external APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Section
    subgraph "Frontend"
        FE1["Next.js Frontend"]:::frontend
        FE2["Routing & Pages"]:::frontend
        FE3["React Components"]:::frontend
    end

    %% Backend Section
    subgraph "Backend"
        BE1["FastAPI Backend"]:::backend
        BE2["API Entry Point (index.py)"]:::backend
        BE3["Configuration (calendar_config)"]:::backend
        BE4["Database Integration (Supabase)"]:::db
        BE5["API Routing (calendar_routes)"]:::backend
        BE6["Google Calendar Service (gcal_service)"]:::backend
        BE7["ElevenLabs/Gemini Service (gemini_service)"]:::backend
        BE8["Notion API Integration (notion)"]:::backend
    end

    %% External Services Section
    subgraph "External Services"
        EX1["Google Calendar API"]:::external
        EX2["Notion API"]:::external
        EX3["ElevenLabs Voice AI"]:::external
        EX4["Clerk Authentication"]:::external
    end

    %% Database Section
    subgraph "Database"
        DB["Supabase Database"]:::db
    end

    %% Connections between Frontend and Backend
    FE1 -->|"API_call"| BE2
    FE1 -->|"Provides UI|UX"| FE2
    FE1 -->|"Renders"| FE3

    %% Backend internal connections
    BE2 -->|"uses"| BE3
    BE2 -->|"accesses"| BE4
    BE2 -->|"delegates"| BE5
    BE5 -->|"calls"| BE6
    BE5 -->|"calls"| BE7
    BE5 -->|"calls"| BE8

    %% External integrations from Backend
    BE6 -->|"integrates"| EX1
    BE7 -->|"integrates"| EX3
    BE8 -->|"integrates"| EX2

    %% Database integration
    BE4 -->|"stores data in"| DB

    %% Frontend external connection for authentication
    FE1 -->|"authVia"| EX4


    %% Click Events
    click FE1 "https://github.com/vishalv971/switch-it-up/tree/main/app"
    click FE2 "https://github.com/vishalv971/switch-it-up/blob/main/app/[[...index]]"
    click FE3 "https://github.com/vishalv971/switch-it-up/tree/main/app/components"
    click BE2 "https://github.com/vishalv971/switch-it-up/blob/main/api/index.py"
    click BE3 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/config/calendar_config.py"
    click BE4 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/db/supabase.py"
    click BE5 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/routes/calendar_routes.py"
    click BE8 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/notion/notion.py"
    click BE6 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/services/gcal_service.py"
    click BE7 "https://github.com/vishalv971/switch-it-up/blob/main/api/src/services/gemini_service.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef db fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
