urn translated; }

**Architecture Rationale:** 
- Using the service-role client for cache reads/writes bypasses RLS overhead during high-throughput operations.
- `upsert` with `onConflict` prevents race conditions when concurrent requests hit the same cache key.
- System prompt explicitly instructs tone preservation, which traditional engines consistently drop.

### 3. Atomic Safety Pipeline
Scam detection must occur before message persistence. Implement the pipeline as a Supabase RPC or server-side mutation that runs checks synchronously. This ensures flagged content never enters the primary messages table.

```typescript
export async function runSafetyPipeline(messageBody: string): Promise<{ status: 'allow' | 'flag' | 'block'; reasons: string[] }> {
  const reasons: string[] = [];
  
  // Financial/crypto pattern detection
  const financialRegex = /\b(?:IBAN|SWIFT|BTC|ETH|USDT|0x[a-fA-F0-9]{40})\b/;
  if (financialRegex.test(messageBody)) reasons.push('financial_reference');

  // Contact handle extraction
  const contactRegex = /(?:@?\w{3,}\s*[\.:]?\s*(?:telegram|whatsapp|signal|discord)|\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i;
  if (contactRegex.test(messageBody)) reasons.push('external_contact');

  // LLM toxicity assessment
  const toxicityCheck = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 64,
    system: 'Rate the toxicity/scam likelihood of this message from 0 to 10. Return only the number.',
    messages: [{ role: 'user', content: messageBody }],
  });

  const score = parseInt(toxicityCheck.content[0].type === 'text' ? toxicityCheck.content[0].text : '0', 10);
  if (score >= 8) reasons.push('high_toxicity');
  else if (score >= 5) reasons.push('moderate_toxicity');

  if (reasons.includes('high_toxicity') || reasons.includes('financial_reference')) {
    return { status: 'block', reasons };
  }
  if (reasons.length > 0) {
    return { status: 'flag', reasons };
  }
  return { status: 'allow', reasons: [] };
}

Architecture Rationale:

• Combining regex for deterministic patterns (crypto addresses, IBANs) with LLM scoring for contextual threats reduces false positives.
• Thresholds (≥8 block, ≥5 flag) are calibrated to minimize disruption while catching sophisticated social engineering.
• Flagged messages should automatically insert a row into a moderation_queue table for human review, creating an audit trail without blocking legitimate users prematurely.

4. Row-Level Security Hardening

RLS policies must account for token format variations. Legacy HS256 tokens sometimes return NULL for auth.uid() inside SQL contexts, even when the application layer recognizes the user. Always verify ownership in TypeScript before executing sensitive writes, and use service-role clients for cache operations that bypass RLS intentionally.

Pitfall Guide

Production Bundle

Action Checklist

• Implement content hashing with language directionality and body normalization
• Configure Supabase translation_registry table with composite unique constraint on cache key
• Set up server-side translation orchestration using Claude Sonnet with tone-preserving system prompts
• Build atomic safety pipeline combining regex pattern detection and LLM toxicity scoring
• Define moderation queue automation: flagged messages auto-insert into moderation_queue with reasons
• Harden RLS policies: add WITH CHECK clauses, verify ownership in TypeScript, use service-role for cache ops
• Implement opt-in translation toggle per conversation with user preference persistence
• Add risk-based sampling for toxicity checks to control LLM inference costs

Decision Matrix

Configuration Template

-- Supabase: translation_registry table
CREATE TABLE translation_registry (
  cache_key TEXT PRIMARY KEY,
  source_lang TEXT NOT NULL,
  target_lang TEXT NOT NULL,
  translated_body TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_tr_lang_pair ON translation_registry(source_lang, target_lang);

-- Supabase: moderation_queue table
CREATE TABLE moderation_queue (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  message_id UUID REFERENCES messages(id),
  reporter_id UUID REFERENCES auth.users(id),
  reasons TEXT[] NOT NULL,
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')),
  reviewed_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- RLS: translation_registry (read-only for clients, service-role for writes)
ALTER TABLE translation_registry ENABLE ROW LEVEL SECURITY;
CREATE POLICY "translation_cache_read" ON translation_registry FOR SELECT USING (true);
CREATE POLICY "translation_cache_write" ON translation_registry FOR INSERT/UPDATE USING (auth.jwt() ->> 'role' = 'service_role');

Quick Start Guide

1. Initialize the cache layer: Create the translation_registry table in Supabase. Add the composite index and RLS policies from the configuration template.
2. Deploy the orchestration service: Implement the resolveTranslation and runSafetyPipeline functions in a Next.js Route Handler or Server Action. Wire Anthropic Claude Sonnet with your API key.
3. Integrate with messaging flow: Intercept message sends on the client. Pass source/target languages and body to the server. Await full translation + safety verdict before persisting to the messages table.
4. Configure moderation routing: Set up a Supabase Edge Function or cron job to poll moderation_queue for pending status. Notify admin users via Web Push or email when new flags appear.
5. Validate with production traffic: Monitor cache hit rates, toxicity score distribution, and translation latency. Adjust regex patterns and LLM thresholds based on false positive/negative ratios. Deploy opt-in toggle to user settings.