# Ersilia.ai - Complete Documentation

> Ersilia.ai is a production-grade SaaS platform that helps freelancers and consultants detect and prevent scope creep using AI-powered analysis. Built with React 18, TypeScript, Supabase, and Google Gemini AI. Grade A+ (100/100), 1,230 tests passing, deployed at https://ersilia.ai

---

## Table of Contents

1. Product Overview
2. Core Features & Capabilities
3. Pricing & Subscription Tiers
4. Technical Architecture
5. Security & Compliance
6. Integrations & Notifications
7. User Journey & Onboarding
8. Development & Deployment
9. Testing & Quality Assurance
10. Performance & Optimization
11. API Reference
12. Database Schema
13. Environment Configuration
14. Monitoring & Observability
15. Support & Resources

---

## 1. Product Overview

### Mission
Ersilia helps freelancers stop working for free by automatically detecting scope creep in client communications before it impacts project profitability.

### Problem Statement
- Freelancers lose an average of 15-20 hours per month to scope creep
- 73% of freelancers struggle to identify scope creep until it's too late
- Manual monitoring of client communications is time-consuming and error-prone
- Lost revenue from unbilled work averages $2,400-$3,600 per month

### Solution
AI-powered analysis of client communications (email, Slack, SMS, WhatsApp) that:
1. Compares requests against original project scope
2. Detects out-of-scope work in real-time
3. Sends instant alerts via 7+ notification channels
4. Tracks revenue protected and time saved
5. Provides analytics on scope creep patterns

### Target Users
- **Freelancers**: Individual consultants, designers, developers
- **Consultants**: Business advisors, strategy consultants
- **Agencies**: Small teams managing multiple client projects
- **Contractors**: Independent professionals on fixed-scope contracts

### Key Differentiators
1. **AI-Powered**: Uses Google Gemini for intelligent scope analysis
2. **Multi-Channel**: Monitors 7+ communication platforms
3. **Real-Time Alerts**: Instant notifications via preferred channels
4. **Revenue Tracking**: Quantifies value protected from scope creep
5. **Trial Mode**: 7-day free trial with full Pro features
6. **Production-Ready**: Grade A+ code quality, 98.9% test coverage

---

## 2. Core Features & Capabilities

### AI Scope Creep Detection
- **Technology**: Google Gemini API with structured prompt engineering
- **Analysis**: Compares client messages against original project scope
- **Accuracy**: Identifies out-of-scope requests with context awareness
- **Speed**: Real-time analysis (< 2 seconds per communication)
- **Security**: Input sanitization prevents prompt injection attacks

### Project Management
- **Unlimited Projects** (Pro tier) or 3 projects (Starter tier)
- **Project Details**: Name, scope, deliverables, deadlines, budget
- **Client Tracking**: Unlimited clients per project (Pro) or 5 (Starter)
- **Communication Logs**: Complete history of analyzed messages
- **Scope Alerts**: Flagged communications with AI reasoning

### Multi-Channel Monitoring
**Supported Platforms**:
1. **Email**: IMAP/SMTP integration
2. **Slack**: Workspace integration via webhooks
3. **Discord**: Server webhooks
4. **Telegram**: Bot API integration
5. **SMS**: Twilio integration
6. **WhatsApp**: WhatsApp Business API
7. **Manual Entry**: Paste any communication for analysis

### Real-Time Alerts
**Notification Channels** (7 integrations):
1. **Discord**: Webhook notifications with rich embeds
2. **Slack**: Channel messages with formatting
3. **Telegram**: Bot messages with inline buttons
4. **Email**: Rich HTML via Resend API
5. **SMS**: Text alerts via Twilio
6. **Zapier**: Connect to 5,000+ apps
7. **WhatsApp**: WhatsApp Business API messages

**Alert Contents**:
- Client name and project
- Communication excerpt
- AI analysis of scope creep
- Recommended actions
- Billable hours estimate

### Revenue Analytics
**Dashboards**:
- Total revenue protected
- Billable hours saved
- Scope creep trends over time
- Client breakdown by alerts
- Project profitability metrics

**Time Tracking**:
- Log billable hours
- Track project budgets
- Monitor time spent vs. estimated
- Calculate project profitability

### Client Management
- **Client Profiles**: Contact info, company, communication preferences
- **Activity History**: Complete communication logs per client
- **Alert Patterns**: Identify problematic clients
- **Notes**: Internal notes on client interactions

### Interactive Onboarding (October 2025)
- **4-Step Checklist**: Guided setup flow
- **Auto-Detection**: Tracks completion automatically
- **Cross-Tab Sync**: Progress synced across browser tabs
- **Celebration Animation**: Completion rewards
- **Collapsible UI**: Saves screen space after completion
- **Expected Impact**: +40% activation rate (60% → 84%)

