SwiftChat Documentation

Version 1.4.2 — Complete Setup, Features & Reference Guide

SwiftChat is a full-featured, self-hostable SaaS messaging and collaboration platform built with React, TypeScript, and Supabase. It combines real-time chat, WebRTC voice/video calls, scheduled meetings, AI-powered features (via Gemini AI), CRM tools, and a powerful admin panel into a single deployable application.

Tech Stack

System Requirements

📁 Project Structure

swiftchat/
├── docs/                       # Documentation (this file)
├── public/                     # Static assets
│   ├── favicon.png             # App favicon
│   ├── pwa-192x192.png         # PWA icon (192px)
│   ├── pwa-512x512.png         # PWA icon (512px)
│   ├── robots.txt              # Search engine directives
│   └── sw-push.js              # Service worker for push notifications
├── src/
│   ├── assets/                 # Images and media files
│   ├── components/             # React components
│   │   ├── admin/              # Admin panel (40+ components)
│   │   │   └── settings/       # Admin settings sub-components
│   │   ├── auth/               # Authentication (login, signup, reset)
│   │   ├── call/               # Voice & video call UI
│   │   ├── channels/           # Broadcast channels
│   │   ├── chat/               # Messaging components
│   │   ├── communities/        # Community system
│   │   ├── contacts/           # Contact management
│   │   ├── inbox/              # Internal inbox
│   │   ├── landing/            # Landing page sections
│   │   ├── leads/              # CRM lead management
│   │   ├── media/              # Media viewers & uploaders
│   │   ├── meetings/           # Meeting scheduler & room
│   │   ├── notifications/      # Notification system
│   │   ├── onboarding/         # User onboarding flow
│   │   ├── orders/             # Order management
│   │   ├── profile/            # User profile views
│   │   ├── promotions/         # Promotion campaigns
│   │   ├── pwa/                # PWA install prompts
│   │   ├── settings/           # User settings panels
│   │   ├── sidebar/            # Navigation sidebar
│   │   ├── ui/                 # Shared UI components (shadcn)
│   │   └── workflows/          # Workflow automation
│   ├── contexts/               # React context providers
│   ├── hooks/                  # 95+ custom React hooks
│   ├── i18n/
│   │   └── locales/            # 13 language files (en, es, fr, de, pt, zh, ja, ko, ar, hi, bn, it, ru)
│   ├── integrations/
│   │   └── supabase/           # Supabase client & auto-generated types
│   ├── lib/                    # Utility libraries
│   ├── pages/                  # Page-level components
│   │   ├── AdminPage.tsx       # Admin dashboard page
│   │   ├── AuthPage.tsx        # Login/signup page
│   │   ├── ChatPage.tsx        # Main chat interface
│   │   ├── Index.tsx           # Route handler
│   │   ├── InstallPage.tsx     # PWA install page
│   │   ├── LandingPage.tsx     # Public landing page
│   │   ├── MeetingJoinPage.tsx # Meeting join flow
│   │   ├── MeetingRoomPage.tsx # Active meeting room
│   │   ├── NotFound.tsx        # 404 page
│   │   └── SetupPage.tsx       # Installation wizard
│   ├── stores/                 # Zustand state stores
│   ├── types/                  # TypeScript type definitions
│   ├── App.tsx                 # Main app component with routing
│   ├── index.css               # Global styles & design tokens
│   └── main.tsx                # Application entry point
├── supabase/
│   ├── config.toml             # Supabase project configuration
│   ├── functions/              # 18 Deno edge functions
│   │   ├── admin-create-user/
│   │   ├── admin-delete-user/
│   │   ├── admin-update-app-settings/
│   │   ├── admin-update-user/
│   │   ├── ai-call-summary/
│   │   ├── ai-chat/
│   │   ├── check-lead-follow-ups/
│   │   ├── cleanup-stale-calls/
│   │   ├── complete-installation/
│   │   ├── on-new-channel-message/
│   │   ├── on-new-message/
│   │   ├── process-scheduled-messages/
│   │   ├── seed-demo-users/
│   │   ├── send-push-notification/
│   │   ├── smart-replies/
│   │   ├── summarize-chat/
│   │   ├── transcribe-audio/
│   │   └── translate-message/
│   ├── migrations/             # SQL migration files
│   └── storage/
│       └── buckets.json        # Storage bucket definitions
├── .env                        # Environment variables
├── CHANGELOG.md                # Version history
├── LICENSE                     # MIT License
├── SECURITY.md                 # Security policy
├── package.json                # Dependencies & scripts
├── tailwind.config.ts          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
└── vite.config.ts              # Vite + PWA configuration

