# denisamselem/study-sidekick architecture

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

- Interactive diagram: https://gitdiagram.com/denisamselem/study-sidekick
- Repository: https://github.com/denisamselem/study-sidekick

## Overview

##### Project type and purpose
- This is a full-stack AI-powered learning tool called “Study Sidekick.”
- Frontend: React (Vite + TypeScript) web client for uploading documents, chatting, and viewing generated quizzes/flashcards.
- Backend: Node.js + Express API providing endpoints for chat, document upload, flashcards, quizzes, and processing logic.
- External services: Google Gemini (AI model) and Supabase (database, file storage, embeddings store).

##### File structure
- Top level:
- App.tsx, index.tsx, index.html, vite.config.ts → React entry points, Vite config.
- package.json, tsconfig.json, tailwind.config.js, postcss.config.js → build/tooling.
- components/ → React UI components (ChatWindow, FileUpload, QuizView, FlashcardView, etc.).
- services/ → frontend service clients (apiService.ts, supabaseClient.ts).
- api/ directory (backend):
- src/index.ts → Express server setup.
- src/handlers → route handlers for each feature (chat, upload, process, quiz, flashcards, config).
- src/services → core business logic (clusteringService, embeddingService, ragService, processingCache).
- src/lib → low-level wrappers for Gemini API, Supabase SDK, textChunker.
- nodemon.json, tsconfig.json → development config.

##### README for additional insights
- Describes the dual-server setup: `npm run dev` starts both Vite frontend (port 5173) and Express API (port 3001).
- Environment variables: Gemini API key, Supabase URL & keys (anon + service_role).
- Use cases: upload documents for chunking, chat with AI, generate quizzes and flashcards via RAG.

a. Main components
1. User’s Browser / UI (React + Vite)
2. Frontend Application
- Components: FileUpload, ChatWindow, QuizView, FlashcardView
- SupabaseClient (for direct DB interactions: auth, file storage, real-time?)
- apiService (for calling backend endpoints)
3. Backend API Server (Express + TypeScript)
- Route Handlers (upload, chat, quiz, flashcards, processing)
- Services (textChunker, embeddingService, clusteringService, ragService, processingCache)
- Libs (Gemini API wrapper, Supabase SDK)
4. External AI Service (Gemini)
5. Supabase Project
- Database / Tables (embeddings, chunks, user metadata)
- Storage (uploaded documents)
6. Optional Caching Layer (processingCache in backend)
b. Relationships & interactions
- UI → apiService → Express endpoints (HTTP REST)
- FileUpload UI → POST /upload → backend writes file to Supabase Storage → triggers chunking
- Backend textChunker splits document → embeddingService calls Gemini or Supabase embeddings API → store embeddings in Supabase DB
- Chat/quiz/flashcards UI → requests to Express → ragService fetches relevant embeddings from Supabase → Gemini generates responses/quizzes/flashcards → response back to UI
- UI may also use SupabaseClient directly for auth or real-time updates (if implemented).
c. Architectural patterns & principles
- Separation of concerns: UI, API handlers, business-logic services, low-level libs.
- Modular layering: Handlers → Services → Lib/drivers.
- RAG (Retrieval-Augmented Generation) pipeline embedded in backend.
- Caching to reduce repeated calls to external services (`processingCache`).
d. Key technologies & frameworks
- Frontend: React, Vite, Tailwind CSS, Supabase JS, TypeScript.
- Backend: Node.js, Express, TypeScript, Supabase Admin SDK, Google Gemini API.
- Dev Tools: nodemon, ts-node, Vite, PostCSS.