### Mobile-Optimized UX (October 2025)
- **Scrollable Tabs**: Visual indicators with gradient fades
- **Arrow Navigation**: Easy scrolling on mobile
- **Responsive Design**: Optimized for all screen sizes
- **Touch-Friendly**: Large tap targets, swipe gestures
- **Expected Impact**: +90% mobile discoverability

---

## 3. Pricing & Subscription Tiers

### Starter Tier - $9/month or $90/year (save 17%)
**Perfect for individual freelancers**
- 3 active projects
- 5 clients per project
- 50 communications analyzed per month
- All 7 notification integrations
- 7-day activity retention
- Email support
- Full AI scope detection
- Revenue analytics dashboard

### Pro Tier - $29/month or $290/year (save 17%)
**For consultants and small agencies**
- Unlimited projects
- Unlimited clients per project
- Unlimited communications analyzed
- All 7 notification integrations
- 30-day activity retention
- Priority email support
- Advanced analytics
- API access (coming soon)

### Trial Mode
- 7-day free trial (no credit card required)
- Full Pro tier features during trial
- Automatic downgrade to Starter after trial
- Can upgrade to Pro anytime during or after trial

### Admin Access
- Free lifetime Starter tier access
- Configured via `ADMIN_EMAILS` environment variable
- No Stripe subscription required
- Perfect for team members, beta testers

### Payment Processing
- **Provider**: Stripe (PCI DSS Level 1 certified)
- **Methods**: Credit card, debit card
- **Billing**: Monthly or annual
- **Currency**: USD
- **Refunds**: 30-day money-back guarantee

---

## 4. Technical Architecture

### Frontend Stack
**Framework**: React 18.3.1 with TypeScript 5.5
- **Build Tool**: Vite 7.1 (ESM-native, lightning fast)
- **UI Library**: shadcn/ui (Radix UI primitives + Tailwind)
- **Styling**: Tailwind CSS 3.4 with custom design system
- **State Management**: React Query (TanStack Query v5)
- **Routing**: React Router 7 with future flags
- **Forms**: React Hook Form + Zod validation
- **Date Handling**: date-fns (tree-shakeable)
- **Icons**: Lucide React (optimized SVGs)

**Key Libraries**:
```json
{
  "@tanstack/react-query": "^5.59.16",
  "@tanstack/react-router": "^1.77.0",
  "react": "^18.3.1",
  "react-dom": "^18.3.1",
  "tailwindcss": "^3.4.1",
  "zod": "^3.23.8"
}
```

### Backend Stack
**Platform**: Supabase (Postgres + Edge Functions)
- **Database**: PostgreSQL 15 with Row Level Security (RLS)
- **Edge Functions**: Deno runtime (TypeScript, V8 isolates)
- **Authentication**: Supabase Auth (JWT-based)
- **Storage**: Supabase Storage (S3-compatible)
- **Real-time**: Supabase Realtime (WebSocket subscriptions)

**Database Features**:
- 12 optimized indexes for performance
- Row Level Security on all tables
- Soft deletes with retention policies
- Database functions for complex logic
- Triggers for automated workflows

### AI & Integrations
**AI Engine**: Google Gemini API
- Model: Gemini 1.5 Flash (fast, cost-effective)
- Prompt Engineering: Structured system prompts
- Input Sanitization: Multi-layer security
- Rate Limiting: 10 requests/minute per user

**Payment Processing**: Stripe
- Subscription management
- Webhook handling for events
- Customer portal integration
- PCI DSS compliant

**Notifications**:
- Resend (Email): HTML templates, tracking
- Twilio (SMS): Global delivery
- Discord, Slack, Telegram: Webhooks
- Zapier: 5,000+ app integrations
- WhatsApp Business API: Rich messages

### Infrastructure
**Hosting**: Vercel (Serverless, Edge Network)
- Auto-deploy from GitHub main branch
- Edge functions globally distributed
- Automatic HTTPS with custom domain
- Preview deployments for PRs

**Database**: Supabase Cloud
- Multi-region PostgreSQL
- Automatic backups (daily)
- Point-in-time recovery
- SOC 2 Type II certified

**Monitoring**:
- Sentry (Error tracking - frontend + backend)
- Upstash Redis (Rate limiting, distributed)
- Vercel Analytics (Performance monitoring)
- Custom health check endpoints

---

## 5. Security & Compliance

### Security Grade: A+ (100/100) ✅

### Authentication & Authorization
- **Auth Provider**: Supabase Auth (JWT tokens)
- **Session Management**: Secure cookies with httpOnly
- **Password Policy**: Minimum 8 characters, complexity required
- **Email Verification**: Required for signup
- **Password Reset**: Secure token-based flow

### Row Level Security (RLS)
**Complete RLS Coverage on All Tables**:
- Users can only access their own data
- Project ownership verification
- Client association checks
- Communication authorization
- Alert access control

**Example Policy**:
```sql
CREATE POLICY "Users can view own projects"
ON projects FOR SELECT
USING (user_id = auth.uid());
```