📋 Complete Setup Guide — Start to Finish

Follow these 10 steps in order to go from a fresh download to a fully working SwiftChat deployment. Each step builds on the previous one.

Step 1 — Create a Supabase Project

Step 2 — Configure the .env File

In the project root, create (or edit) a .env file with your Supabase credentials:

.envCopy
# ========================================
# SwiftChat Environment Configuration
# ========================================

# ----- REQUIRED: Supabase Connection -----
VITE_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key-here
VITE_SUPABASE_PROJECT_ID=YOUR_PROJECT_REF

# ----- App Mode -----
VITE_DEMO_MODE=false

# ----- OPTIONAL -----
# VITE_HCAPTCHA_SITE_KEY=your-hcaptcha-site-key
# VITE_MAPBOX_TOKEN=pk.your-mapbox-public-token

Step 3 — Install Dependencies

TerminalCopy
# Install frontend dependencies
npm install

# Install Supabase CLI (needed for Steps 4 & 5)
npm install supabase

Verify Supabase CLI: npx supabase --version

Step 4 — Deploy Database & Storage

This imports all tables, RLS policies, functions, triggers, and storage buckets into your Supabase project.

TerminalCopy
# Login to Supabase
npx supabase login

# Link to your project (use your Project Reference ID)
npx supabase link --project-ref YOUR_PROJECT_REF

# Deploy all database migrations (creates 70+ tables, storage buckets, RLS policies)
npx supabase db push

What This Creates

• 70+ database tables (profiles, messages, calls, meetings, leads, orders, etc.)
• Row Level Security (RLS) policies on every table
• 9 storage buckets (avatars, chat-attachments, voice-messages, etc.)
• Database functions & triggers (auto-timestamps, member counts, etc.)
• Realtime publications for messages, calls, and presence

Step 5 — Deploy Edge Functions

Deploy all 18 serverless backend functions to your Supabase project:

TerminalCopy
# Deploy all edge functions at once
npx supabase functions deploy

All 18 Edge Functions

Step 6 — Configure Authentication Settings

In the Supabase Dashboard:

Step 7 — Configure Edge Function Secrets

Go to Supabase Dashboard → Project Settings → Edge Functions → Secrets and add:

Generate VAPID Keys

TerminalCopy
npx web-push generate-vapid-keys

# Output:
# Public Key:  BEl62iUYgUivxIk...  ← (already configured in the app)
# Private Key: DH7FsOnD6WmP...    ← Add this as VAPID_PRIVATE_KEY secret

Step 8 — Build for Production

TerminalCopy
# Build the production bundle
npm run build

# Verify output
ls dist/
# Should contain: index.html, assets/, sw.js, manifest.webmanifest, etc.

The dist/ folder contains everything needed for deployment — it's a static SPA (Single Page Application).

Step 9 — Upload to Your Server

Copy the entire contents of the dist/ folder to your web server's document root. Choose your deployment method below:

Step 10 — Run the Setup Wizard

