Architecture Overview

PIP AI follows a modern full-stack architecture with a Nuxt 4 frontend, Supabase backend, and N8N workflow orchestration.

System Architecture

graph TB
    subgraph Client["Frontend (Nuxt 4 + Vue 3)"]
        Pages[Pages & Layouts]
        Components[Components]
        Composables[Composables]
        Stores[Pinia Stores]
        FabricJS[Fabric.js Canvas]
    end

    subgraph Server["Backend (Nitro Server)"]
        API[Server API Routes]
        Webhooks[Webhook Handlers]
    end

    subgraph Supabase["Supabase Platform"]
        Auth[Auth & JWT]
        DB[(PostgreSQL + pgvector)]
        Storage[Storage Buckets]
        Realtime[Realtime Subscriptions]
        RLS[Row Level Security]
    end

    subgraph N8N["N8N Orchestration"]
        SpecFlow[Spec Processing]
        PIPFlow[PIP Processing]
        FloorPlanFlow[Floor Plan Processing]
        AIFlow[AI Image Generation]
    end

    subgraph External["External Services"]
        PolyHaven[Poly Haven API]
        NanoBanana[Nano Banana AI]
        OpenAI[OpenAI Embeddings]
    end

    Client --> Server
    Client --> Supabase
    Server --> Supabase
    Server --> N8N
    N8N --> Supabase
    N8N --> External
    Server --> External

Key Architecture Decisions

Decision	Choice	Rationale
Frontend Framework	Nuxt 4 (Vue 3)	SSR support, file-based routing, auto-imports
Backend	Supabase + Nitro	Managed PostgreSQL, built-in auth, realtime, minimal server code
Vector Search	pgvector (1536-dim)	Single-stack simplicity, hybrid search
Canvas Library	Fabric.js 5.2.4	Mature object manipulation, custom objects, good performance
PDF Rendering	PDF.js 3.11.174	Client-side PDF rendering for floor plans
Orchestration	N8N	Visual workflow builder, webhook support, retries
State Management	Pinia	Vue 3 native, simple API, devtools support

Data Flow Summary

1. Document Upload — User uploads PDF → stored in Supabase Storage → N8N webhook triggered
2. AI Processing — N8N extracts data using OCR/LLM → upserts structured items → generates embeddings
3. Matching — pgvector hybrid search finds candidate specs → stored as matches with confidence scores
4. Human Review — User reviews, approves, or rejects matches in the UI
5. Export — Document builder assembles final deliverable → PDF export

Sections

• Frontend Architecture — Nuxt 4, Vue 3, pages, layouts, middleware
• Backend Architecture — Server routes, Supabase service role, webhooks
• Database Architecture — ERD, table relationships, pgvector
• Data Flow — End-to-end processing flows
• Authentication — Auth middleware, RLS, dev bypass