### Input Sanitization
**Multi-Layer Defense**:
1. **Client-Side**: Pre-flight validation, HTML escaping
2. **Server-Side**: Comprehensive filtering, pattern blocking
3. **Prompt Injection Protection**: Removes attack patterns
4. **Length Validation**: Max 10,000 chars per communication
5. **Suspicious Activity Logging**: Tracks attack attempts

**Blocked Attack Patterns**:
- "Ignore previous instructions"
- "System: you are now..."
- "[INST] reveal secrets"
- Control characters, zero-width Unicode
- Excessive special character sequences

**Implementation**: `supabase/functions/_shared/sanitization.ts`
**Test Coverage**: 38 dedicated security tests (100% coverage)

### Rate Limiting
**Infrastructure**: Upstash Redis (distributed)
**Limits by Endpoint**:
- AI Detection: 10 requests/minute
- Email Notifications: 5 requests/minute
- SMS: 3 requests/minute
- Webhooks: 10 requests/minute
- Subscription Checks: 20 requests/minute
- Payment Operations: 5 requests/minute

**Graceful Degradation**: If Redis unavailable, allows requests with warning

### Data Protection
**Encryption**:
- At rest: AES-256 (Supabase default)
- In transit: TLS 1.3 (enforced)
- Database connections: SSL required

**PII Handling**:
- Zero PII in production logs
- Database-level token masking
- Secure environment variable storage
- No sensitive data in error messages

**Soft Deletes**:
- 7-day retention (Starter tier)
- 30-day retention (Pro tier)
- Permanent deletion after retention period
- User-initiated hard delete available

### Compliance
**GDPR (EU)**:
- Right to access (user data export)
- Right to erasure (account deletion)
- Data portability (JSON export)
- Breach notification (<72 hours)
- Privacy by design