Open your domain in a browser (e.g., https://yourdomain.com). SwiftChat will automatically redirect to the Setup Wizard.

✅ Post-Setup Verification Checklist

🚀 Deployment Options

SwiftChat is a static SPA — it can be hosted anywhere that serves HTML files. Choose the method that fits your infrastructure:

Nginx (VPS / Cloud Server)

Create /etc/nginx/sites-available/swiftchat:

nginx.confCopy
server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name yourdomain.com www.yourdomain.com;

    # SSL (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    root /var/www/swiftchat;
    index index.html;

    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Gzip Compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;

    # Cache static assets (1 year — Vite hashes filenames)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # No caching for service worker
    location = /sw.js {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # SPA routing — serve index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Enable & restartCopy
sudo ln -s /etc/nginx/sites-available/swiftchat /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Apache / cPanel / Plesk

Create a .htaccess file in your document root (e.g., public_html/):

.htaccessCopy
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>

<IfModule mod_headers.c>
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</IfModule>

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType image/jpeg "access plus 1 year"
    ExpiresByType font/woff2 "access plus 1 year"
</IfModule>

<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/css application/javascript application/json image/svg+xml
</IfModule>

cPanel steps: Build locally → File Manager → Upload all files from dist/ to public_html → Create .htaccess above → Enable SSL via cPanel SSL/TLS.

Required Apache modules: sudo a2enmod rewrite headers expires deflate ssl

Docker

DockerfileCopy
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

# SPA routing config
RUN echo 'server { \
  listen 80; \
  root /usr/share/nginx/html; \
  index index.html; \
  location / { try_files $uri $uri/ /index.html; } \
  location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; } \
}' > /etc/nginx/conf.d/default.conf

EXPOSE 80

docker-compose.ymlCopy
version: '3.8'
services:
  swiftchat:
    build: .
    ports:
      - "80:80"
    restart: unless-stopped

TerminalCopy
# Build and run
docker build -t swiftchat .
docker run -d -p 80:80 --name swiftchat swiftchat

# Or with Docker Compose
docker-compose up -d

Vercel / Netlify

VercelCopy
npm i -g vercel
vercel --prod

NetlifyCopy
npm i -g netlify-cli
netlify deploy --prod

Both platforms handle SPA routing automatically. Set environment variables in the platform's dashboard.

SSL & Custom Domain

HTTPS is required for PWA installation, push notifications, and WebRTC calls.

Let's Encrypt (free SSL)Copy
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
# Auto-renewal is configured automatically

DNS Configuration

Core Features

SwiftChat includes a comprehensive set of features for messaging, collaboration, and business operations.

💬 Real-time Messaging

Built on Supabase Realtime with PostgreSQL change notifications for instant message delivery.

• 1:1 & Group Chats — Private conversations and multi-participant groups with avatar, name, and member management
• Typing Indicators — Real-time "is typing..." display via Supabase presence
• Read Receipts — Double-check marks showing sent → delivered → read status
• Message Reactions — Add emoji reactions to any message
• Reply Threading — Quote and reply to specific messages with context preview
• Message Editing & Deletion — Edit sent messages or delete them with timestamp tracking
• File Sharing — Send images, documents (PDF, Word), and videos via the chat-attachments bucket
• Voice Messages — Record and send audio notes, stored in voice-messages bucket
• Pinned & Starred Messages — Pin important messages for quick access, star favorites
• Scheduled Messages — Schedule messages for future delivery (processed by process-scheduled-messages edge function)
• Polls & Events — Create polls with voting, events with RSVP tracking
• Location Sharing — Share live location via Mapbox GL integration
• Message Search — Full-text search across all conversations
• Forward Messages — Forward messages to other conversations
• Online Presence — Online/offline/away status with auto-away detection
• Notification Sound — Audio notifications for new messages
• Pull-to-Refresh — Mobile-style refresh gesture
• Speech-to-Text — Voice input for message composition

📹 Voice & Video Calls

WebRTC peer-to-peer communication with STUN server support and DTLS-SRTP encryption.

• 1:1 Voice & Video Calls — HD adaptive quality with automatic bandwidth adjustment
• Group Calls — Multi-participant calls with individual mute/video controls
• Screen Sharing — Share full screen or specific application window
• Virtual Backgrounds — Blur or replace background using MediaPipe selfie segmentation and TensorFlow body segmentation
• Call Recording — Record calls locally, stored in call-recordings bucket (private)
• In-Call Chat — Text chat during active calls
• Call History — Full log of incoming, outgoing, and missed calls
• Call Quality Monitor — Real-time signal strength and connection quality indicator
• AI Call Summaries — Automatic transcription & summarization via Gemini AI
• Connection Timeout — Auto-hangup after 20 seconds if connection fails
• Graceful Permission Fallback — Handles camera/mic denial with synthetic silent audio track
• STUN Servers — Uses stun1–stun4.l.google.com for NAT traversal
• Incoming Call Notifications — Real-time ring notification with caller info

📅 Scheduled Meetings

Full meeting scheduler with WebRTC-powered meeting rooms.

• Create Meetings — Title, description, date/time, duration (15–240 min)
• Meeting Templates — Save and reuse meeting configurations
• Participant Management — Invite users, track accepted/declined/pending status
• Meeting Reminders — Configurable reminder notifications before meetings
• Meeting Notes — Collaborative notes within meetings
• Meeting Chat — Text chat during active meetings
• Meeting Recording — Record meetings, stored in dedicated storage
• Recurring Meetings — Daily, weekly, monthly recurrence patterns
• Join via Link — /meeting/:code for easy sharing
• Waiting Room — Host approval before participants join
• Meeting Analytics — Track attendance, duration, and engagement
• Meeting Join Page — Pre-join screen with camera/mic preview

📢 Channels

Broadcast-style channels for announcements, news, and content distribution.

• Public/Private Channels — Open for anyone or invite-only
• Multiple Channel Admins — Delegate channel management
• Subscriber Management — View and manage subscribers
• Scheduled Posts — Schedule content for future publishing
• Channel Analytics — Track views, engagement, and subscriber growth
• Channel Bans — Ban disruptive users with reason tracking
• Media Support — Share images, videos, PDFs via channel-media bucket

👥 Communities

Group spaces with comprehensive moderation, roles, and sub-groups.

• Community Groups — Create sub-groups within communities for focused discussions
• Role System — Owner, admin, moderator, member hierarchy
• Join Requests — Require approval for new members
• Invite Codes — Generate shareable invite links with usage limits and expiry
• Announcements — Pin important announcements for all members
• Auto-Moderation — Configurable blocked words filter
• Member Management — Mute (temporary), ban (permanent), kick members
• Reports — Member reporting system with admin review
• Community Analytics — Track member growth and engagement
• Welcome Messages — Automatic greeting for new members
• Notification Settings — Per-community notification preferences
• Rules Display — Community rules visible to all members

📇 Contacts

• Contact List — Add, organize, and manage contacts
• Activity Tracking — See recent activity for each contact
• Private Notes — Add personal notes to contacts (only visible to you)
• Quick Actions — One-click to start chat, voice call, or video call
• Profile Directory — Privacy-respecting user discovery (profile_directory view hides sensitive fields)
• Shared Media — View all media shared with a contact

📸 Status Updates

• Image & Video Statuses — Share media that expires after 24 hours
• Text Statuses — Post text-only updates
• View Tracking — See who viewed your status
• Media stored in status-media bucket

🤖 AI Integration (Gemini AI)

SwiftChat uses Gemini AI to power intelligent features across the platform. All AI features run through secure edge functions on your Supabase backend.

Smart Replies

AI-generated contextual reply suggestions displayed as quick-reply chips below the message input. Analyzes recent conversation context to suggest relevant responses.

Edge Function: smart-replies | Hook: useSmartReplies

AI Chat Assistant

Built-in conversational AI chatbot accessible from the sidebar. Supports streaming responses, markdown formatting, and maintains conversation context. Useful for Q&A, writing assistance, code generation, and general knowledge.

Edge Function: ai-chat | Hook: useAIChat

Chat & Call Summaries

Chat Summaries: Condense long conversations into key points and action items. Triggered on-demand per conversation.

Call Summaries: Automatically transcribe and summarize completed calls with key topics, decisions, and follow-ups.

Edge Functions: summarize-chat, ai-call-summary | Hooks: useChatSummary, useAICallSummary

Message Translation

Translate any message to any of the 13 supported languages with one click. Preserves formatting and context.

Edge Function: translate-message

Audio Transcription

Convert voice messages and audio recordings to text. Supports multiple languages and accents.

Edge Function: transcribe-audio

⚡ Workflow Automation

Create automated workflows triggered by events across the platform.

• Trigger Types — On new message, on new user, on schedule, on lead update
• Multi-step Workflows — Chain actions with conditions and delays
• Lead Follow-up Automation — Automatic reminders for inactive leads (via check-lead-follow-ups)
• Scheduled Message Processing — Automatic delivery of scheduled messages (via process-scheduled-messages)
• Stale Call Cleanup — Automatic cleanup of abandoned calls (via cleanup-stale-calls)

Hook: useWorkflows

📊 CRM & Lead Management

Full-featured CRM integrated directly into the messaging platform.

• Lead Pipeline — Kanban-style stages: New → Contacted → Qualified → Proposal → Negotiation → Won/Lost
• Lead Status — Active, inactive, converted tracking
• Activity Tracking — Log calls, emails, meetings, notes with full timeline
• Follow-up Reminders — Automatic alerts for leads inactive beyond a configurable threshold
• Import/Export — Bulk import/export leads via CSV
• Tags & Filtering — Categorize and filter leads by tags, source, stage, status, score
• Source Tracking — Track where leads originate (manual, website, referral, etc.)
• Assignment — Assign leads to team members

Lead Scoring

Automatic lead scoring based on activity, engagement, and profile completeness. Higher scores indicate more qualified leads.

Hook: useLeadScoring

Lead Templates

Save and reuse lead configurations with default values for stage, status, source, tags, and notes. Speeds up repetitive lead creation.

Hook: useLeadTemplates

Custom Fields

Define custom field types (text, number, date, dropdown) for leads. Fields can be marked as required and support custom sort order.

🛒 Orders & Products

Create and manage orders with full line item support.

• Order Management — Create, update, track order lifecycle (pending → confirmed → shipped → delivered)
• Line Items — Add products with quantity, unit price, total price
• Customer Info — Name, email, phone, billing & shipping addresses
• Payment Status — Pending, paid, refunded, failed tracking
• Lead Linking — Associate orders with CRM leads
• Order Notes — Internal notes on orders
• Currency Support — Multi-currency order tracking
• Order Numbers — Auto-generated unique order identifiers

Hook: useOrders

📣 Promotions & Coupons

• Promotion Campaigns — Create targeted promotions with images, descriptions, and scheduling
• A/B Testing — Test multiple promotion variants to optimize performance
• Coupon Codes — Generate discount codes with usage limits and expiry dates
• Analytics — Track views, clicks, conversions, and revenue per promotion
• Image Upload — Upload promotion banners to promotion-images bucket

Hooks: usePromotions, usePromotionABTesting, usePromotionCoupons, usePromotionAnalytics

📥 Inbox

Internal notification and messaging inbox separate from chat.

• Categories — General, system, alerts, updates
• Priority Levels — Low, normal, high, urgent
• Read/Unread Status — Mark as read/unread, bulk actions
• Message Types — Notification, alert, message

Hook: useInboxMessages

💳 Payment Gateways

Configurable payment gateway integrations managed via the admin panel.

Hook: usePaymentGateways | Admin Component: AdminPaymentGateways

🛡️ Admin Dashboard

Comprehensive admin panel accessible at /admin. Only users with admin or moderator roles can access this area.

Admin Sections

User Management

• View All Users — Searchable, filterable user list with pagination
• Create Users — Admin-created accounts via admin-create-user edge function
• Edit Users — Update name, email, avatar, role via admin-update-user
• Suspend Users — Temporarily disable accounts
• Delete Users — Permanently remove accounts via admin-delete-user
• Bulk Actions — Select multiple users for batch operations
• User Filters — Filter by role, status, date range
• Activity Timeline — View user's recent actions
• Export — Export user data

Roles & Permissions

App Settings

All settings are stored in the app_settings table and managed via the admin-update-app-settings edge function.

• General — Site name, description, logo URL, favicon URL, copyright text
• Features — Toggle individual features on/off (calls, meetings, channels, communities, CRM, AI, etc.)
• Appearance — Primary colors, fonts, dark mode default
• SEO — Meta title, description, OG image, keywords
• Security — hCaptcha toggle, session settings, registration controls
• Localization — Default language, enabled languages
• Notifications — Push notification settings, email notification preferences

Hook: useAppSettings (reads settings), useDynamicSettings (applies settings dynamically)

Moderation

• Flagged Messages — Review messages reported by users, with flag reason, notes, and resolution status
• Community Reports — Handle reports from community members
• User Suspension — Temporarily disable problematic accounts
• Admin Audit Logs — Complete audit trail of all admin actions (who, what, when, from where)
• Message Editing — Edit inappropriate messages directly

Hooks: useMessageFlags, useAdminActivityLogs

Analytics & System Health

• Real-time Stats — Online users, total users, new users today
• Message Volume — Messages per day/week/month charts
• Call Analytics — Call volume, duration, type distribution
• Community/Channel Growth — Member and subscriber trends
• Lead Pipeline — Conversion funnel visualization
• System Health — Database status, edge function status, storage usage
• Real-time Dashboard — Live-updating stats via useAdminRealtimeStats

Hooks: useAdminStats, useAdminRealtimeStats, useAdminAnalytics

Media Library

Central media management for admin-uploaded assets (logos, banners, branding materials).

• Upload — Drag-and-drop file upload to admin-media bucket
• Categories — Organize media by category
• Alt Text — SEO-friendly alt text for images
• File Info — File name, type, size, upload date

Hook: useAdminMedia

📖 Reference

Environment Variables (.env)

Required

Optional

Edge Function Secrets

Configured in Supabase Dashboard → Project Settings → Edge Functions → Secrets:

Database Schema

70+ tables with Row Level Security (RLS) on every table. All tables use UUID primary keys and include created_at timestamps.

Storage Buckets

All buckets have RLS policies for secure access control.

Create Storage Buckets (SQL)

If buckets are not auto-created by migrations, run this SQL in the Supabase SQL Editor:

SQL — Create Storage BucketsCopy
-- Create all 9 storage buckets
INSERT INTO storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
VALUES
  ('avatars', 'avatars', true, 5242880, ARRAY['image/png','image/jpeg','image/gif','image/webp']),
  ('voice-messages', 'voice-messages', true, 52428800, ARRAY['audio/webm','audio/mp4','audio/mpeg','audio/ogg','audio/wav']),
  ('call-recordings', 'call-recordings', false, 524288000, ARRAY['audio/webm','audio/mp4','video/webm','video/mp4']),
  ('status-media', 'status-media', true, 52428800, ARRAY['image/png','image/jpeg','image/gif','image/webp','video/mp4','video/webm']),
  ('channel-media', 'channel-media', true, 52428800, ARRAY['image/png','image/jpeg','image/gif','image/webp','video/mp4','video/webm','application/pdf']),
  ('community-avatars', 'community-avatars', true, 5242880, ARRAY['image/png','image/jpeg','image/gif','image/webp']),
  ('promotion-images', 'promotion-images', true, 10485760, ARRAY['image/png','image/jpeg','image/gif','image/webp']),
  ('chat-attachments', 'chat-attachments', true, 52428800, ARRAY['image/png','image/jpeg','image/gif','image/webp','video/mp4','video/webm','application/pdf','application/msword','application/vnd.openxmlformats-officedocument.wordprocessingml.document']),
  ('admin-media', 'admin-media', true, 52428800, ARRAY['image/png','image/jpeg','image/gif','image/webp','image/svg+xml','video/mp4','video/webm'])
ON CONFLICT (id) DO NOTHING;

Storage Bucket RLS Policies (SQL)

Run these SQL statements to secure all storage buckets with Row Level Security policies:

SQL — Avatars Bucket PoliciesCopy
-- AVATARS: Public read, user-scoped write
CREATE POLICY "Avatar images are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'avatars');

CREATE POLICY "Users can upload their own avatar"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can update their own avatar"
  ON storage.objects FOR UPDATE
  USING (bucket_id = 'avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own avatar"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

SQL — Chat Attachments Bucket PoliciesCopy
-- CHAT-ATTACHMENTS: Public read, user-scoped write
CREATE POLICY "Chat attachments are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'chat-attachments');

CREATE POLICY "Users can upload chat attachments"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'chat-attachments' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own chat attachments"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'chat-attachments' AND auth.uid()::text = (storage.foldername(name))[1]);

SQL — Voice Messages Bucket PoliciesCopy
-- VOICE-MESSAGES: Public read, user-scoped write
CREATE POLICY "Voice messages are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'voice-messages');

CREATE POLICY "Users can upload voice messages"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'voice-messages' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own voice messages"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'voice-messages' AND auth.uid()::text = (storage.foldername(name))[1]);

SQL — Call Recordings Bucket Policies (Private)Copy
-- CALL-RECORDINGS: Private bucket — only uploader can access
CREATE POLICY "Users can view their own call recordings"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'call-recordings' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can upload call recordings"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'call-recordings' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own call recordings"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'call-recordings' AND auth.uid()::text = (storage.foldername(name))[1]);

SQL — Status, Channel, Community Bucket PoliciesCopy
-- STATUS-MEDIA: Public read, user-scoped write
CREATE POLICY "Status media is publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'status-media');

CREATE POLICY "Users can upload status media"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'status-media' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own status media"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'status-media' AND auth.uid()::text = (storage.foldername(name))[1]);

-- CHANNEL-MEDIA: Public read, user-scoped write
CREATE POLICY "Channel media is publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'channel-media');

CREATE POLICY "Users can upload channel media"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'channel-media' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own channel media"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'channel-media' AND auth.uid()::text = (storage.foldername(name))[1]);

-- COMMUNITY-AVATARS: Public read, user-scoped write
CREATE POLICY "Community avatars are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'community-avatars');

CREATE POLICY "Users can upload community avatars"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'community-avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Users can delete their own community avatars"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'community-avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

SQL — Admin & Promotion Bucket PoliciesCopy
-- PROMOTION-IMAGES: Public read, admin-only write
CREATE POLICY "Promotion images are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'promotion-images');

CREATE POLICY "Admins can upload promotion images"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'promotion-images' AND public.has_role(auth.uid(), 'admin'));

CREATE POLICY "Admins can update promotion images"
  ON storage.objects FOR UPDATE
  USING (bucket_id = 'promotion-images' AND public.has_role(auth.uid(), 'admin'));

CREATE POLICY "Admins can delete promotion images"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'promotion-images' AND public.has_role(auth.uid(), 'admin'));