##### Final advice
- Be detailed: break the backend into Handler, Service, and Lib layers.
- Data flow: upload → chunk → embed → store → retrieve → generate → display.
- Avoid over-complexity: focus on major components and interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "React Frontend"
        direction TB
        App["App.tsx"]:::ui
        IndexTSX["index.tsx"]:::ui
        IndexHTML["index.html"]:::ui
        ViteConfig["vite.config.ts"]:::ui
        subgraph "UI Components"
            direction TB
            FileUpload["FileUpload"]:::ui
            ChatWindow["ChatWindow"]:::ui
            QuizView["QuizView"]:::ui
            FlashcardView["FlashcardView"]:::ui
            ErrorBoundary["ErrorBoundary"]:::ui
            ToastProvider["ToastProvider"]:::ui
            Icons["Icons"]:::ui
        end
        subgraph "Service Clients"
            direction TB
            APIService["apiService"]:::ui
            SupabaseClient["supabaseClient"]:::ui
        end
    end

    %% Backend Layer
    subgraph "Express API Server"
        direction TB
        Server["Server (index.ts)"]:::backend
        Nodemon["nodemon.json"]:::backend
        BackendPkg["package.json"]:::backend

        subgraph "Route Handlers"
            direction TB
            ChatHandler["chatHandler"]:::backend
            UploadHandler["uploadHandler"]:::backend
            DocumentHandler["documentHandler"]:::backend
            ProcessHandler["processHandler"]:::backend
            ProcessingHandlers["processingHandlers"]:::backend
            QuizHandler["quizHandler"]:::backend
            FlashcardsHandler["flashcardsHandler"]:::backend
            ConfigHandler["configHandler"]:::backend
        end

        subgraph "Core Services"
            direction TB
            EmbeddingService["embeddingService"]:::backend
            ClusteringService["clusteringService"]:::backend
            RAGService["ragService"]:::backend
            ProcessingCache["processingCache"]:::backend
        end

        subgraph "Lib Wrappers"
            direction TB
            GeminiWrapper["gemini.ts"]:::backend
            SupabaseWrapper["supabase.ts"]:::backend
            TextChunker["textChunker.ts"]:::backend
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gemini["Google Gemini"]:::external
        SupabaseDB["Supabase DB"]:::external
        SupabaseStorage["Supabase Storage"]:::external
    end

    %% Connections
    FileUpload -->|"/upload"| UploadHandler
    ChatWindow -->|"/chat"| ChatHandler
    QuizView -->|"/quiz"| QuizHandler
    FlashcardView -->|"/flashcards"| FlashcardsHandler

    APIService -->|"REST calls"| Server
    Server -->|uses| Nodemon
    Server -->|uses| BackendPkg

    Server --> ChatHandler
    Server --> UploadHandler
    Server --> DocumentHandler
    Server --> ProcessHandler
    Server --> ProcessingHandlers
    Server --> QuizHandler
    Server --> FlashcardsHandler
    Server --> ConfigHandler

    ChatHandler --> EmbeddingService
    UploadHandler --> TextChunker
    DocumentHandler --> TextChunker
    ProcessHandler --> ProcessingCache

    EmbeddingService --> GeminiWrapper
    EmbeddingService --> SupabaseWrapper
    ClusteringService --> SupabaseWrapper
    RAGService --> EmbeddingService
    RAGService --> ClusteringService
    RAGService --> GeminiWrapper
    ProcessingCache --> SupabaseWrapper

    GeminiWrapper --> Gemini
    SupabaseWrapper --> SupabaseDB
    SupabaseWrapper --> SupabaseStorage

    SupabaseClient -.->|auth/storage| SupabaseDB
    SupabaseClient -.-> SupabaseStorage

    %% Click Events
    click App "https://github.com/denisamselem/study-sidekick/blob/main/App.tsx"
    click IndexTSX "https://github.com/denisamselem/study-sidekick/blob/main/index.tsx"
    click IndexHTML "https://github.com/denisamselem/study-sidekick/blob/main/index.html"
    click ViteConfig "https://github.com/denisamselem/study-sidekick/blob/main/vite.config.ts"
    click FileUpload "https://github.com/denisamselem/study-sidekick/blob/main/components/FileUpload.tsx"
    click ChatWindow "https://github.com/denisamselem/study-sidekick/blob/main/components/ChatWindow.tsx"
    click QuizView "https://github.com/denisamselem/study-sidekick/blob/main/components/QuizView.tsx"
    click FlashcardView "https://github.com/denisamselem/study-sidekick/blob/main/components/FlashcardView.tsx"
    click ErrorBoundary "https://github.com/denisamselem/study-sidekick/blob/main/components/ErrorBoundary.tsx"
    click ToastProvider "https://github.com/denisamselem/study-sidekick/blob/main/components/ToastProvider.tsx"
    click Icons "https://github.com/denisamselem/study-sidekick/blob/main/components/common/Icons.tsx"
    click APIService "https://github.com/denisamselem/study-sidekick/blob/main/services/apiService.ts"
    click SupabaseClient "https://github.com/denisamselem/study-sidekick/blob/main/services/supabaseClient.ts"
    click Server "https://github.com/denisamselem/study-sidekick/blob/main/api/src/index.ts"
    click Nodemon "https://github.com/denisamselem/study-sidekick/blob/main/api/nodemon.json"
    click BackendPkg "https://github.com/denisamselem/study-sidekick/blob/main/api/package.json"
    click ChatHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/chatHandler.ts"
    click UploadHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/uploadHandler.ts"
    click DocumentHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/documentHandler.ts"
    click ProcessHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/processHandler.ts"
    click ProcessingHandlers "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/processingHandlers.ts"
    click QuizHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/quizHandler.ts"
    click FlashcardsHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/flashcardsHandler.ts"
    click ConfigHandler "https://github.com/denisamselem/study-sidekick/blob/main/api/src/handlers/configHandler.ts"
    click EmbeddingService "https://github.com/denisamselem/study-sidekick/blob/main/api/src/services/embeddingService.ts"
    click ClusteringService "https://github.com/denisamselem/study-sidekick/blob/main/api/src/services/clusteringService.ts"
    click RAGService "https://github.com/denisamselem/study-sidekick/blob/main/api/src/services/ragService.ts"
    click ProcessingCache "https://github.com/denisamselem/study-sidekick/blob/main/api/src/services/processingCache.ts"
    click GeminiWrapper "https://github.com/denisamselem/study-sidekick/blob/main/api/src/lib/gemini.ts"
    click SupabaseWrapper "https://github.com/denisamselem/study-sidekick/blob/main/api/src/lib/supabase.ts"
    click TextChunker "https://github.com/denisamselem/study-sidekick/blob/main/api/src/lib/textChunker.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff;
    classDef backend fill:#d4edda,stroke:#28a745;
    classDef external fill:#ffe5cc,stroke:#ff9900;
    classDef dashed stroke-dasharray: 5 5;
```
