# klaritylab/klarity architecture

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

- Interactive diagram: https://gitdiagram.com/klaritylab/klarity
- Repository: https://github.com/klaritylab/klarity

## Overview

##### Project type and purpose
- This is a single‑page web application built with Vite, TypeScript, and React, styled with Tailwind CSS and shadcn‑ui components.
- It leverages Firebase (authentication, Firestore, storage) and several AI/external services (Gemini, custom chat APIs) to provide features like PDF upload & search, AI chat, journaling, task management, courses, and user profiles.

##### File structure
- Top level
– index.html → the SPA entry point
– public/ → static assets & uploads
– src/ → all application code
– firebase-key.json → BaaS credentials
– configuration files (tsconfig, vite.config.ts, tailwind.config.ts)
- Inside src/
– components/ → reusable UI pieces & layout (e.g. Navbar.tsx, ChatRoom.tsx)
– pages/ → route‑level components (Home, ChatPage, UploadPDFsPage, etc.)
– context/ → React Context (PDFContext) for global state
– hooks/ → custom hooks (use‑mobile, use‑toast)
– services/ → abstractions for external interactions (ai‑service.ts, firestoreServices.ts, chat‑service.ts)
– firebase/ → initialization & helper functions
– lib/ → utility libraries (journalGemini.ts)
– models/ → TypeScript interfaces (chat messages)
– styles/ → global CSS
- Architectural patterns
– Component‑based UI (Atomic and composite components in src/components/ui/)
– SPA routing (pages/ + main.tsx)
– Service layer abstraction in src/services/
– Context API for state management