-- ADMIN-MEDIA: Public read, admin-only write
CREATE POLICY "Admin media is publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'admin-media');

CREATE POLICY "Admins can upload admin media"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'admin-media' AND public.has_role(auth.uid(), 'admin'));

CREATE POLICY "Admins can update admin media"
  ON storage.objects FOR UPDATE
  USING (bucket_id = 'admin-media' AND public.has_role(auth.uid(), 'admin'));

CREATE POLICY "Admins can delete admin media"
  ON storage.objects FOR DELETE
  USING (bucket_id = 'admin-media' AND public.has_role(auth.uid(), 'admin'));

Edge Functions

All 18 edge functions are Deno-based serverless functions deployed to Supabase. JWT verification is disabled for all functions (they handle auth internally).

Custom Hooks Reference

SwiftChat includes 95+ custom React hooks organized by feature domain:

📱 PWA & Mobile

SwiftChat is a Progressive Web App installable on any device.

• Install Prompt — Native browser install banner with custom UI
• Offline Support — Service worker caching for offline access
• Push Notifications — Browser notifications for messages, calls, and meetings
• Responsive Design — Optimized layouts for mobile, tablet, and desktop
• Install Page — Dedicated /install page with QR code for easy mobile install
• App Icons — 192x192 and 512x512 PWA icons
• Manifest — Auto-generated manifest.webmanifest by vite-plugin-pwa
• Service Worker — sw-push.js handles push notifications in background

