{"id":32033833,"url":"https://github.com/bryanthelai/stackrag-frontend","last_synced_at":"2026-05-05T14:09:30.574Z","repository":{"id":308734619,"uuid":"983857854","full_name":"BryanTheLai/StackRAG-Frontend","owner":"BryanTheLai","description":"A frontend project, built primarily with TypeScript. This repository provides the user interface and client-side logic for interacting with Stackifier’s features and services.","archived":false,"fork":false,"pushed_at":"2025-09-26T06:38:01.000Z","size":1626,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-26T07:21:37.399Z","etag":null,"topics":["client-side","frontend","python","react","stackifier","typescript","ui","webapp","website"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BryanTheLai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-15T03:01:03.000Z","updated_at":"2025-09-26T06:38:06.000Z","dependencies_parsed_at":"2025-09-26T07:13:41.906Z","dependency_job_id":"12e539ad-bb92-4b63-b8e7-e003c26c4648","html_url":"https://github.com/BryanTheLai/StackRAG-Frontend","commit_stats":null,"previous_names":["bryanthelai/stackrag-frontend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/BryanTheLai/StackRAG-Frontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryanTheLai%2FStackRAG-Frontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryanTheLai%2FStackRAG-Frontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryanTheLai%2FStackRAG-Frontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryanTheLai%2FStackRAG-Frontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BryanTheLai","download_url":"https://codeload.github.com/BryanTheLai/StackRAG-Frontend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BryanTheLai%2FStackRAG-Frontend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279285965,"owners_count":26140330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-17T02:00:07.504Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-side","frontend","python","react","stackifier","typescript","ui","webapp","website"],"created_at":"2025-10-17T04:57:35.286Z","updated_at":"2026-05-05T14:09:30.559Z","avatar_url":"https://github.com/BryanTheLai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🏦 StackRAG - Frontend\n\n**A Modern, Data-Driven React Interface for Financial AI **\n\n[![React 19](https://img.shields.io/badge/React-19-blue.svg)](https://react.dev/)\n[![Vite](https://img.shields.io/badge/Vite-6.3+-purple.svg)](https://vitejs.dev/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)\n[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4.1+-cyan.svg)](https://tailwindcss.com/)\n\n*A responsive, secure, and real-time frontend for the Stackifier AI platform, built with modern web technologies.*\n\n**Backend Source**: [StackRAG-Backend](https://github.com/BryanTheLai/StackRAG-Backend)\n\n\u003c!-- Demo Screenshots --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/chat_with_pdf_ui.png\" alt=\"Chat Interface - Part 2\" width=\"400\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/Documents.png\" alt=\"Documents List\" width=\"400\" /\u003e\n  \u003cimg src=\"public/Dashboard.png\" alt=\"Dashboard View\" width=\"400\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/Chat2.png\" alt=\"Chat Interface - Part 2\" width=\"400\" /\u003e\n    \u003cimg src=\"public/PDF.png\" alt=\"Import PDF Screen\" width=\"400\" /\u003e\n\n\u003c/p\u003e\n\n[Quick Start](#-quick-start) • [Architecture](#-architecture--data-flow) • [Key Patterns](#-key-architectural-patterns) • [Project Structure](#-project-structure)\n\n📽️ [Quick Demo Video](https://youtu.be/NAl0ogYWZHo)\n\n\u003c/div\u003e\n\n---\n\n## 🚀 Overview\n\nThis repository contains the frontend for the Stackifier platform, a responsive single-page application (SPA) built with **React 19**, **Vite**, and **TypeScript**. It provides a secure, multi-tenant user interface for document management, real-time conversational AI, and dynamic financial data visualization.\n\nThe architecture emphasizes a clear separation of concerns, robust state management via **React Context**, and a well-defined data access layer for interacting with both the Supabase BaaS and the custom FastAPI backend.\n\n### ✨ Core Capabilities\n\n-   **🔐 Centralized Authentication:** A global `AuthContext` manages the Supabase JWT session, providing a single source of truth for user authentication state across the entire application.\n-   **🛡️ Protected Routing:** Implements a `PrivateRoute` component that leverages the auth context to guard access to sensitive pages like dashboards and chat, seamlessly redirecting unauthenticated users.\n-   **⚡ Real-Time Data Streaming:** The chat interface (`Chat.tsx`) consumes Server-Sent Events (SSE) from the backend, parsing and rendering streamed AI responses and structured data in real-time.\n-   **📊 Dynamic, Data-Driven Visualization:** A reusable `ChartComponent` renders multiple chart types (`bar`, `line`, `pie`, `composed`) based on a standardized JSON schema provided by the backend's LLM agent.\n-   **📂 Typed Data Access Layer:** All interactions with external services are encapsulated in a typed `supabase/` directory, ensuring type safety and abstracting away API logic from UI components.\n-   **🎨 Modern UI/UX:** Built with **Tailwind CSS** and **DaisyUI**, providing a consistent, themeable, and responsive user experience.\n\n## 🛠 Tech Stack\n\n| Category           | Technology / Library                                       |\n| :----------------- | :--------------------------------------------------------- |\n| **Framework**      | `React 19`, `Vite`                                         |\n| **Language**       | `TypeScript`                                               |\n| **Styling**        | `Tailwind CSS 4`, `DaisyUI`                                |\n| **Routing**        | `wouter`                                                   |\n| **State Management** | `React Context API`                                        |\n| **Data Visualization** | `recharts`                                                 |\n| **API Client**     | `@supabase/supabase-js`, `fetch` API                       |\n| **Markdown**       | `react-markdown` with `remark-gfm`                         |\n\n## 🏗 Architecture \u0026 Data Flow\n\nThe frontend architecture is designed around a clear, unidirectional data flow, managed by a central authentication context and a dedicated data access layer.\n\n```mermaid\ngraph TD\n    subgraph \"Browser\"\n        User[User Interaction]\n    end\n    \n    subgraph \"React Application\"\n        direction LR\n        \n        subgraph \"Routing (wouter)\"\n            App[App.tsx\u003cbr\u003e\u003ci\u003eRoute Definitions\u003c/i\u003e]\n            PrivateRoute[PrivateRoute.tsx\u003cbr\u003e\u003ci\u003eAuth Guard\u003c/i\u003e]\n        end\n\n        subgraph \"State Management\"\n            AuthContext[AuthContext.tsx\u003cbr\u003e\u003ci\u003eSession \u0026 User State\u003c/i\u003e]\n        end\n\n        subgraph \"UI Components\"\n            Pages[Pages\u003cbr\u003e\u003ci\u003eDashboard, Chat, Documents\u003c/i\u003e]\n            Sidebar[Sidebar.tsx]\n            ChartComponent[ChartComponent.tsx]\n        end\n        \n        subgraph \"Data Access Layer (supabase/)\"\n            SupabaseClient[client.ts\u003cbr\u003e\u003ci\u003eAuth, DB Client\u003c/i\u003e]\n            DocumentService[documents.ts]\n            ChatService[chatService.ts]\n        end\n    end\n    \n    subgraph \"External Services\"\n        FastAPI_Backend[FastAPI Backend]\n        Supabase_Service[Supabase]\n    end\n\n    %% Component Interactions\n    User --\u003e Pages\n    User --\u003e Sidebar\n\n    App --\u003e PrivateRoute\n    App --\u003e Pages\n    \n    PrivateRoute -- \"Consumes\" --\u003e AuthContext\n    Pages -- \"Consumes\" --\u003e AuthContext\n    Sidebar -- \"Consumes\" --\u003e AuthContext\n\n    Pages -- \"Calls\" --\u003e DocumentService\n    Pages -- \"Calls\" --\u003e ChatService\n    Sidebar -- \"Calls\" --\u003e DocumentService\n\n    %% Data Layer Interactions\n    AuthContext -- \"Manages Session with\" --\u003e SupabaseClient\n    DocumentService -- \"Fetches from\" --\u003e FastAPI_Backend\n    DocumentService -- \"Reads/Writes\" --\u003e Supabase_Service\n    ChatService -- \"Streams from\" --\u003e FastAPI_Backend\n    ChatService -- \"Reads/Writes\" --\u003e Supabase_Service\n    SupabaseClient -- \"Interacts with\" --\u003e Supabase_Service\n```\n\n## 🔑 Key Architectural Patterns\n\nThis application implements several key patterns crucial for building robust and maintainable SPAs.\n\n### 1. Centralized State Management (`AuthContext.tsx`)\n\nInstead of prop-drilling or using a heavy state management library, authentication is handled by a global React Context (`AuthProvider`).\n- **Mechanism:** It wraps the entire application in `App.tsx`. A `useEffect` hook subscribes to Supabase's `onAuthStateChange` listener.\n- **Benefit:** This ensures that the application's `session` and `user` state are always in sync with the Supabase authentication service in real-time. Any component can consume this state via the `useAuth` hook, decoupling it from the authentication logic itself.\n\n### 2. Protected Routing (`PrivateRoute.tsx`)\n\nAccess to authenticated routes is managed declaratively.\n- **Mechanism:** The `PrivateRoute` component wraps protected pages (e.g., `Dashboard`). It consumes the `AuthContext` to check the `session` and `isLoading` state.\n- **Flow:**\n    1. If `isLoading` is true, it renders a loading indicator.\n    2. If `isLoading` is false and no `session` exists, it uses `wouter`'s `Redirect` component to navigate the user to the home page.\n    3. If a `session` exists, it renders its `children`.\n- **Benefit:** This pattern keeps routing logic clean in `App.tsx` and centralizes the protection logic in one reusable component.\n\n### 3. Abstracted Data Access Layer (`supabase/`)\n\nAll external communication is isolated within the `supabase/` directory.\n- **Mechanism:** Files like `documents.ts` and `chatService.ts` export typed functions (e.g., `fetchDocuments`, `processDocument`, `fetchChatSessions`). These functions handle the `fetch` calls, header management (including the auth token), and data parsing.\n- **Benefit:** UI components remain agnostic of the specific API endpoints or data fetching logic. This makes components more reusable and simplifies future migrations or changes to the backend API.\n\n### 4. Real-Time Streaming \u0026 Custom Data Protocol (`Chat.tsx`)\n\nThe chat interface is designed for a real-time conversational experience.\n- **Mechanism:** It uses the browser's native `EventSource` API (or a polyfill via `fetch` with a `ReadableStream`) to connect to the backend's `/chat/stream` endpoint. As data chunks arrive, a `TextDecoder` processes them.\n- **Custom Protocol:** The component includes logic to parse special ` \u003cChartData\u003e...\u003c/ChartData\u003e ` tags embedded within the text stream. It buffers content between these tags until a complete block is received, then parses it as JSON and passes it to the `ChartComponent`.\n- **Benefit:** This innovative approach allows the LLM to seamlessly interleave text and complex, structured data (like charts) in a single, continuous stream, creating a rich and dynamic user experience.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n-   **Node.js 18+** and **npm**\n-   A running instance of the **Stackifier Backend API**\n-   A configured **Supabase Project**\n\n### ⚙️ Installation \u0026 Setup\n\n1.  **Clone the Repository**\n    If you've already cloned the backend, the frontend is included. Navigate to the `frontend` directory.\n\n2.  **Install Dependencies**\n    ```bash\n    cd frontend\n    npm install\n    ```\n\n3.  **Configure Environment Variables**\n    Create a `.env.local` file in the `frontend/` directory and add your Supabase and backend URLs:\n    ```env\n    # Supabase Credentials (must be prefixed with VITE_)\n    VITE_SUPABASE_URL=\"https://\u003cyour-project-ref\u003e.supabase.co\"\n    VITE_SUPABASE_ANON_KEY=\"your-anon-key\"\n\n    # URL for the running FastAPI backend\n    VITE_FASTAPI_BACKEND_URL=\"http://127.0.0.1:8000\"\n\n    # Optional: For pre-filling the login form during development\n    VITE_TEST_EMAIL=\"your_test_email@example.com\"\n    VITE_TEST_PASSWORD=\"your_test_password\"\n    ```\n\n4.  **Run the Development Server**\n    ```bash\n    npm run dev\n    ```\n\nThe application will be available at `http://localhost:5173`.\n\n## 📁 Project Structure\n\n```\nfrontend/\n└── src/\n    ├── assets/                 # Static assets like images\n    ├── components/             # Reusable React components (Sidebar, ChartComponent, etc.)\n    ├── config/                 # Centralized configuration (e.g., API endpoints)\n    ├── contexts/               # React Context providers (AuthContext.tsx)\n    ├── lib/                    # General utility functions (cn for classnames)\n    ├── pages/                  # Route components (Home, Login, Dashboard, Chat)\n    │   └── private/            # Components for authenticated routes\n    ├── supabase/               # Data Access Layer (client, documents, chat services)\n    ├── types/                  # TypeScript type definitions (chart.ts)\n    ├── App.tsx                 # Root component with routing logic\n    ├── main.tsx                # Application entry point\n    └── index.css               # Global styles and Tailwind/DaisyUI config\n```\n\n## 📘 FYP Report – Chapter 5 (Implementation \u0026 Testing)\n\nFor academic documentation, a dedicated Chapter 5 draft in markdown is included in this repository:\n\n- **File**: `chapter5.md`\n- **Purpose**:\n  - Provide a concise base text for the FYP Implementation and Testing chapter.\n  - Be the place where you document key code snippets that show how requirements are met (e.g. auth, RLS, ingestion, chat streaming).\n  - Capture important configuration settings (server URL, network endpoints, database/RLS security, environment variables).\n  - List all test cases in tables, covering authentication, document ingestion, RAG chat, security, and performance.\n\nYou can copy and extend this file when preparing the FYP report section on Implementation and Testing to match your faculty’s format.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanthelai%2Fstackrag-frontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbryanthelai%2Fstackrag-frontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanthelai%2Fstackrag-frontend/lists"}