**CCPA (California)**:
- Data disclosure requirements
- Opt-out of data sales (N/A - we don't sell data)
- Data deletion rights
- Non-discrimination policy

**SOC 2 Type II**:
- Infrastructure: Supabase (certified)
- Payment Processing: Stripe (certified)
- Application: Security controls documented

### Security Testing
**Test Coverage**: 1,230 tests passing (98.9%)
- 38 dedicated security tests
- 100% coverage on sanitization functions
- SQL injection prevention tests
- XSS prevention tests
- CSRF protection tests

### Security Monitoring
**Sentry Integration**:
- Frontend error tracking
- Edge Function monitoring
- Performance monitoring
- Release tracking
- User feedback integration

**Logging Standards**:
- Structured logging (JSON format)
- No console.* in production code
- Error severity levels
- Request correlation IDs
- Performance metrics

---

## 6. Integrations & Notifications

### Discord Integration
**Setup**: Webhook URL from Discord server settings
**Features**:
- Rich embed messages
- Color-coded alerts (red for scope creep)
- Clickable links to project
- Avatar and username customization
**Rate Limit**: 10 requests/minute
**Security**: URL validation, timeout handling (10s)

### Slack Integration
**Setup**: Incoming webhook URL
**Features**:
- Formatted messages with sections
- Emoji indicators
- Thread support
- Mention support
**Rate Limit**: 10 requests/minute
**Security**: HTTPS required, payload validation

### Telegram Integration
**Setup**: Bot token + chat ID
**Features**:
- Rich text formatting (Markdown)
- Inline buttons (coming soon)
- Group chat support
- File attachments
**Rate Limit**: 10 requests/minute
**Security**: Bot API token encryption

### Email Integration (Resend)
**Setup**: Automatic (uses RESEND_API_KEY)
**Features**:
- HTML email templates
- Plain text fallback
- Tracking (opens, clicks)
- Delivery reports
**Rate Limit**: 5 requests/minute
**Security**: DKIM, SPF, DMARC configured

### SMS Integration (Twilio)
**Setup**: Account SID + Auth Token
**Features**:
- Global SMS delivery
- Delivery receipts
- Short URLs for links
- Unicode support
**Rate Limit**: 3 requests/minute
**Security**: Token encryption, number validation

### Zapier Integration
**Setup**: Webhook URL from Zap
**Features**:
- Connect to 5,000+ apps
- Multi-step workflows
- Conditional logic
- Data transformation
**Rate Limit**: 10 requests/minute
**Security**: HTTPS only, payload signing

### WhatsApp Business API
**Setup**: Complex (see WHATSAPP_SETUP_GUIDE.md)
**Requirements**:
- WhatsApp Business Account
- Meta Business verification
- Phone number registration
**Features**:
- Rich media messages
- Template messages
- Interactive buttons
- Read receipts
**Rate Limit**: 10 requests/minute
**Security**: End-to-end encryption, webhook verification

### Integration Security
**Common Security Measures**:
- Webhook URL validation
- Timeout handling (10 seconds)
- Retry logic with exponential backoff
- Error logging to Sentry
- Rate limiting (Upstash Redis)
- CORS validation (strict origin checking)
- Input sanitization

**Documentation**: See `docs/guides/INTEGRATION_SECURITY.md`

---

## 7. User Journey & Onboarding

### Signup Flow
1. Visit https://ersilia.ai
2. Click "Get Started" or "Start Free Trial"
3. Enter email + password (min 8 chars)
4. Verify email (check inbox for link)
5. Redirected to dashboard with onboarding checklist

### Onboarding Checklist (4 Steps)
**Step 1: Create Your First Project**
- Click "New Project" button
- Fill in project details (name, scope, deliverables)
- Set deadline and budget
- Auto-detected upon project creation

**Step 2: Add a Client**
- Click "Add Client" in project view
- Enter client name, email, company
- Set communication preferences
- Auto-detected upon client creation

**Step 3: Log Your First Communication**
- Click "Add Communication" in project
- Paste client message (email, Slack, etc.)
- AI analyzes against scope
- Auto-detected upon communication creation

**Step 4: Connect a Notification Channel**
- Visit Integrations tab
- Choose Discord, Slack, or Email
- Enter webhook URL or credentials
- Test notification to verify
- Auto-detected upon integration connection

**Completion Celebration**:
- Confetti animation
- Success message
- Checklist collapses to save space
- Can be dismissed permanently

**Cross-Tab Sync**:
- Progress tracked in localStorage
- Storage events sync across tabs
- Real-time updates across devices

### First Alert Experience
1. User logs communication with out-of-scope request
2. AI analyzes and detects scope creep
3. Alert created in database
4. Notification sent via configured channels
5. User receives real-time notification
6. Dashboard shows new alert with AI reasoning
7. User can approve/reject or discuss with client

### Trial to Paid Conversion
**Day 1-7 (Trial)**:
- Full Pro features available
- No credit card required
- Gentle reminders about trial ending

**Day 7 (Trial Ends)**:
- Auto-downgrade to Starter tier
- Notification of tier change
- Prompt to upgrade to Pro
- No data loss, features restricted

**Upgrade Flow**:
1. Click "Upgrade to Pro" button
2. Redirected to Stripe Checkout
3. Enter payment details
4. Subscription created
5. Webhook updates user tier
6. Instant access to Pro features

---

## 8. Development & Deployment

### Local Development Setup
```bash
# Clone repository
git clone https://github.com/yourusername/ersilia.git
cd ersilia

# Install dependencies
npm install

# Start dev server
npm run dev
# App opens at http://localhost:8080

# Environment variables (.env)
VITE_SUPABASE_URL=https://btehobdaisrfchyrwssk.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-key
```

### Build & Quality Checks
```bash
# Production build (includes lint check)
npm run build

# TypeScript compilation check
npx tsc --noEmit

# ESLint (zero tolerance for warnings)
npm run lint:check

# Unit tests
npm run test

# E2E tests
npx playwright test

# Performance tests
npm run perf:smoke
npm run perf:load
npm run perf:stress
```

### Database Migrations
```bash
# Check migration status
npx supabase migration list --project-ref btehobdaisrfchyrwssk

# Apply pending migrations
npx supabase db push --project-ref btehobdaisrfchyrwssk

# Create new migration
npx supabase migration new my_migration_name
```

### Edge Functions Deployment
```bash
# Deploy all functions
npx supabase functions deploy --project-ref btehobdaisrfchyrwssk

# Deploy specific function
npx supabase functions deploy detect-scope-creep --project-ref btehobdaisrfchyrwssk

# View function logs
npx supabase functions logs detect-scope-creep --project-ref btehobdaisrfchyrwssk
```

### Production Deployment (Vercel)
**Automatic Deployment**:
1. Push to `main` branch
2. Vercel detects changes
3. Runs build with lint check
4. Deploys to production
5. Updates https://ersilia.ai

**Environment Variables** (Vercel Dashboard):
```bash
# Required
VITE_SUPABASE_URL
VITE_SUPABASE_PUBLISHABLE_KEY
GEMINI_API_KEY
RESEND_API_KEY
STRIPE_SECRET_KEY
ADMIN_EMAILS

# Monitoring
VITE_SENTRY_DSN
SENTRY_DSN
UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN

# Optional
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
VITE_GA_MEASUREMENT_ID
```

### Rollback Procedure
1. Visit Vercel Dashboard
2. Navigate to Deployments
3. Find previous stable deployment
4. Click "Promote to Production"
5. Confirm rollback
**Recovery Time**: 30-60 seconds

### Health Check Endpoints
**Frontend**: `https://ersilia.ai/health`
- Status: healthy | degraded
- Timestamp
- Response time
- App version

**Backend**: `https://btehobdaisrfchyrwssk.supabase.co/functions/v1/health-check`
- Database connectivity
- Stripe API health
- Gemini API health
- Overall status: healthy | degraded | unhealthy

---

## 9. Testing & Quality Assurance

### Test Coverage Summary
**Total**: 1,230 tests passing (98.9% pass rate)
- **Unit Tests**: 1,223 passing (Vitest + React Testing Library)
- **E2E Tests**: 7 passing (Playwright - complete user journey)
- **Skipped**: 14 tests (intentionally disabled)

### Unit Test Breakdown
**Framework**: Vitest + React Testing Library
**Coverage Areas**:
- React components (hooks, state, props)
- Utility functions (sanitization, error handling)
- Form validation (Zod schemas)
- API integrations (mocked)
- Context providers (SubscriptionContext)
- Security functions (100% coverage)

**Key Test Suites**:
- `sanitization.test.ts`: 38 tests (prompt injection prevention)
- `error-utils.test.ts`: 12 tests (error handling)
- `subscription-context.test.tsx`: 15 tests (payment flows)
- Component tests: 850+ tests

**Run Commands**:
```bash
npm run test              # Run all unit tests
npm run test:coverage     # Coverage report
npm run test:ui           # Interactive UI
npm run test:watch        # Watch mode
```

### E2E Test Journey (7 Steps)
**Framework**: Playwright
**Test User**: `e2e-test@ersilia.ai`

**Complete User Journey**:
1. **Authentication**: Sign up, verify email, login
2. **Project Creation**: Create project with scope details
3. **Client Management**: Add client to project
4. **Communication Analysis**: Log client message, AI detects scope creep
5. **Alert Verification**: Confirm alert created with AI reasoning
6. **Notification Setup**: Configure Discord integration
7. **End-to-End Flow**: Verify notification sent successfully

**Run Commands**:
```bash
npx playwright test                  # Run E2E tests
npx playwright test --headed         # Watch tests run
npx playwright show-report           # View HTML report
npx playwright test --debug          # Debug mode
```

**Test Data Cleanup** (Required):
```sql
-- Run in Supabase SQL Editor before tests
DELETE FROM projects
WHERE user_id = (SELECT id FROM auth.users WHERE email = 'e2e-test@ersilia.ai');
```

### Performance Testing (k6)
**Framework**: k6 by Grafana Labs

**Test Types**:
1. **Smoke Test** (30s, 1 VU):
   - Quick health check
   - Pre-deployment validation
   - Threshold: p95 < 1s, error < 1%

2. **Load Test** (40s, 5-10 VUs):
   - Normal traffic simulation
   - Weekly performance baseline
   - Threshold: p95 < 2s, error < 1%

3. **Stress Test** (8min, up to 100 VUs):
   - Find breaking points
   - Capacity planning
   - Threshold: p95 < 3s, error < 5%

**Run Commands**:
```bash
npm run perf:smoke        # Quick validation (30s)
npm run perf:load         # Load test (40s)
npm run perf:stress       # Stress test (8min)
npm run perf:all          # Smoke + Load

# Custom environment
BASE_URL=https://staging.ersilia.ai npm run perf:smoke
```

**CI/CD Integration**:
- Runs after production deployments
- Tests critical paths (homepage, auth, pricing, assets)
- Fails deployment if performance degrades
- Stores results as artifacts (30-day retention)

### Code Quality Standards
**ESLint Configuration**:
- Zero tolerance: `--max-warnings 0`
- `no-console` rule enforced (use `log.*` instead)
- Build fails on any lint errors
- TypeScript strict mode enabled

**Build Pipeline**:
```json
{
  "scripts": {
    "build": "npm run lint:check && vite build",
    "lint:check": "eslint . --max-warnings 0"
  }
}
```

### Security Testing
**Dedicated Security Tests**: 38 tests
- Prompt injection prevention
- XSS prevention
- SQL injection prevention (database functions)
- CSRF protection
- Input validation
- Authorization checks

**Coverage**: 100% on security-critical code

---

## 10. Performance & Optimization

### Bundle Optimization
**Code Splitting Strategy**:
- All route components lazy loaded
- Automatic preloading on hover
- Critical routes preloaded on mount
- Manual chunking for vendor code

**Bundle Sizes** (gzipped):
- Initial bundle: ~147 KB (46.6 KB gzipped)
- React vendor: 160 KB (52.4 KB gzipped)
- Supabase API: 181 KB (47.8 KB gzipped)
- Route chunks: 2-22 KB each (lazy loaded)

**Performance Impact**:
- 30% faster initial load vs. monolithic bundle
- Seamless navigation with hover preloading
- Reduced bandwidth for mobile users

### Database Optimization
**12 Optimized Indexes**:
- `projects(user_id)` - User ownership queries
- `clients(project_id)` - Project associations
- `communications(project_id)` - Communication logs
- `scope_alerts(project_id)` - Alert queries
- `time_entries(user_id)` - Time tracking
- Composite indexes on frequently queried columns

**Query Optimization**:
- Explicit column selection (no `SELECT *`)
- JOIN optimization for related data
- LIMIT clauses on paginated queries
- Database functions for complex logic

**Connection Pooling**:
- Supabase Pooler (PgBouncer)
- Max 100 concurrent connections
- Transaction mode for Edge Functions

### Chunk Loading Error Recovery
**Problem**: After deployments, old chunks may 404
**Solution**: Automatic detection and recovery

**Implementation**:
1. ErrorBoundary detects chunk loading errors
2. Checks if error is from lazy import
3. Waits 10-second cooldown (prevents infinite loops)
4. Reloads page to fetch latest chunks
5. User sees seamless recovery

**Files**:
- `src/lib/chunk-reload-handler.ts`
- `src/components/ErrorBoundary.tsx`

**Documentation**: See `docs/guides/CHUNK_LOADING_SCENARIOS.md`

### Caching Strategy
**React Query Configuration**:
- Default stale time: 5 minutes
- Cache time: 30 minutes
- Automatic background refetching
- Optimistic updates for mutations

**Browser Caching**:
- Static assets: 1 year (immutable)
- HTML: No cache (always fresh)
- API responses: Controlled by backend

### Real-Time Subscriptions
**Supabase Realtime**:
- WebSocket connections for live updates
- Subscribe to project/client changes
- Automatic reconnection on disconnect
- Efficient filtering (RLS applied)

**Use Cases**:
- Live alert notifications
- Collaborative project editing (future)
- Real-time analytics updates

---

## 11. API Reference

### Edge Functions (Supabase)

#### detect-scope-creep
**Endpoint**: `POST /functions/v1/detect-scope-creep`
**Purpose**: Analyze communication for scope creep
**Authentication**: Required (JWT)
**Rate Limit**: 10 requests/minute

**Request Body**:
```json
{
  "communication": "Client message text (max 10,000 chars)",
  "projectScope": "Original project scope",
  "projectId": "uuid"
}
```

**Response**:
```json
{
  "isScopeCreep": true,
  "confidence": 0.85,
  "reasoning": "AI explanation of why this is scope creep",
  "suggestedAction": "Contact client to discuss additional work"
}
```

**Error Responses**:
- 400: Invalid input (failed sanitization)
- 401: Unauthorized
- 429: Rate limit exceeded
- 500: Server error

#### notify-scope-alert
**Endpoint**: `POST /functions/v1/notify-scope-alert`
**Purpose**: Send notifications via configured channels
**Authentication**: System (database trigger)
**Rate Limit**: 10 requests/minute

**Triggered By**: New scope alert creation
**Sends To**: All configured integrations for user
**Includes**: Alert details, project context, recommended actions

#### check-subscription
**Endpoint**: `GET /functions/v1/check-subscription`
**Purpose**: Verify user subscription tier and limits
**Authentication**: Required (JWT)
**Rate Limit**: 20 requests/minute

**Response**:
```json
{
  "tier": "pro",
  "status": "active",
  "limits": {
    "projects": -1,
    "clients_per_project": -1,
    "communications_per_month": -1
  },
  "usage": {
    "projects": 5,
    "communications_this_month": 142
  }
}
```

#### stripe-webhook
**Endpoint**: `POST /functions/v1/stripe-webhook`
**Purpose**: Handle Stripe subscription events
**Authentication**: Stripe signature verification
**Rate Limit**: 100 requests/minute

**Events Handled**:
- `checkout.session.completed`: Create subscription
- `customer.subscription.updated`: Update tier/status
- `customer.subscription.deleted`: Cancel subscription

### Database Functions

#### get_user_tier_name(user_id)
**Purpose**: Get subscription tier name for user
**Returns**: 'starter' | 'pro' | 'trial'

#### can_user_create_project(user_id)
**Purpose**: Check if user can create more projects
**Returns**: boolean

#### get_user_communication_count(user_id, period)
**Purpose**: Count communications in billing period
**Returns**: integer

---

## 12. Database Schema

### Core Tables

#### users
**Managed by**: Supabase Auth
**Key Fields**:
- `id` (uuid, PK): User ID
- `email` (text): User email
- `created_at` (timestamp): Signup date

#### subscriptions
**Purpose**: Track user subscription tiers
**Fields**:
- `id` (uuid, PK): Subscription ID
- `user_id` (uuid, FK): References users
- `tier` (text): 'starter' | 'pro' | 'trial'
- `status` (text): 'active' | 'canceled' | 'expired'
- `stripe_customer_id` (text): Stripe customer ID
- `stripe_subscription_id` (text): Stripe subscription ID
- `trial_ends_at` (timestamp): Trial expiration
- `current_period_start` (timestamp): Billing period start
- `current_period_end` (timestamp): Billing period end
- `created_at` (timestamp): Record creation
- `updated_at` (timestamp): Last update

**Indexes**:
- `user_id` (unique)
- `stripe_customer_id`
- `stripe_subscription_id`

#### projects
**Purpose**: Store project details
**Fields**:
- `id` (uuid, PK): Project ID
- `user_id` (uuid, FK): Owner
- `name` (text): Project name
- `original_scope` (text): Scope description
- `deliverables` (text[]): List of deliverables
- `deadline` (date): Project deadline
- `budget` (numeric): Budget amount
- `is_active` (boolean): Active flag
- `deleted_at` (timestamp): Soft delete
- `created_at` (timestamp): Creation date
- `updated_at` (timestamp): Last update

**Indexes**:
- `user_id`
- `is_active`
- `deleted_at`

#### clients
**Purpose**: Store client information
**Fields**:
- `id` (uuid, PK): Client ID
- `project_id` (uuid, FK): Associated project
- `name` (text): Client name
- `email` (text): Client email
- `company` (text): Company name
- `phone` (text): Phone number
- `deleted_at` (timestamp): Soft delete
- `created_at` (timestamp): Creation date
- `updated_at` (timestamp): Last update

**Indexes**:
- `project_id`
- `email`
- `deleted_at`

#### communications
**Purpose**: Log client communications
**Fields**:
- `id` (uuid, PK): Communication ID
- `project_id` (uuid, FK): Associated project
- `client_id` (uuid, FK): Associated client
- `content` (text): Message content
- `channel` (text): Communication channel
- `analyzed` (boolean): AI analysis complete
- `deleted_at` (timestamp): Soft delete
- `created_at` (timestamp): Message date

**Indexes**:
- `project_id`
- `client_id`
- `analyzed`
- `created_at`
- `deleted_at`

#### scope_alerts
**Purpose**: Store scope creep alerts
**Fields**:
- `id` (uuid, PK): Alert ID
- `project_id` (uuid, FK): Associated project
- `communication_id` (uuid, FK): Triggering message
- `is_scope_creep` (boolean): AI determination
- `confidence` (numeric): Confidence score (0-1)
- `reasoning` (text): AI explanation
- `suggested_action` (text): Recommended next steps
- `status` (text): 'new' | 'reviewed' | 'resolved'
- `deleted_at` (timestamp): Soft delete
- `created_at` (timestamp): Alert date

**Indexes**:
- `project_id`
- `communication_id`
- `status`
- `created_at`
- `deleted_at`

#### integrations
**Purpose**: Store notification channel configurations
**Fields**:
- `id` (uuid, PK): Integration ID
- `user_id` (uuid, FK): Owner
- `type` (text): 'discord' | 'slack' | 'telegram' | ...
- `config` (jsonb): Channel-specific configuration
- `is_active` (boolean): Active flag
- `created_at` (timestamp): Setup date
- `updated_at` (timestamp): Last update

**Indexes**:
- `user_id`
- `type`
- `is_active`

### Security Policies (RLS)

All tables have Row Level Security enabled with policies:
- `SELECT`: Users can view their own data
- `INSERT`: Users can create their own data
- `UPDATE`: Users can update their own data
- `DELETE`: Users can delete their own data (soft delete)

**Example Policy**:
```sql
CREATE POLICY "Users can view own projects"
ON projects FOR SELECT
USING (user_id = auth.uid());
```

---

## 13. Environment Configuration

### Frontend Variables (.env)
```bash
# Supabase Configuration
VITE_SUPABASE_URL=https://btehobdaisrfchyrwssk.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-key

# Optional Monitoring
VITE_SENTRY_DSN=your-sentry-dsn
VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX
```

### Backend Variables (Supabase Vault)
```bash
# Required
GEMINI_API_KEY=your-gemini-api-key         # Google AI Studio
RESEND_API_KEY=your-resend-api-key         # Email service
STRIPE_SECRET_KEY=sk_live_xxx              # Stripe payments
STRIPE_WEBHOOK_SECRET=whsec_xxx            # Stripe webhooks
ADMIN_EMAILS=email1@gmail.com,email2@...   # Admin users

# Monitoring (Recommended)
SENTRY_DSN=your-sentry-dsn                 # Edge Function errors
UPSTASH_REDIS_REST_URL=your-redis-url      # Rate limiting
UPSTASH_REDIS_REST_TOKEN=your-redis-token  # Rate limiting

# Optional
TWILIO_ACCOUNT_SID=your-twilio-sid         # SMS
TWILIO_AUTH_TOKEN=your-twilio-token        # SMS
ENVIRONMENT=production                      # CORS config
```

### Setting Secrets
```bash
# Via Supabase CLI
npx supabase secrets set GEMINI_API_KEY="your-key" --project-ref btehobdaisrfchyrwssk
npx supabase secrets set RESEND_API_KEY="your-key" --project-ref btehobdaisrfchyrwssk

# View current secrets (values hidden)
npx supabase secrets list --project-ref btehobdaisrfchyrwssk
```

---

## 14. Monitoring & Observability

### Error Tracking (Sentry)
**Frontend Integration**:
- React error boundary
- Unhandled promise rejections
- Network errors
- User feedback widget

**Backend Integration**:
- Edge Function errors
- Database connection errors
- External API failures
- Performance monitoring

**Configuration**:
```typescript
Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: 'production',
  tracesSampleRate: 0.1,
  beforeSend: (event) => {
    // Sanitize PII before sending
    return sanitizeEvent(event);
  }
});
```

### Structured Logging
**Standards**:
- No `console.*` in production code
- Use `log.*` from `src/lib/logger.ts`
- JSON format for parsing
- Severity levels: error, warn, info, debug

**Example**:
```typescript
import { log } from '@/lib/logger';

log.error('Failed to detect scope creep', error, {
  component: 'ScopeDetectionService',
  projectId: project.id,
  userId: user.id
});
```

### Performance Monitoring
**Metrics Tracked**:
- Page load times
- API response times
- Database query duration
- Edge Function cold starts
- Network latency

**Tools**:
- Vercel Analytics (frontend)
- Supabase Dashboard (database)
- Sentry Performance (end-to-end)

### Health Checks
**Frontend** (`/health`):
- Response time < 100ms
- Returns: status, timestamp, version

**Backend** (`/functions/v1/health-check`):
- Database connectivity
- Stripe API availability
- Gemini API availability
- Overall status determination

**Monitoring Integration**:
- UptimeRobot: Ping every 5 minutes
- Alerts: Email + Slack on downtime
- SLA Target: 99.9% uptime

---

## 15. Support & Resources

### Getting Help
**Email Support**: support@ersilia.ai
- Response time: 24 hours (Starter), 12 hours (Pro)
- Include: account email, project ID, error screenshots

**Documentation**:
- Developer Guide: `CLAUDE.md`
- Security Docs: `SECURITY.md`
- Integration Setup: `docs/guides/`
- API Reference: This document

**Community** (Coming Soon):
- Discord server for users
- GitHub Discussions for feature requests
- Roadmap transparency

### Status Page
**URL**: https://status.ersilia.ai (coming soon)
**Features**:
- Real-time service status
- Incident history
- Planned maintenance announcements
- Subscribe to updates

### Documentation Links
**Core Documentation**:
- Main README: `README.md`
- Security: `SECURITY.md`
- Project History: `docs/guides/PROJECT_HISTORY.md`
- Integration Security: `docs/guides/INTEGRATION_SECURITY.md`

**Technical Audits**:
- Senior Code Review: `docs/audits/technical/SENIOR_CODE_REVIEW_2025.md`
- Comprehensive Review: `docs/audits/technical/COMPREHENSIVE_CODE_REVIEW_2025_10_19.md`
- UX Review: `docs/audits/technical/COMPREHENSIVE_UX_REVIEW_2025_10_23.md`
- Color System: `docs/audits/technical/COLOR_SYSTEM_REVIEW_2025_10_23.md`

**Business & Strategy**:
- Business Model: `docs/audits/business/`
- Brand Guidelines: `docs/audits/business/`
- Launch Strategy: `docs/audits/business/`

### Feature Requests
**Process**:
1. Check existing requests in GitHub Issues
2. Create new issue with template
3. Vote on existing requests
4. Track progress on public roadmap

**Priority Criteria**:
- User impact (how many users benefit)
- Business value (revenue impact)
- Technical feasibility
- Strategic alignment

### Bug Reports
**Template**:
1. Expected behavior
2. Actual behavior
3. Steps to reproduce
4. Screenshots/videos
5. Browser/device info
6. Account email (for investigation)

**Response SLA**:
- Critical (service down): 1 hour
- High (major feature broken): 4 hours
- Medium (minor bug): 24 hours
- Low (cosmetic issue): 72 hours

---

## Appendix: Company Information

**Product Name**: Ersilia.ai
**Legal Entity**: Ersilia Technologies Inc. (Delaware C-Corp)
**Founded**: October 2025
**Headquarters**: San Francisco, CA, USA
**Website**: https://ersilia.ai
**Email**: hello@ersilia.ai
**Support**: support@ersilia.ai

**Social Media**:
- Twitter: @ersiliaai
- LinkedIn: /company/ersilia
- GitHub: /ersilia-ai

**Compliance**:
- SOC 2 Type II (in progress)
- GDPR compliant
- CCPA compliant
- PCI DSS (via Stripe)

**Technology Partners**:
- Supabase (Database & Auth)
- Vercel (Hosting)
- Stripe (Payments)
- Google Cloud (AI)
- Upstash (Redis)
- Sentry (Monitoring)

---

**Version**: 1.0
**Last Updated**: November 2025
**Next Review**: February 2026

For the latest updates, visit: https://ersilia.ai/docs