🌐 Internationalization

13 languages supported via i18next with automatic language detection:

Users can switch languages via Settings → Language. The app remembers the preference across sessions.

🔒 Security

Authentication

• Email/Password — Standard registration with optional email verification
• Phone OTP — SMS-based login (requires SMS provider in Supabase)
• Password Reset — Email-based password recovery flow
• Auto-refresh Tokens — Sessions refresh automatically before expiry
• Persistent Sessions — Sessions survive browser restarts via localStorage
• Global Sign-out — Sign out from all devices

Data Protection

• Row Level Security (RLS) — Every single table has RLS policies. Users can only access their own data.
• Profile Privacy — A profile_directory database view hides sensitive fields from public queries
• PKCE Auth Flow — Proof Key for Code Exchange for enhanced OAuth security
• hCaptcha — Optional bot protection on registration forms
• Zod Validation — All forms validated with Zod schemas before submission
• Role-based Access Control — has_role() SECURITY DEFINER function prevents privilege escalation
• Admin Audit Logging — Every admin action is logged with user ID, IP, timestamp, and details
• Security Headers — X-Frame-Options, X-Content-Type-Options, HSTS recommended in server config
• WebRTC Encryption — DTLS-SRTP for voice/video call encryption
• Storage RLS — All 9 storage buckets have granular access policies

