How stephan-chiorean/learnhub works
Project type and purpose
• LearnHub is a full-stack web application for exploring GitHub repositories with AI-powered explanations, built in React (frontend), Node.js/TypeScript (backend), and Tailwind CSS for styling. It integrates with external services (GitHub API, OpenAI, Pinecone) and includes a custom BAML-based code-generation client library.
File structure
• Top level
• assets/ — static animations (JSON loaders)
• index.html — entry point for the frontend
• package.json, vite.config.ts, tsconfig.json — frontend build/configuration
• docker-compose.yaml — orchestrates containers for backend, database, etc.
• baml_src/ & baml_client/ — definition files and generated TypeScript client code for BAML (a domain-specific language parser/generator)
• server/ — Node.js/Express (or similar) backend, database schema, environment config, utility modules, and workspace logic
• src/ — React code for the UI, with components, pages, context, hooks, utils, and styling
README for additional insights
• Stack: React + Vite on the frontend; Node.js + TypeScript on the backend
• External dependencies: GitHub API (repository data), OpenAI API (summaries), Pinecone (vector storage for embeddings)
• Local development: two npm processes (frontend on 5173, backend on 3000) plus Docker Compose for service orchestration
Main components
a. Frontend (React/Vite)
• Modules: UI components, context providers, pages, utilities
• Consumes backend REST endpoints for repo data, notes, AI summaries
• Bundles and serves index.html
b. Backend (Node.js/Express + TypeScript)
• REST API layer (server/index.ts)
• Database access layer (server/db/index.ts + schema.sql)
• Workspace management (server/workspaces)
• OpenAI integration (server/utils/openai.ts)
• BAML client usage (baml_client/) for code generation or request orchestration
• Scripts folder for embedding, upserting, chunking repository data
c. Database
• SQL database (Postgres or SQLite) defined by schema.sql in server/db
• Stores user workspaces, annotations, notebook entries, repo metadata
d. External services
• GitHub API (via server or direct front-end calls)
• OpenAI API (through server/utils/openai.ts)
• Pinecone vector database (for similarity search of code snippets)
Relationships and data flow
• Frontend → Backend: HTTP(S) REST calls for UI actions (explore repo, save notes, fetch summaries)
• Backend → Database: SQL queries for persistence
• Backend → External APIs:
• GitHub API to fetch repo data and file contents
• OpenAI API to generate explanations/summaries
• Pinecone API to store/retrieve embeddings of code chunks
• Backend uses baml_client internally to parse/generate requests according to BAML definitions (baml_src)
Architectural patterns and design principles
• Layered architecture: UI layer, API layer, data layer, external integrations
• Separation of concerns: BAML client (code-generation) isolated in its own module; UI logic in React components; backend business logic in server folder
• Modular frontend using Context API and custom hooks for state management
• Infrastructure as code: docker-compose.yaml to define container relationships
Critical details to capture
• Separation of UI vs. API vs. Data
• Role of the BAML client and source definitions
• Integration points with GitHub/OpenAI/Pinecone
• Development vs. production pathways (local dev scripts, Docker Compose)