From c39c3bf710634b929f180ab53b595f400927b513 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 22 Sep 2025 09:59:26 +0000 Subject: [PATCH 1/2] Initial plan From de6ab074c00c7377e0a65c26ad7a07b58aefcd93 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:08:12 +0000 Subject: [PATCH 2/2] Add comprehensive .github/copilot-instructions.md file Co-authored-by: salindae25 <8200073+salindae25@users.noreply.github.com> --- .github/copilot-instructions.md | 204 ++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..7809f6e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,204 @@ +# Copilot Instructions for Browser Chat LLM + +## Repository Overview + +This is a browser-based chat interface for interacting with multiple Large Language Models (LLMs). The application runs entirely in the browser with no server-side component - all conversation data is stored locally in IndexedDB for privacy. + +**Repository Type**: Frontend web application +**Primary Languages**: TypeScript, React +**Size**: Medium (50+ source files) +**Target Runtime**: Modern web browsers + +### Key Features +- Multiple LLM provider support (OpenAI, Google Gemini, Groq, OpenAI-compatible endpoints like LM Studio and Ollama) +- Local IndexedDB storage for conversations and settings +- Serverless architecture with client-side only operation +- Project organization and chat tagging capabilities +- Modern React with TypeScript and Vite build system + +## Build and Validation Instructions + +### Prerequisites +- **Node.js**: LTS version (currently using v20.19.5) +- **pnpm**: Package manager (v9.15.1) - **ALWAYS** use pnpm, not npm + +### Environment Setup +1. **ALWAYS run `pnpm install` before any other command** - this is required for all operations +2. The project uses pnpm workspaces and exact dependency versions via `pnpm-lock.yaml` + +### Build Commands (in order of typical workflow) + +#### Installation and Dependencies +```bash +pnpm install # Always run first, takes ~15-20 seconds +``` + +#### Linting and Code Quality +```bash +pnpm lint # Biome linter - will show errors, expect ~2-8 errors typically +pnpm format # Biome formatter - will show format violations +pnpm check # Combined lint + format check - most comprehensive +``` + +**Important**: The project currently has known linting/formatting issues: +- Import type issues in UI components (`src/components/ui/dialog.tsx`, `src/components/ui/tabs.tsx`) +- Format violations in some files (quote styles, import organization) +- These are NOT blocking issues - the build will still succeed + +#### Building +```bash +pnpm build # Vite build + TypeScript compilation, takes ~8-10 seconds +``` +- Creates `dist/` directory with production assets +- Includes TypeScript compilation step +- Build succeeds even with linting issues +- Expect warnings about large chunks (>500KB) - this is normal + +#### Development Server +```bash +pnpm dev # Starts dev server on http://localhost:3000, takes ~2-3 seconds +# or +pnpm start # Alias for pnpm dev +``` + +#### Testing +```bash +pnpm test # Vitest unit tests - KNOWN TO FAIL currently +``` + +**Important**: Tests currently fail due to: +- Missing RouterProvider context in test setup +- IndexedDB API not available in test environment +- This is a known issue and NOT something you need to fix unless specifically tasked + +#### Preview Built Application +```bash +pnpm serve # Preview production build locally on http://localhost:4173 +``` + +### Timing Expectations +- `pnpm install`: 15-20 seconds (first time or after lock file changes) +- `pnpm build`: ~13-14 seconds total (8s Vite + 5s TypeScript) +- `pnpm dev`: 2-3 seconds to start +- `pnpm serve`: Instant start (requires prior build) +- `pnpm lint/format/check`: 1-2 seconds +- `pnpm test`: Will fail in ~1-2 seconds (known issue) + +## Project Architecture and Layout + +### Core Configuration Files +- `package.json` - Dependencies and scripts, uses pnpm as package manager +- `vite.config.js` - Vite build configuration with React plugin and manual chunking +- `tsconfig.json` - TypeScript configuration with strict settings +- `biome.json` - Linting and formatting rules (Biome instead of ESLint/Prettier) +- `components.json` - Shadcn/UI component configuration +- `vercel.json` - Deployment configuration with SPA routing + +### Source Code Structure (`src/`) + +#### Main Application Files +- `src/main.tsx` - Application entry point with router setup +- `src/App.tsx` - Main application component +- `src/styles.css` - Global CSS styles + +#### Core Architecture +- `src/lib/` - **Core business logic and utilities** + - `db.ts` - IndexedDB database setup using Dexie + - `models.ts` - TypeScript interfaces and type definitions + - `chat-store.ts` - Zustand state management for chat functionality + - `utils.ts` - Common utility functions + - `services/` - Business logic services for LLM providers + +#### UI Components +- `src/components/` - **React UI components** + - `ui/` - Base UI components from Shadcn/UI library + - `Chat/` - Chat-specific components + - `Header.tsx`, `Sidebar.tsx` - Layout components + - `OnboardingScreen.tsx` - Initial setup screen + +#### Application Structure +- `src/routes/` - **Page components and routing** + - `chat.section.tsx` - Main chat interface + - `settings.llm.tsx` - LLM provider configuration + - `settings.general.tsx` - General application settings +- `src/layout/` - Layout wrapper components +- `src/hooks/` - Custom React hooks (e.g., `use-mobile.ts`) +- `src/integrations/` - Third-party service integrations (TanStack Query) + +### Dependencies and Tech Stack +- **React 19** with TypeScript for UI +- **Vite** as build tool and dev server +- **TanStack Router** for client-side routing +- **TanStack Query** for async state management +- **Zustand** for global state management +- **Dexie** for IndexedDB database operations +- **Shadcn/UI** + **Radix UI** for component library +- **Tailwind CSS v4** for styling +- **Biome** for linting and formatting (not ESLint/Prettier) +- **AI SDK** for LLM provider integrations + +### Data Storage +- **IndexedDB** via Dexie for local data persistence +- Tables: `chatSessions`, `projects`, `llmProviders`, `llmModels`, `generalSettings` +- No backend required - fully client-side data management + +### LLM Provider Integration +Supports multiple providers via AI SDK: +- OpenAI (GPT models) +- Google (Gemini models) +- Groq +- OpenAI-compatible endpoints (LM Studio, Ollama) +- Configuration stored in IndexedDB + +## Validation and CI/CD +Currently no GitHub Actions workflows are configured. Validation is manual via the commands above. + +### Pre-commit Validation Steps +1. Run `pnpm check` (expect some linting issues - not blocking) +2. Run `pnpm build` (should succeed) +3. Manually test dev server with `pnpm dev` + +### Common Issues and Workarounds + +### Known Build Issues +1. **Linting errors are not blocking** - build succeeds despite lint failures +2. **Large bundle warnings** - expected due to syntax highlighting and AI SDK dependencies +3. **Test failures** - known issue with RouterProvider and IndexedDB mocking +4. **CSS warning during build** - Tailwind CSS syntax issue in output, does not affect functionality + +### Component Library Usage +- Uses **Shadcn/UI** components - add new components with: `pnpx shadcn@latest add ` +- Components are installed to `src/components/ui/` +- Configuration is in `components.json` + +### Common Fixes +- If dependencies seem out of sync: delete `node_modules` and run `pnpm install` +- If build fails: ensure you're using pnpm, not npm +- If dev server won't start: check port 3000 is available (or 4173 for preview) +- If syntax highlighting seems broken: it's included in the large syntax_highlighter chunk + +### File Locations Reference +- Package manager: `pnpm` (never use npm) +- Lock file: `pnpm-lock.yaml` +- Build output: `dist/` +- Static assets: `public/` +- Main HTML: `index.html` +- Environment files: Not used (client-side only) + +## Development Workflow + +1. **Always start with `pnpm install`** +2. For quick validation: `pnpm check && pnpm build` +3. For development: `pnpm dev` +4. The application will be available at `http://localhost:3000` +5. Linting issues are informational - don't block on them unless specifically fixing code quality + +## Important Notes for Agents + +- **TRUST THESE INSTRUCTIONS** - only search/explore if information is missing or incorrect +- Always use `pnpm` commands, never `npm` +- Expect and ignore current linting/formatting issues unless specifically tasked to fix them +- Tests currently fail - this is a known issue, not a blocker +- Build output warnings about large chunks are expected and normal +- The app is client-side only - no server setup needed +- Focus on `src/lib/` for business logic, `src/components/` for UI, `src/routes/` for pages \ No newline at end of file