🧪 Demo / Test Mode

Set VITE_DEMO_MODE=true in .env to enable demo mode for testing or showcasing.

What Demo Mode Does

• Shows "Demo Accounts Quick Access" panel on the login page
• Displays a floating demo badge/watermark across the app
• Hides sign-up form, phone auth, and forgot password links
• Restricts demo-flagged users from destructive actions (delete, modify settings, etc.)

Demo Accounts

After enabling demo mode, invoke the seed-demo-users edge function to create test accounts:

Available Scripts

🔧 Troubleshooting

❓ FAQ

Can I use SwiftChat without Supabase?

No. SwiftChat is built on Supabase for its database, authentication, storage, realtime, and edge functions. All backend logic depends on Supabase.

Is SwiftChat free to use?

SwiftChat itself is open-source. You'll need a Supabase project (free tier available) and a server to host the frontend. AI features require a Gemini API key (free tier available from Google).

Can I customize the branding?

Yes. Use the Admin Panel → Settings to change the site name, logo, favicon, colors, and more. All branding is configurable without code changes.

How do I add a new language?

Create a new JSON file in src/i18n/locales/ (e.g., tr.json for Turkish) following the structure of en.json. Register it in the i18next configuration.

How do I set up cron jobs for scheduled functions?

In the Supabase Dashboard, go to Database → Extensions and enable pg_cron. Then create cron jobs that call your edge functions via HTTP. Example:

