UXGrounded: Technical Architecture

---

Multi-Provider AI Resilience

Context-Aware Analysis

Security-First Design

UXGrounded’s architecture provides a robust, scalable UX analysis platform with enterprise-grade security, real-time capabilities, and AI-powered insights enhanced by retrieval-augmented generation.

Below is a detailed breakdown of UGrounded’s complete technical architecture:

High-Level Component Interaction Flow

Frontend Architecture

Core Technology Stack

• React 18.3.1 with TypeScript as the primary frontend framework

• Vite as the build tool and development server

• Tailwind CSS with Shadcn/ui component library for styling

• React Router DOM 6.26.2 for client-side routing

• Framer Motion 12.18.1 for animations and transitions

State Management & Data Fetching

• TanStack React Query 5.56.2 for server state management, caching, and data synchronization

• React Context API for authentication state management

• React Hook Form 7.53.0 with Zod 3.23.8 for form validation

• @hookform/resolvers for form schema validation integration

UI Component Library

Complete Radix UI ecosystem including:

• Dialogs, Dropdowns, Tooltips, Accordions, Tabs

• Form controls (Input, Select, Checkbox, Radio)

• Navigation components (Menubar, Navigation Menu)

• Data visualization with Recharts 2.12.7

• Toast notifications via Sonner 1.5.0

Backend & Database Architecture

Supabase Integration

• Supabase JS Client 2.50.0 for database operations and authentication

• PostgreSQL database with Row-Level Security (RLS) policies

Database Schema

Core Tables:

1. projects - Project management

   • Fields: id, name, user_id, is_favourite, created_at

2. figma_files - Figma design imports

   • Fields: id, project_id, figma_url, figma_data (JSONB), status, ux_score, ux_score_breakdown, task_objective, strategic_context

3. reference_documents - RAG document storage

   • Fields: id, project_id, source_url, source_type, title, processing_status, chunk_count

4. document_chunks - Vector embeddings for RAG

   • Fields: id, document_id, chunk_text, embedding (vector), chunk_index

5. personas - AI-generated user personas

   • Fields: id, figma_file_id, name, title, summary, goals, frustrations, type

6. recommendations - UX recommendations

   • Fields: id, figma_file_id, summary, priority, status, action_items, screen_name, element_type, ux_principle_violated, industry_context

7. test_cases - Generated test scenarios

   • Fields: id, figma_file_id, title, description, test_type, pm_priority, pm_status

Database Functions:

• match_document_chunks() - Vector similarity search for RAG system using cosine similarity with 1536-dimension embeddings

Authentication & Security

Supabase Authentication

• Email/password authentication via Supabase Auth

• JWT token-based session management

• Automatic token refresh and persistence

• Protected routes with ProtectedRoute component

Security Features

• Row-Level Security (RLS) on all tables

• User-scoped data access (all records tied to user_id)

• CORS headers on all edge functions

• URL validation with SSRF protection in reference document uploads

• Authentication checks in all API endpoints

API Keys & Secrets Management

Configured Supabase secrets:

• OPENAI_API_KEY - OpenAI GPT models

• GROQ_API_KEY - Groq LLM models

• FIGMA_API_TOKEN - Figma API access

• SUPABASE_SERVICE_ROLE_KEY - Admin operations

AI & Machine Learning Architecture

Multi-Model AI System

Primary AI Providers:

1. OpenAI Integration

   • Models: gpt-4o-mini, gpt-4o

   • Used for: UX analysis, recommendations generation

   • Embeddings: text-embedding-3-small (1536 dimensions)

2. Groq Integration

   • High-speed inference with configurable models as primary provider

3. Fallback System: Groq → OpenAI → Synthetic data generation

RAG (Retrieval-Augmented Generation) System

• Document Processing Pipeline:

  • URL content extraction with Cheerio

  • Text chunking (1500 chars, 200 overlap)

  • OpenAI embedding generation

  • Vector storage in PostgreSQL with pgvector

• Context Retrieval:

  • Cosine similarity search (threshold: 0.7)

  • Project-scoped document search

  • Real-time context injection into AI prompts

Edge Functions Architecture

Supabase Edge Functions (Deno runtime)

1. figma-import

   • Figma API integration for design file import

   • Multi-agent AI analysis system

   • Generates personas, test cases, and recommendations

   • Deep traversal of Figma node tree for interactive element extraction

2. run-analysis

   • Automatically invokes enhance-recommendations after storing initial results

   • Comprehensive UX analysis engine

   • RAG-enhanced AI prompting

   • Multi-provider fallback system (Groq → OpenAI → Synthetic)

   • Structured JSON output with 7-dimension UX scoring

3. process-document

   • Creates vector embeddings that run-analysis queries via match_document_chunks()

   • Reference document processing pipeline

   • Web scraping with content extraction

   • Embedding generation and chunking

   • Vector database population

4. enhance-recommendations

   • Post-analysis recommendation enrichment

   • Adds screen mapping, element types, UX principles

   • Industry context integration

Error Handling & Reliability

• Retry logic with exponential backoff

• Timeout protection (30s-120s timeouts)

• Graceful degradation to synthetic data

• Comprehensive error logging

Real-time Features

Supabase Realtime

• Reference document status updates - Live processing status

• Analysis progress tracking - Real-time workflow updates

• Memory leak prevention - Proper subscription cleanup

• Channel management - Explicit unsubscribe and removal

Development & Deployment

Lovable Development Platform

• Live preview integration

• Hot reload development environment

• Automatic deployments for edge functions

• Git integration capabilities

Build System

• Vite with TypeScript compilation

• Tailwind CSS compilation

• ESLint code quality enforcement

• PostCSS processing

Key Technical Innovations

1. Automatic Function Chaining: run-analysis automatically triggers enhance-recommendations for seamless workflow

2. Context-Aware RAG: Document chunks are project-scoped and similarity-searched for relevant context injection

3. Multi-Provider AI Resilience: Automatic fallback between Groq, OpenAI, and synthetic data

4. Real-time Processing Updates: Live status tracking for long-running operations. All edge functions update database status for live frontend progress indication

5. Memory-Safe Operations: Prevents memory leaks in real-time features. Proper cleanup and chunking prevent memory leaks in document processing

6. Comprehensive Error Boundaries: Application-level error handling

7. Security-First Design: URL validation, RLS policies, and authentication checks