##### Extract insights from the README
- Confirms tech stack: Vite, React, TypeScript, Tailwind CSS, shadcn‑ui

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Browser & UI
    subgraph "Client (Browser)"
        subgraph "UI Layer"
            MainTS["main.tsx"]:::ui
            AppTS["App.tsx"]:::ui
            subgraph "Components"
                UIPrims["Atomic UI Primitives"]:::ui
                Navbar["Navbar.tsx"]:::ui
                ChatRoom["ChatRoom.tsx"]:::ui
                PDFUploader["PDFUploader.tsx"]:::ui
                PDFSearch["PDFSearch.tsx"]:::ui
            end
            subgraph "Pages"
                Home["Home.tsx"]:::ui
                ChatPage["ChatPage.tsx"]:::ui
                UploadPDFsPage["UploadPDFsPage.tsx"]:::ui
                TasksPage["TasksPage.tsx"]:::ui
                ProfilePage["ProfilePage.tsx"]:::ui
            end
        end
        Styles["globals.css / index.css"]:::ui
    end

    %% State Management
    subgraph "State Management"
        PDFContext["PDFContext.tsx"]:::service
    end

    %% Service Layer
    subgraph "Service Layer"
        APIClient["api.ts"]:::service
        AIService["ai-service.ts"]:::service
        GeminiService["geminiService.ts"]:::service
        ChatService["chat-service.ts"]:::service
        ChatApi["chatApi.js"]:::service
        FirestoreService["firestoreServices.ts"]:::service
        SpacesService["spaces.ts"]:::service
    end

    %% Firebase Initialization
    subgraph "Firebase Init"
        FirebaseInit["firebase.tsx"]:::service
        FirebaseHelpers["firebaseHelpers.ts"]:::service
    end

    %% Utilities & Models
    subgraph "Utilities & Models"
        JournalLib["journalGemini.ts"]:::service
        Utils["utils.ts"]:::service
        ChatModel["chat.ts"]:::service
        HookMobile["use-mobile.tsx"]:::service
        HookToast["use-toast.tsx"]:::service
    end

    %% Backend Services
    subgraph "Firebase Backend"
        Auth["Firebase Auth"]:::external
        FirestoreDB["Firestore DB"]:::external
        Storage["Firebase Storage"]:::external
    end

    subgraph "External AI & Chat APIs"
        GeminiAPI["Gemini API"]:::external
        ChatExternalAPI["Chat External API"]:::external
    end

    %% Static Assets & Config
    subgraph "Static & Config"
        IndexHTML["index.html"]:::ui
        Public["public/"]:::external
        TailwindCfg["tailwind.config.ts"]:::ui
        ViteCfg["vite.config.ts"]:::ui
    end

    %% Relationships
    IndexHTML --> MainTS
    MainTS --> AppTS
    AppTS --> UIPrims
    AppTS --> Navbar
    AppTS --> Home
    AppTS --> ChatPage
    AppTS --> UploadPDFsPage
    AppTS --> TasksPage
    AppTS --> ProfilePage

    Home --> PDFContext
    ChatPage --> ChatService
    ChatPage --> ChatApi
    UploadPDFsPage --> SpacesService
    UploadPDFsPage --> FirestoreService
    TasksPage --> FirestoreService
    ProfilePage --> FirestoreService

    PDFContext --> FirestoreService
    PDFContext --> SpacesService

    FirestoreService --> FirestoreDB
    SpacesService --> Storage

    AIService --> GeminiAPI
    GeminiService --> GeminiAPI

    ChatService --> ChatExternalAPI
    ChatApi --> ChatExternalAPI

    FirestoreService --> FirebaseInit
    SpacesService --> FirebaseInit

    FirebaseInit --> Auth
    FirebaseInit --> FirestoreDB
    FirebaseInit --> Storage

    JournalLib --> GeminiAPI
    Utils --> FirestoreService

    %% Click Events
    click UIPrims "https://github.com/klaritylab/klarity/tree/main/src/components/ui/"
    click Navbar "https://github.com/klaritylab/klarity/blob/main/src/components/Navbar.tsx"
    click ChatRoom "https://github.com/klaritylab/klarity/blob/main/src/components/ChatRoom.tsx"
    click PDFUploader "https://github.com/klaritylab/klarity/blob/main/src/components/PDFUploader.tsx"
    click PDFSearch "https://github.com/klaritylab/klarity/blob/main/src/components/PDFSearch.tsx"
    click MainTS "https://github.com/klaritylab/klarity/blob/main/src/main.tsx"
    click AppTS "https://github.com/klaritylab/klarity/blob/main/src/App.tsx"
    click Home "https://github.com/klaritylab/klarity/blob/main/src/pages/Home.tsx"
    click ChatPage "https://github.com/klaritylab/klarity/blob/main/src/pages/ChatPage.tsx"
    click UploadPDFsPage "https://github.com/klaritylab/klarity/blob/main/src/pages/UploadPDFsPage.tsx"
    click TasksPage "https://github.com/klaritylab/klarity/blob/main/src/pages/TasksPage.tsx"
    click ProfilePage "https://github.com/klaritylab/klarity/blob/main/src/pages/ProfilePage.tsx"
    click PDFContext "https://github.com/klaritylab/klarity/blob/main/src/context/PDFContext.tsx"
    click AIService "https://github.com/klaritylab/klarity/blob/main/src/services/ai-service.ts"
    click GeminiService "https://github.com/klaritylab/klarity/blob/main/src/services/geminiService.ts"
    click ChatService "https://github.com/klaritylab/klarity/blob/main/src/services/chat-service.ts"
    click ChatApi "https://github.com/klaritylab/klarity/blob/main/src/services/chatApi.js"
    click FirestoreService "https://github.com/klaritylab/klarity/blob/main/src/services/firestoreServices.ts"
    click SpacesService "https://github.com/klaritylab/klarity/blob/main/src/services/spaces.ts"
    click APIClient "https://github.com/klaritylab/klarity/blob/main/src/services/api.ts"
    click FirebaseInit "https://github.com/klaritylab/klarity/blob/main/src/firebase/firebase.tsx"
    click FirebaseHelpers "https://github.com/klaritylab/klarity/blob/main/src/firebase/firebaseHelpers.ts"
    click JournalLib "https://github.com/klaritylab/klarity/blob/main/src/lib/journalGemini.ts"
    click Utils "https://github.com/klaritylab/klarity/blob/main/src/lib/utils.ts"
    click ChatModel "https://github.com/klaritylab/klarity/blob/main/src/models/chat.ts"
    click HookMobile "https://github.com/klaritylab/klarity/blob/main/src/hooks/use-mobile.tsx"
    click HookToast "https://github.com/klaritylab/klarity/blob/main/src/hooks/use-toast.tsx"
    click Styles "https://github.com/klaritylab/klarity/blob/main/src/styles/globals.css"
    click Styles "https://github.com/klaritylab/klarity/blob/main/src/index.css"
    click TailwindCfg "https://github.com/klaritylab/klarity/blob/main/tailwind.config.ts"
    click ViteCfg "https://github.com/klaritylab/klarity/blob/main/vite.config.ts"
    click Public "https://github.com/klaritylab/klarity/tree/main/public/"
    click IndexHTML "https://github.com/klaritylab/klarity/blob/main/index.html"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