SELECT cron.schedule('process-messages', '*/5 * * * *', 
  $$SELECT net.http_post('https://YOUR_REF.supabase.co/functions/v1/process-scheduled-messages', '{}', '{}', 
  ARRAY[net.http_header('Authorization', 'Bearer YOUR_SERVICE_ROLE_KEY')])$$);

How many concurrent users can SwiftChat handle?

This depends on your Supabase plan. The free tier supports ~50 concurrent realtime connections. Paid plans scale to thousands. WebRTC calls are peer-to-peer, so they don't consume server resources beyond signaling.

Can I deploy SwiftChat on shared hosting?

Yes, if the host supports serving static files with URL rewriting (most cPanel hosts do). See the Apache / cPanel deployment guide.

📝 Changelog

v1.4.2 Latest

Released: February 20, 2026

✨ New Features

• Unified single-page documentation covering every feature, setup step, and reference table
• Comprehensive custom hooks reference with 95+ hooks documented by domain
• FAQ section with common deployment and configuration questions
• Docker Compose support with production-ready configuration

🔧 Improvements

• All AI features now reference Gemini AI engine consistently throughout documentation and codebase
• Storage bucket RLS policies audited and verified for all 9 buckets
• Documentation restructured from fragmented multi-page format into single comprehensive guide
• Removed all external development tool branding references from source code, metadata, and documentation
• Improved deployment guides with security headers (HSTS) and Docker Compose examples
• Added 13th language (Russian) to i18n language list

