# p1manav/figmaguard architecture

> Architecture diagram of the GitHub repository p1manav/figmaguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p1manav/figmaguard
- Repository: https://github.com/p1manav/figmaguard

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Automated Testing Platform”) with two distinct user flows:
a. Test an existing Figma design or live URL against an SRS.
b. Generate a website from an SRS via AI, deploy it, then test it.
- Frontend: Next.js + TypeScript + Tailwind.
- Backend: Python Flask + Playwright + Supabase + AI & external services.

##### Main Architectural Layers and Components
A. Client Layer
- Next.js App Router
- React Components & Pages (under `frontend/app`, `frontend/components`, `frontend/hooks`)
- CSS (Tailwind + global styles)
B. API Layer
- Flask server (`backend/server.py`) exposing REST endpoints for:
– Authentication callbacks
– SRS upload & parsing
– Test request creation
– Code-generation request
– Fetching test results
C. Test Engine
- `backend/scripts/`
– `test_runner.py` orchestrates different testers:
functional, UI/UX, accessibility, compatibility, performance
– Each tester uses Playwright under the hood
D. Data & Storage
- Supabase
– Auth (Google OAuth)
– PostgreSQL (tables: user_profiles, test_requests, test_reports, execution_logs)
– Storage buckets (SRS-docs, test-reports, generated-sites)
- Local temp storage for intermediate PDFs (`backend/temp/`)
E. AI & Integration Services
- Groq LLM (code generation)
- Gemini LLM (content extraction, analysis)
- GitHub API (repo creation & commit)
- Vercel API (deployment)
F. External Clients & Users
- Browser / End-user
- CI or Dev Tools invoking scripts (if any)

##### Relationships & Data Flows
1. User → Browser → Next.js UI
2. UI → HTTP → Flask API
3. Flask API ↔ Supabase (Auth, DB, Storage)
4. Flask API → Gemini & Groq LLMs → code or analysis results
5. For “Generate & Test”:
a. Flask → GitHub API → new repo
b. Flask → Vercel API → deploy site
c. After deploy, URL returned to Flask
6. Flask API → invokes `test_runner.py` → Playwright tests against target URL
7. Test scripts → write results/logs → Supabase Storage & DB
8. UI polls or listens for test-status updates → displays results

##### Architectural Patterns & Principles
- Layered architecture: clear separation between Presentation (Next.js), API (Flask), Business Logic (scripts/utils), Data (Supabase).
- Modular test engine: each test type is a plug-in under `backend/scripts/`.
- Single monolith for backend, but integration with external microservices (LLMs, GitHub, Vercel).
- Use of SDKs/clients in `backend/utils/` for external services (supabase_client, llm_client, gemini_client).

## Diagram (Mermaid)

```mermaid
graph TB

    subgraph "Client Layer"
        Browser["Browser / Next.js"]:::internal
        NextApp["Next.js App Router"]:::internal
        ReactComp["React Components & Pages"]:::internal
        Styles["Tailwind & Global Styles"]:::internal

        Browser --> NextApp
        NextApp --> ReactComp
        ReactComp --> Styles

        click NextApp "https://github.com/p1manav/figmaguard/tree/main/frontend/app"
        click ReactComp "https://github.com/p1manav/figmaguard/tree/main/frontend/components"
        click Styles "https://github.com/p1manav/figmaguard/blob/main/frontend/app/globals.css"
        click Styles "https://github.com/p1manav/figmaguard/blob/main/frontend/styles/globals.css"
        click Styles "https://github.com/p1manav/figmaguard/blob/main/frontend/tailwind.config.ts"
    end

    subgraph "API Layer and Test Engine"
        APIServer["Flask API Server"]:::internal
        Docker["Deployment Config"]:::internal
        LocalTemp["Local Temp Storage (PDFs)"]:::data

        APIServer --> Docker
        APIServer --> LocalTemp

        click APIServer "https://github.com/p1manav/figmaguard/blob/main/backend/server.py"
        click Docker "https://github.com/p1manav/figmaguard/tree/main/backend/Dockerfile"
        click Docker "https://github.com/p1manav/figmaguard/blob/main/backend/render.yaml"
        click Docker "https://github.com/p1manav/figmaguard/blob/main/backend/.dockerignore"
        click LocalTemp "https://github.com/p1manav/figmaguard/tree/main/backend/temp"

        subgraph "Test Engine"
            TestRunner["Test Runner Orchestrator"]:::internal
            FT["Functional Testing"]:::internal
            UIUX["UI/UX Testing"]:::internal
            ACC["Accessibility Testing"]:::internal
            COMP["Compatibility Testing"]:::internal
            PERF["Performance Testing"]:::internal

            TestRunner --> FT
            TestRunner --> UIUX
            TestRunner --> ACC
            TestRunner --> COMP
            TestRunner --> PERF

            click TestRunner "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/test_runner.py"
            click FT "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/functional_testing.py"
            click UIUX "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/uiux_testing.py"
            click ACC "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/accessibility_testing.py"
            click COMP "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/compatibility_testing.py"
            click PERF "https://github.com/p1manav/figmaguard/blob/main/backend/scripts/performance_testing.py"
        end

        subgraph "Utils"
            SupaClient["Supabase Client SDK"]:::internal
            SupabaseSchema["Supabase Schema"]:::data
            LLMGroq["Groq LLM Client"]:::internal
            LLMDemo["Gemini LLM Client"]:::internal

            click SupaClient "https://github.com/p1manav/figmaguard/blob/main/backend/utils/supabase_client.py"
            click SupabaseSchema "https://github.com/p1manav/figmaguard/blob/main/backend/supabase_schema.sql"
            click LLMGroq "https://github.com/p1manav/figmaguard/blob/main/backend/utils/llm_client.py"
            click LLMDemo "https://github.com/p1manav/figmaguard/blob/main/backend/utils/gemini_client.py"

            APIServer --> SupaClient
            SupaClient --> SupabaseSchema
            APIServer --> LLMGroq
            APIServer --> LLMDemo
            APIServer --> TestRunner
        end
    end

    subgraph "External Services"
        SupabaseDB["Supabase (Auth / DB / Storage)"]:::data
        GitHubAPI["GitHub API"]:::ext
        VercelAPI["Vercel API"]:::ext
        Groq["Groq LLM"]:::ext
        Gemini["Gemini LLM"]:::ext

        APIServer -->|REST calls| SupabaseDB
        LLMGroq -->|SDK calls| Groq
        LLMDemo -->|SDK calls| Gemini
        APIServer -->|Create repo| GitHubAPI
        APIServer -->|Deploy site| VercelAPI
        TestRunner -->|Store results| SupabaseDB
        TestRunner -->|Fetch config| SupabaseDB
    end

    Browser -->|REST calls| APIServer

    classDef internal fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef data fill:#E8F5E9,stroke:#43A047,color:#000
    classDef ext fill:#FFF3E0,stroke:#FB8C00,color:#000
```
