Teardown

Frontend Design DNA Extractor

🔬 Drop any UI screenshot or design link to extract a structured, production-ready design system — typography, color swatches, 2D FFT texture signatures, layout metrics, and generative image recipes.

---

✦ Key Features

• 📸 Dual Upload Modes: Drag & drop local image screenshots (PNG, JPG, WEBP) or instantly scrape shots directly from Dribbble, Pinterest, Behance, or web URLs with WAF-bypass fallback.
• 🎨 Computer Vision Feature Extraction: Runs deterministic LAB-space KMeans palette clustering, WCAG contrast ratio calculations, 2D FFT spectral texture frequency analysis, and Canny/Hough layout grid detection before invoking AI.
• 🧠 Grounded Vision LLM Reasoning: Feeds screenshot + measured CV data to OpenRouter vision models (Qwen-2.5-VL / Gemini 2.0 / Claude Vision) to emit structured "Design DNA" JSON without hallucinated hex codes.
• ⚡ Editorial Gallery & Filter Board: Browse cataloged UI designs with instant category filtering, keyword tag search, interactive detail breakdowns, color swatches, and confidence-rated font guesses.
• 📋 One-Click Copy Workflows: Copy complete production Design Briefs or Generative Image Prompts (Midjourney / Flux / DALL-E) ready for clipboard reuse.
• 🛡️ Hardened Security Posture: Built-in SSRF IP blocking, file byte-sniffing and re-encoding, upload caps, static CORS binding, and orphaned screenshot garbage collection.

---

📐 Architecture Diagram

flowchart TD
    subgraph Client ["Next.js Client (Port 3005)"]
        UI["Gallery Grid • Filter Bar • Upload Dropzone / Scraper"]
    end

    subgraph Backend ["FastAPI Backend (Port 8000)"]
        CV["Layer 1: OpenCV + Scikit-Learn CV Feature Extraction<br/>• LAB KMeans Palette (Hex + WCAG Contrast Roles)<br/>• 2D FFT Frequency Analysis (Pattern & Grain)<br/>• Canny/Hough Lines (Whitespace Density & Grid)"]
        LLM["Layer 2: OpenRouter Vision Reasoning (LLM)<br/>• Grounded Design DNA Structured Schema"]
        DB[("Layer 3: Persistence<br/>• SQLite DB (teardown.db) + Local Screenshot Store")]
    end

    UI -->|"Multipart Upload / URL Scrape"| CV
    CV -->|"Grounded CV Measurements"| LLM
    LLM -->|"Merged DesignCard Record"| DB

Loading

---

🧰 Tech Stack

Component	Technology	Purpose
Frontend	Next.js 16 (App Router), TypeScript, Tailwind CSS 4	Print-tech editorial UI with Playfair Display & IBM Plex Mono typography
Backend API	Python 3.12+ / FastAPI, Uvicorn	Async sidecar handling processing, scraping & LLM communication
Computer Vision	OpenCV, Pillow, NumPy, Scikit-Learn (KMeans)	Deterministic color, texture, and layout extraction
Scraper	BeautifulSoup4, HTTPX, Jina Reader fallback	SSRF-guarded image scraper for Dribbble, Pinterest & web links
AI / LLM	OpenRouter Chat Completions	Grounded multimodal vision reasoning
Database & Storage	SQLite (WAL mode) & Disk Storage	Monotonic catalog position indexing & local file storage

---

🎨 Design DNA Tokens

The UI follows an editorial print-tech aesthetic:

:root {
  --bg-cream:     #F4F0E6; /* Cream canvas background */
  --ink:          #1C1A16; /* Midnight ink primary text & borders */
  --ink-soft:     #4A463D; /* Secondary muted text */
  --warm-gray:    #8C8676; /* Tertiary borders & catalog index counter */
  --tag-bg:       #EAE4D6; /* Tag pill fill */
  --accent-rust:  #AE5A34; /* Terracotta rust diamond glyph ◆ */
  --recipe-tint:  #EDDCD2; /* Generative recipe panel background */
}

---

⚡ Quick Start

1. Prerequisites

• Python 3.12+ (Python 3.12, 3.13, or 3.14)
• Node.js 18+ & npm

2. Clone & Launch

git clone https://github.com/satiricalguru/Teardown.git
cd Teardown

# Install dependencies (First time setup)
cd backend && python3 -m venv venv && ./venv/bin/pip install -r requirements.txt && cd ..
cd frontend && npm install && cd ..

# Configure OpenRouter Key (Optional for AI reasoning; CV-only fallback enabled by default)
cp backend/.env.example backend/.env

3. Run Teardown

./start.sh

./start.sh launches the FastAPI backend (http://127.0.0.1:8000) and Next.js frontend (http://localhost:3005), waits for health check confirmation, and opens your default browser automatically.

---

📡 API Reference

Method	Endpoint	Description
POST	/api/designs/analyze	Upload multipart screenshot image → runs full CV + LLM pipeline → persists card
POST	/api/designs/analyze-url	Scrapes shot from Dribbble/Pinterest/web link → runs pipeline → persists card
GET	/api/designs	List all cataloged cards (?category= filter, ?q= search)
GET	/api/designs/{id}	Get single design card by ID
DELETE	/api/designs/{id}	Permanently delete card and unlinks screenshot file
GET	/api/categories	Retrieve live category taxonomy list with count totals

---

🧪 Testing & Verification

# Run backend pytest suite (38 tests)
cd backend && ./venv/bin/python3 -m pytest

# Run frontend type checking & linter
cd frontend && npx tsc --noEmit && npm run lint

---

📜 License

This project is licensed under the MIT License.