docs/architecture.md

# HELPDESK.AI - As-Built Architecture

## 1. System Overview
HELPDESK.AI is a multi-tenant SaaS ticketing platform driven by an AI processing pipeline to automate triage.

## 2. Component Architecture

### 2.1 Frontend (React + Vite)
- **Framework:** React 19 mapped through Vite.
- **State Management:** Zustand (`useAuthStore`, `useTicketStore`) with `zustand/middleware/persist` bound to `localStorage` (hardened against QuotaExceeded errors).
- **Styling:** TailwindCSS + Vanilla CSS for animations and layout.
- **Routing:** React Router DOM (v6+), facilitating public routes (`/`), protected user routes (`/dashboard`), and admin flows (`/master-admin`).

### 2.2 Backend (FastAPI + Python)
- **Framework:** FastAPI providing high-concurrency async endpoints.
- **Core Endpoints:**
  - `POST /ai/analyze_ticket`: Synchronous pipeline handling Text Classification (DistilBERT), NER, and Semantic Duplicate detection.
  - `POST /ai/log_correction`: Feedback loop endpoint for adversarial retraining.
- **Deployment:** Containerized and hosted on Hugging Face Spaces.

### 2.3 AI Inference Pipeline (Hugging Face / PyTorch)
- **Categorization & Routing:** Fine-tuned `DistilBERT`.
- **Duplicate Detection:** `sentence-transformers/all-MiniLM-L6-v2` for cosine similarity on cached ticket embeddings.
- **Performance:** End-to-end inference executes in <400ms under standard load.

### 2.4 Database & Auth Layer (Supabase / PostgreSQL)
- **Auth:** Supabase Auth (Email/Password & Magic Links). User state synchronized instantly via metadata and asynchronously via `profiles` table.
- **Database:** PostgreSQL.
  - Table: `profiles` (User RBAC and metadata)
  - Table: `tickets` (Core ticket data with JSONB for AI metadata)
- **Row Level Security (RLS):** Strict RLS policies ensure Company Admins only see their tenant's data, and users only see their own tickets.

## 3. Storage and Scaling Strategy
- **Client-Side:** Critical UI state cached in `localStorage` via Zustand persist. Direct `localStorage` access wrapped in `try-catch` blocks for adversarial resilience.
- **API Rate Limiting:** Expected at the API Gateway level (or via Hugging Face limits).

## 4. Production Hardening (BMAD Phase 1 & 2)
As part of the BMAD End-Game:
- **SEO & Metadata:** Implemented OpenGraph, Twitter Cards, and canonical meta boundaries in `index.html`.
- **Browser Storage Hardening:** Error boundaries established defensively against JSON Parse failures and Quota Limit Exceeded exceptions on clients.
- **Retrospective Log:** Documented in project artifacts repository.