How denisamselem/study-sidekick works
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.