update the readme files

README.md

@@ -220,11 +220,52 @@ All calls are proxied through the FastAPI backend running at `http://localhost:8
 
 ### Data Storage
 
-- **SQLite Databases** (for demo/development):
-  - `data/admin_rules.db` - Admin rules with regex patterns and severity
-  - `data/analytics.db` - Analytics events, tool usage, violations, RAG metrics
+IntegraChat supports **dual-backend storage** with automatic fallback:
 
-- **Production Ready**: Can easily swap SQLite for PostgreSQL/Supabase for production deployments.
+- **Supabase (Production/Preferred)**:
+  - `admin_rules` table - Admin rules with regex patterns and severity
+  - `tool_usage_events`, `redflag_violations`, `rag_search_events`, `agent_query_events` - Analytics tables
+  - Automatically used when `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` are configured
+  - Supports Row Level Security (RLS) for multi-tenant isolation
+  - Scalable, production-ready with automatic backups
+
+- **SQLite (Development Fallback)**:
+  - `data/admin_rules.db` - Admin rules (local)
+  - `data/analytics.db` - Analytics events (local)
+  - Used automatically when Supabase credentials are not available
+  - Perfect for local development and testing
+
+**Migration**: Use `python migrate_sqlite_to_supabase.py` to copy existing SQLite data to Supabase. See `SUPABASE_SETUP.md` for detailed setup instructions.
+
+---
+
+## Supabase Setup & Migration
+
+IntegraChat supports Supabase for production-ready storage of admin rules and analytics. Both `RulesStore` and `AnalyticsStore` automatically detect and use Supabase when credentials are available, falling back to SQLite for local development.
+
+### Quick Setup
+
+1. **Create Supabase tables**:
+   - Run `supabase_admin_rules_table.sql` in Supabase SQL Editor
+   - Run `supabase_analytics_tables.sql` in Supabase SQL Editor
+
+2. **Configure environment variables** in `.env`:
+   ```env
+   SUPABASE_URL=https://your-project-id.supabase.co
+   SUPABASE_SERVICE_KEY=your_service_role_key_here
+   ```
+
+3. **Migrate existing data** (optional):
+   ```bash
+   python migrate_sqlite_to_supabase.py
+   ```
+
+4. **Verify setup**:
+   ```bash
+   python verify_supabase_setup.py
+   ```
+
+See `SUPABASE_SETUP.md` and `SUPABASE_MIGRATION_COMPLETE.md` for detailed instructions and troubleshooting.
 
 ---
 
@@ -244,6 +285,15 @@ IntegraChat ships with several helper scripts to validate the full stack end-to-
 - `python check_rag_database.py`  
   Provides a low-level inspection of the RAG datastore. It connects straight to the pgvector/Postgres instance, lists all tenant IDs, prints sample chunks, and runs `search_vectors()` directly to ensure the SQL `WHERE tenant_id = …` filter is behaving as expected. Use this script when diagnosing suspected cross-tenant leakage or when seeding demo data.
 
+- `python verify_supabase_setup.py`  
+  Verifies Supabase configuration and shows which backend (Supabase or SQLite) each store is using. Displays any missing configuration and provides a summary of where data will be saved.
+
+- `python check_supabase_rules.py`  
+  Checks Supabase admin rules configuration and RLS policies. Validates that rules can be read/written correctly.
+
+- `python migrate_sqlite_to_supabase.py`  
+  One-shot migration script that copies existing SQLite data (admin rules + analytics) to Supabase. Supports both PostgreSQL direct connection and Supabase REST API methods.
+
 - `python test_manual.py`  
   The existing manual test runner remains useful for smoke-testing analytics logging, admin rule CRUD, and API response codes. Run it whenever you adjust schemas or update MCP endpoints.
 
@@ -286,8 +336,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **UI Libraries**: Plotly for interactive charts, Gradio for web interface
 - **LLM Integration**: Ollama (local) or Groq (cloud) via configurable backend with streaming support
 - **Vector Store**: pgvector (via Supabase) or SQLite embeddings
-- **Analytics**: SQLite with indexed queries for fast analytics
-- **Rules Storage**: Supabase (production) or SQLite (development) with automatic table creation
+- **Analytics**: Supabase (production) or SQLite (development) with indexed queries for fast analytics
+- **Rules Storage**: Supabase (production) or SQLite (development) with automatic detection and fallback
 - **MCP Server**: Unified MCP server (port 8900) exposing all tools via namespaces
 - **Database**: PostgreSQL with pgvector extension for RAG embeddings, SQLite for analytics
 - **File Processing**: Support for TXT, PDF, DOC, DOCX with server-side text extraction (PyPDF2, python-docx)

backend/README.md

@@ -12,7 +12,10 @@ This folder contains the production-ready FastAPI stack plus the companion MCP s
 
 - Python 3.10+
 - PostgreSQL (with the `vector` extension) for RAG data, or Supabase with pgvector enabled
-- Supabase (preferred) for admin rules + analytics, with automatic SQLite fallback in `data/`
+- **Supabase (recommended)** for admin rules + analytics storage, with automatic SQLite fallback in `data/`
+  - Both `RulesStore` and `AnalyticsStore` automatically detect and use Supabase when configured
+  - Falls back to SQLite automatically if Supabase credentials are missing
+  - See `SUPABASE_SETUP.md` in the root directory for setup instructions
 - Optional: Ollama running locally (default) or Groq API credentials for remote LLMs
 
 Create a virtual environment at the repo root, then:
@@ -88,6 +91,9 @@ Use the helper scripts in the repo root when validating backend changes:
 
 - `python verify_tenant_isolation.py` – Exercises analytics logging, admin rule CRUD, API reachability, and proves RAG tenant isolation by ingesting + querying as multiple tenants.
 - `python check_rag_database.py` – Talks directly to the pgvector database to list tenant IDs, preview stored chunks, and run safeguarded searches via `search_vectors()`. Helpful when troubleshooting suspected cross-tenant leakage.
+- `python verify_supabase_setup.py` – Verifies Supabase configuration and shows which backend (Supabase or SQLite) each store is using.
+- `python check_supabase_rules.py` – Checks Supabase admin rules configuration and RLS policies.
+- `python migrate_sqlite_to_supabase.py` – One-shot migration script to copy existing SQLite data to Supabase.
 - `python test_manual.py` – Legacy manual smoke test harness (analytics store, admin rules, API surface).
 
 > **Troubleshooting tip:** If the isolation script reports a failure, first run `check_rag_database.py` to confirm documents are tagged with the correct `tenant_id`, then restart the unified MCP server so it reloads the updated SQL filtering logic.
@@ -149,13 +155,58 @@ Defined in `env.example`:
 - `MCP_HOST` - Host for unified MCP server (default: 0.0.0.0)
 - `POSTGRESQL_URL` - PostgreSQL connection string with pgvector extension
 - `OLLAMA_URL`, `OLLAMA_MODEL` (or `GROQ_API_KEY` + `LLM_BACKEND=groq`)
-- `SUPABASE_URL`, `SUPABASE_SERVICE_KEY` (optional admin integrations)
+- `SUPABASE_URL`, `SUPABASE_SERVICE_KEY` - **Required for Supabase backend** (admin rules + analytics)
+  - If not set, the system automatically falls back to SQLite in `data/` directory
+  - See `SUPABASE_SETUP.md` in the root directory for detailed setup instructions
 - `APP_ENV`, `LOG_LEVEL`, `API_PORT`
 
 Update these before starting the servers to ensure the agent can reach every MCP endpoint and LLM runtime.
 
 **Note**: The unified MCP server runs on a single port (default 8900) and handles all namespaced tools. The `start.bat` script automatically configures the correct URLs.
 
+## Supabase Configuration
+
+Both `RulesStore` and `AnalyticsStore` support dual-backend storage with automatic detection:
+
+### Setup Steps
+
+1. **Create Supabase tables**:
+   - Run `supabase_admin_rules_table.sql` in Supabase SQL Editor (from repo root)
+   - Run `supabase_analytics_tables.sql` in Supabase SQL Editor (from repo root)
+
+2. **Configure environment variables** in `.env`:
+   ```env
+   SUPABASE_URL=https://your-project-id.supabase.co
+   SUPABASE_SERVICE_KEY=your_service_role_key_here
+   ```
+
+3. **Verify configuration**:
+   ```bash
+   python verify_supabase_setup.py
+   ```
+
+4. **Migrate existing data** (if you have SQLite data):
+   ```bash
+   python migrate_sqlite_to_supabase.py
+   ```
+
+### How It Works
+
+- **Automatic Detection**: Both stores check for `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` at initialization
+- **Supabase First**: If credentials are found, Supabase is used automatically
+- **SQLite Fallback**: If Supabase is not configured, SQLite databases in `data/` are used
+- **Startup Logging**: Check startup logs to see which backend each store is using:
+  - `✅ RulesStore: Using Supabase backend`
+  - `✅ AnalyticsStore: Using Supabase backend`
+  - Or `⚠️  RulesStore: Using SQLite backend` if Supabase is not configured
+
+### Tables Used
+
+- **Admin Rules**: `admin_rules` table in Supabase
+- **Analytics**: `tool_usage_events`, `redflag_violations`, `rag_search_events`, `agent_query_events`
+
+See `SUPABASE_SETUP.md` and `SUPABASE_MIGRATION_COMPLETE.md` in the root directory for detailed instructions and troubleshooting.
+
 ## Unified MCP tool instructions
 
 Agents that speak the Model Context Protocol should connect to the `integrachat` server id defined in `backend/mcp_server/server.py` and call the namespaced tools directly:
@@ -198,3 +249,10 @@ Agents that speak the Model Context Protocol should connect to the `integrachat`
 - **Tenant ID mismatch**: The system normalizes tenant IDs, but ensure you're using the same tenant_id format as when documents were ingested
 - **Check logs**: Database deletion logs show detailed information about tenant ID matching and document existence
 
+### Supabase Configuration Issues
+- **Data still going to SQLite**: Check that `SUPABASE_URL` and `SUPABASE_SERVICE_KEY` are set correctly in `.env` (no quotes, no spaces)
+- **Service role key errors**: Make sure you're using the **service_role** key (not anon key) from Supabase Dashboard → Settings → API
+- **Tables don't exist**: Run `supabase_admin_rules_table.sql` and `supabase_analytics_tables.sql` in Supabase SQL Editor
+- **Permission errors**: Check RLS policies in Supabase allow service role access
+- **Startup warnings**: Check FastAPI startup logs to see which backend each store is using (`✅` for Supabase, `⚠️` for SQLite fallback)
+