# stephan-chiorean/learnhub architecture

> Architecture diagram of the GitHub repository stephan-chiorean/learnhub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephan-chiorean/learnhub
- Repository: https://github.com/stephan-chiorean/learnhub

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React/Vite)" 
        direction TB
        FE_HTML["index.html"]:::internal
        FE_PKG["package.json"]:::internal
        FE_VITE["vite.config.ts"]:::internal
        FE_TS_CONFIG["tsconfig.json"]:::internal
        ASSETS["assets/"]:::internal
        SRC["src/"]:::internal
        subgraph "src/" 
            direction TB
            APP["App.tsx"]:::internal
            MAIN["main.tsx"]:::internal
            INDEX_TSX["index.tsx"]:::internal
            INDEX_CSS["index.css"]:::internal
            COMPONENTS["components/"]:::internal
            PAGES["pages/"]:::internal
            CONTEXT["context/"]:::internal
            HOOKS["hooks/"]:::internal
            UTIL_FE["utils/"]:::internal
            STYLES["styles/"]:::internal
            TYPES_FE["types/"]:::internal
        end
    end

    %% Backend Layer
    subgraph "Backend (Node.js API Server)" 
        direction TB
        BE_ENTRY["server/index.ts"]:::internal
        BE_PKG["server/package.json"]:::internal
        BE_TS_CONFIG["server/tsconfig.json"]:::internal
        BE_TEST_ENV["server/test-env.ts"]:::internal
        subgraph "Utils & Logic"
            direction TB
            OPENAI_UTIL["server/utils/openai.ts"]:::internal
            WORKSPACE_HELPERS["server/workspaces/workspaceHelpers.ts"]:::internal
        end
        subgraph "Database Layer"
            direction TB
            DB_ACCESS["server/db/index.ts"]:::internal
            DB_SCHEMA["server/db/schema.sql"]:::internal
        end
        subgraph "BAML Integration"
            direction TB
            BAML_SRC["baml_src/"]:::gen
            BAML_CLIENT["baml_client/"]:::gen
        end
        subgraph "Scripts"
            direction TB
            EMBED_UPSERT["scripts/embedAndUpsert.cjs"]:::internal
            CHUNK_REPO_JS["scripts/chunkRepo.cjs"]:::internal
            CHUNK_REPO_PY["scripts/chunk_repo_unified.py"]:::internal
            CHAT_UTIL["scripts/chat.cjs"]:::internal
        end
    end

    %% Services
    DB["Postgres/SQLite DB"]:::db
    GH_API["GitHub API"]:::external
    OPENAI_API["OpenAI API"]:::external
    PINECONE["Pinecone"]:::external

    %% Infrastructure
    DC["docker-compose.yaml"]:::internal

    %% Connections
    FE_HTML -->|Served by| DC
    FE_PKG -->|Config for| FE_HTML
    FE_VITE -->|Builds| FE_HTML
    FE_TS_CONFIG -->|Type Config| SRC
    ASSETS -->|Static Loaders| SRC
    SRC -->|HTTP Calls| BE_ENTRY
    BE_ENTRY -->|"SQL Queries"| DB_ACCESS
    DB_ACCESS -->|Schema| DB_SCHEMA
    BE_ENTRY -->|Calls| OPENAI_UTIL
    BE_ENTRY -->|Calls| WORKSPACE_HELPERS
    BE_ENTRY -->|Uses| BAML_CLIENT
    BAML_CLIENT -->|Definitions| BAML_SRC
    EMBED_UPSERT -->|Upsert Embeddings| PINECONE
    CHUNK_REPO_JS -->|Chunking| PINECONE
    CHUNK_REPO_PY -->|Chunking| PINECONE
    CHAT_UTIL -->|Chat Ops| BE_ENTRY
    BE_ENTRY -->|Docker Service| DC
    BE_ENTRY -->|DB Container| DB
    BE_ENTRY -->|GitHub Data| GH_API
    OPENAI_UTIL -->|API Calls| OPENAI_API
    EMBED_UPSERT -->|Pinecone Ops| PINECONE

    %% Click Events Frontend
    click FE_HTML "https://github.com/stephan-chiorean/learnhub/blob/main/index.html"
    click FE_PKG "https://github.com/stephan-chiorean/learnhub/blob/main/package.json"
    click FE_VITE "https://github.com/stephan-chiorean/learnhub/blob/main/vite.config.ts"
    click FE_TS_CONFIG "https://github.com/stephan-chiorean/learnhub/blob/main/tsconfig.json"
    click ASSETS "https://github.com/stephan-chiorean/learnhub/tree/main/assets/"
    click SRC "https://github.com/stephan-chiorean/learnhub/tree/main/src/"
    click APP "https://github.com/stephan-chiorean/learnhub/blob/main/src/App.tsx"
    click MAIN "https://github.com/stephan-chiorean/learnhub/blob/main/src/main.tsx"
    click INDEX_TSX "https://github.com/stephan-chiorean/learnhub/blob/main/src/index.tsx"
    click INDEX_CSS "https://github.com/stephan-chiorean/learnhub/blob/main/src/index.css"
    click COMPONENTS "https://github.com/stephan-chiorean/learnhub/tree/main/src/components/"
    click PAGES "https://github.com/stephan-chiorean/learnhub/tree/main/src/pages/"
    click CONTEXT "https://github.com/stephan-chiorean/learnhub/tree/main/src/context/"
    click HOOKS "https://github.com/stephan-chiorean/learnhub/tree/main/src/hooks/"
    click UTIL_FE "https://github.com/stephan-chiorean/learnhub/tree/main/src/utils/"
    click STYLES "https://github.com/stephan-chiorean/learnhub/tree/main/src/styles/"
    click TYPES_FE "https://github.com/stephan-chiorean/learnhub/tree/main/src/types/"

    %% Click Events Backend
    click BE_ENTRY "https://github.com/stephan-chiorean/learnhub/blob/main/server/index.ts"
    click BE_PKG "https://github.com/stephan-chiorean/learnhub/blob/main/server/package.json"
    click BE_TS_CONFIG "https://github.com/stephan-chiorean/learnhub/blob/main/server/tsconfig.json"
    click BE_TEST_ENV "https://github.com/stephan-chiorean/learnhub/blob/main/server/test-env.ts"
    click OPENAI_UTIL "https://github.com/stephan-chiorean/learnhub/blob/main/server/utils/openai.ts"
    click WORKSPACE_HELPERS "https://github.com/stephan-chiorean/learnhub/blob/main/server/workspaces/workspaceHelpers.ts"

    %% Click Events Database
    click DB_ACCESS "https://github.com/stephan-chiorean/learnhub/blob/main/server/db/index.ts"
    click DB_SCHEMA "https://github.com/stephan-chiorean/learnhub/blob/main/server/db/schema.sql"

    %% Click Events BAML
    click BAML_SRC "https://github.com/stephan-chiorean/learnhub/tree/main/baml_src/"
    click BAML_CLIENT "https://github.com/stephan-chiorean/learnhub/tree/main/baml_client/"
    
    %% Click Events Scripts
    click EMBED_UPSERT "https://github.com/stephan-chiorean/learnhub/blob/main/scripts/embedAndUpsert.cjs"
    click CHUNK_REPO_JS "https://github.com/stephan-chiorean/learnhub/blob/main/scripts/chunkRepo.cjs"
    click CHUNK_REPO_PY "https://github.com/stephan-chiorean/learnhub/blob/main/scripts/chunk_repo_unified.py"
    click CHAT_UTIL "https://github.com/stephan-chiorean/learnhub/blob/main/scripts/chat.cjs"

    %% Click Event Infrastructure
    click DC "https://github.com/stephan-chiorean/learnhub/blob/main/docker-compose.yaml"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#000,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef gen fill:#f9cb9c,stroke:#000,stroke-width:1px
    classDef db fill:#ffe599,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