🐛 Bug Fixes

• Fixed documentation referencing incorrect AI API key names
• Fixed inconsistent version numbers across documentation pages
• Fixed missing storage bucket documentation for admin-media and status-media

🗑️ Removed

• Removed 20+ obsolete multi-page documentation files (replaced by unified guide)
• Removed duplicate CSS and JS files from docs directory
• Cleaned up legacy documentation template files

v1.3.0

Released: February 15, 2026

✨ New Features

• Centralized demo/test mode via VITE_DEMO_MODE with granular feature flags
• WebRTC connection timeout — auto-hangup after 20s with user-friendly error
• Expanded STUN servers (stun1–stun4.l.google.com) for better NAT traversal
• Graceful camera/mic permission denial handling with synthetic silent audio fallback
• Admin settings integration verified across all modules

🔧 Improvements

• Auth page uses centralized demoConfig for all demo-related UI controls
• Group WebRTC creates synthetic silent streams on media failure instead of crashing
• Consistent demo restriction messaging across all hooks

🐛 Bug Fixes

• Fixed "Failed to start call" when camera/microphone permissions are denied
• Fixed calls stuck on "Connecting..." indefinitely
• Fixed admin redirect race condition after clearing browser cache

🔒 Security

• Demo mode controls enforced via environment variable — no client-side bypass possible
• Demo user restrictions enforced via is_demo flag in user_roles table

v1.0.0

Released: January 20, 2026

🔒 Security

• PKCE authentication flow for enhanced OAuth security
• Updated all npm dependencies to latest secure versions
• Added LICENSE (MIT) and SECURITY.md documentation

✨ Initial Release

• Real-time messaging with typing indicators, read receipts, and reactions
• WebRTC voice and video calls with DTLS-SRTP encryption
• AI-powered features (chat summarization, translation, transcription)
• CRM lead and contact management with scoring and templates
• 12-language internationalization support
• Progressive Web App (PWA) support with push notifications
• 6+ payment gateway integrations
• Comprehensive admin dashboard with 25+ management sections
• Scheduled meetings with WebRTC-powered meeting rooms
• Channels and communities with moderation tools
• Docker-based self-hosting support

📄 License

SwiftChat is released under the MIT License. See the LICENSE file in the project root for details.