AI Side Panel — Code Reference

Project Overview

A Chrome Extension side panel UI with AI chat, dictionary lookup, voice input, token-based subscriptions, and user authentication.

Tech Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui
• Backend: Lovable Cloud (Supabase) — Edge Functions, Auth, PostgreSQL
• AI Models: GPT-5 (OpenAI), Gemini (Google) via Lovable AI Gateway, Local LLM (FastAPI)
• Voice: Web Speech API (browser-native)

Project Structure

src/
├── components/
│   ├── ui/                    # shadcn/ui base components
│   ├── ChatInterface.tsx      # Main chat with streaming, persistence, voice
│   ├── DefinitionCard.tsx     # Dictionary + AI summary for highlighted text
│   ├── ModelSelector.tsx      # AI model dropdown (GPT-5/Gemini/Local)
│   ├── SettingsPanel.tsx      # Local LLM endpoint config
│   ├── TokenDisplay.tsx       # Token usage progress bar
│   ├── UserMenu.tsx           # User dropdown (profile, subscription, logout)
│   ├── VoiceInput.tsx         # Web Speech API microphone button
│   └── NavLink.tsx            # Navigation helper
├── hooks/
│   ├── useAuth.tsx            # Auth context provider (signup/login/logout)
│   ├── useTokens.tsx          # Token usage tracking hook
│   ├── use-toast.ts           # Toast notifications
│   └── use-mobile.tsx         # Mobile detection
├── lib/
│   ├── chat.ts                # Chat streaming (cloud + local LLM)
│   ├── dictionary.ts          # Dictionary API + AI summary
│   └── utils.ts               # Tailwind utility
├── pages/
│   ├── Index.tsx               # Main panel page
│   ├── Auth.tsx                # Login/Signup page
│   ├── Subscription.tsx        # Plans & token usage page
│   └── NotFound.tsx            # 404
├── types/
│   └── speech.d.ts             # Web Speech API type declarations
├── integrations/supabase/      # Auto-generated (DO NOT EDIT)
│   ├── client.ts
│   └── types.ts
└── index.css                   # Design tokens (dark mode default)

supabase/
├── config.toml                 # Auto-generated (DO NOT EDIT)
└── functions/
    ├── chat/index.ts           # SSE streaming proxy to Lovable AI Gateway
    └── define/index.ts         # AI summary generation

Database Schema

profiles

Column	Type	Description
id	UUID	Primary key
user_id	UUID	FK to auth.users
display_name	TEXT	User display name
avatar_url	TEXT	Profile picture URL
subscription_plan	TEXT	"free", "pro", "unlimited"
daily_token_limit	INTEGER	Default: 1000

conversations

Column	Type	Description
id	UUID	Primary key
user_id	UUID	FK to auth.users
title	TEXT	Chat title
model	TEXT	AI model used

messages

Column	Type	Description
id	UUID	Primary key
conversation_id	UUID	FK to conversations
user_id	UUID	FK to auth.users
role	TEXT	"user" or "assistant"
content	TEXT	Message content
tokens_used	INTEGER	Estimated tokens

token_usage

Column	Type	Description
id	UUID	Primary key
user_id	UUID	FK to auth.users
date	DATE	Usage date (unique per user/day)
tokens_used	INTEGER	Total tokens used that day

All tables have RLS policies — users can only access their own data.

Key Features

Token System

• Free: 1,000 tokens/day (rough estimate: 1 token ≈ 4 characters)
• Token bar shown in the side panel header
• Daily reset (tracked by date in token_usage table)

Chat Persistence

• Conversations and messages saved to database when logged in
• Last conversation auto-loaded on page load
• Works without login (no persistence, no token limits)

Voice Input

• Uses browser-native Web Speech API
• Click microphone icon → speak → text appears in input
• Chrome/Edge supported; Safari partial support

Authentication

• Email/password signup with email verification
• Auto-creates profile on signup via database trigger
• User menu in header with subscription & logout

Environment Variables (auto-managed)

• VITE_SUPABASE_URL — Backend URL
• VITE_SUPABASE_PUBLISHABLE_KEY — Public API key
• VITE_SUPABASE_PROJECT_ID — Project identifier

Secrets (edge functions)

• LOVABLE_API_KEY — Lovable AI Gateway key (auto-configured)

Design System

• Dark mode by default (forced via html { color-scheme: dark })
• All colors via HSL CSS variables in index.css
• Custom tokens: --user-bubble, --assistant-bubble for chat bubbles
• Never use hardcoded colors in components — always use semantic tokens

Commands

npm install    # Install dependencies
npm run dev    # Start dev server
npm run build  # Production build