# elgabocraft/v0-ecommerce architecture

> Architecture diagram of the GitHub repository elgabocraft/v0-ecommerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elgabocraft/v0-ecommerce
- Repository: https://github.com/elgabocraft/v0-ecommerce

## Overview

##### Project type and purpose
- This is a full-stack e-commerce website built on Next.js (using the app router), TypeScript, and Vercel for hosting.
- It surfaces a storefront for end users (shopping, checkout, order tracking) and an admin panel (product catalog management, orders, reports).
- It uses Supabase (PostgreSQL) as its primary database, plus utility services (image storage, PDF‐invoice generation, webhooks via n8n).

##### High-level file structure analysis
- app/…       → Next.js pages and layouts separated into public storefront, cart/checkout flows, user profile, admin panel, and API routes under app/api
- components/… → Reusable UI components grouped by domain: admin, auth, storefront, reviews, plus low-level ui primitives
- lib/…        → Core business logic and integrations: auth, database (lib/db.ts), Supabase wrapper, image‐storage, PDF generator, webhook API, common types & utils
- hooks/…      → Custom React hooks (e.g. useToast)
- data/…       → JSON fixtures (likely used for local mock or initial seeding)
- scripts/…    → SQL and JS scripts for initializing or migrating Supabase tables
- public/, styles/, next.config.mjs, Dockerfile, nixpacks.toml, etc. → Deployment, configuration, and static assets

##### Key insights from README
- The repo is auto-synced from a v0.app design interface and deployed on Vercel.

##### Main components
a. Client Browser (User’s device)
b. Next.js Frontend (SSR/SSG + React components in app/ + components/)
c. Next.js API Layer (app/api routes)
d. Business Logic & Services (lib/* modules)
e. Database (Supabase/PostgreSQL)
f. External Services
- Image Storage (e.g., S3 or Supabase storage via lib/image-storage.ts)
- PDF Generator (lib/pdf-generator.ts)
- Webhooks (n8n integration via lib/webhook-api.ts, app/api/webhooks)
g. Deployment Infrastructure (Vercel, Docker/Nixpacks config)

##### Relationships & data flows
- Browser → Next.js pages (GET/POST) → Server-side rendering or client hydration
- Browser → fetch(…) → app/api/*** route handlers
- API handlers → call into lib/* modules (auth.ts, cart-context, db.ts, export-utils, etc.)
- lib/db.ts + lib/supabase.ts → read/write Supabase database
- Business logic → invoke external services (PDF, image store, webhooks)
- Admin users → authenticated gaps → admin API routes → same underlying services & DB
- Deployment config sits alongside to package all components into Vercel microservices

##### Architectural patterns & design principles
- Separation of concerns: UI vs. API vs. business logic vs. data layer
- Next.js “app router” pattern: colocating routes, server code, and UI per domain folder
- Modular services in lib/: single-responsibility modules (auth, db, webhooks, PDF)
- Component-driven UI with domain and generic UI primitives
- Infrastructure as code: Dockerfile, nixpacks.toml, SQL migration scripts

##### Detailing the essential elements
- Do not omit the app/api folder – it’s the heart of your backend.
- Lib/db.ts and lib/supabase.ts as the gateway to persistent storage.
- Flows for critical features:
- Catalog browsing (products → categories → UI)
- Cart & checkout (cart context → API → orders → invoices)
- Admin management (product CRUD, reports generation)
- Webhooks (order events → lib/webhook-api → n8n)

## Diagram (Mermaid)

```mermaid
graph TB
    Browser["Client Browser"]:::frontend

    subgraph "Next.js Frontend Layer"
        Storefront["Public Storefront"]:::frontend
        CartCheckout["Cart & Checkout Flows"]:::frontend
        ProfileOrders["User Profile & Orders"]:::frontend
        AdminPanel["Admin Panel"]:::frontend
    end

    subgraph "Next.js API Layer"
        ProductsAPI["Products API"]:::api
        AdminAPI["Admin & Reports API"]:::api
        InventoryAPI["Inventory & Invoices API"]:::api
        WebhooksAPI["Webhooks API"]:::api
    end

    subgraph "Business Logic & Services"
        AuthService["Auth Service"]:::service
        DBService["Database Service (lib/db.ts)"]:::service
        CartService["Cart Context"]:::service
        ExportUtils["Export & Export-Utils"]:::service
        TypesUtils["Common Types & Utils"]:::service
        Hooks["React Hooks (use-toast)"]:::service
    end

    DB["Supabase / PostgreSQL"]:::db

    subgraph "External Services"
        ImageStorage["Image Storage"]:::external
        PDFGenerator["PDF Generator"]:::external
        WebhookSystem["n8n Webhook Platform"]:::external
    end

    Infra["Deployment Infrastructure (Vercel / Docker)"]:::infra
    Scripts["DB Migrations & Setup Scripts"]:::infra

    %% Flows
    Browser --> Storefront
    Browser --> CartCheckout
    Browser --> ProfileOrders
    Browser --> AdminPanel

    Storefront --> ProductsAPI
    Storefront --> AuthService

    CartCheckout --> ProductsAPI
    CartCheckout --> InventoryAPI
    CartCheckout --> AuthService

    ProfileOrders --> ProductsAPI
    ProfileOrders --> AuthService

    AdminPanel --> AdminAPI
    AdminPanel --> ProductsAPI
    AdminPanel --> InventoryAPI
    AdminPanel --> AuthService

    ProductsAPI --> DBService
    ProductsAPI --> ImageStorage

    AdminAPI --> AuthService
    AdminAPI --> DBService

    InventoryAPI --> DBService
    InventoryAPI --> ExportUtils
    InventoryAPI --> PDFGenerator

    WebhooksAPI --> AuthService
    WebhooksAPI --> WebhookSystem

    AuthService --> DBService
    CartService --> DBService
    ExportUtils --> DBService

    Infra --- Storefront
    Infra --- ProductsAPI
    Infra --- AuthService
    Infra --- DBService

    Scripts --- DBService

    %% Click Events
    click Storefront "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/page.tsx"
    click CartCheckout "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/cart/page.tsx"
    click ProfileOrders "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/profile/page.tsx"
    click AdminPanel "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/admin/layout.tsx"
    click ProductsAPI "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/api/products/route.ts"
    click AdminAPI "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/api/admin/login/route.ts"
    click InventoryAPI "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/api/inventory/available/route.ts"
    click WebhooksAPI "https://github.com/elgabocraft/v0-ecommerce/blob/main/app/api/webhooks/n8n/route.ts"
    click DBService "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/db.ts"
    click AuthService "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/auth.ts"
    click CartService "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/cart-context.tsx"
    click ExportUtils "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/export-utils.ts"
    click TypesUtils "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/types.ts"
    click Hooks "https://github.com/elgabocraft/v0-ecommerce/blob/main/hooks/use-toast.ts"
    click ImageStorage "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/image-storage.ts"
    click PDFGenerator "https://github.com/elgabocraft/v0-ecommerce/blob/main/lib/pdf-generator.ts"
    click Scripts "https://github.com/elgabocraft/v0-ecommerce/blob/main/scripts/setup-tables.js"
    click Infra "https://github.com/elgabocraft/v0-ecommerce/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#D0F0C0,stroke:#099e00,color:#099e00;
    classDef service fill:#C5D9F1,stroke:#1155CC,color:#1155CC;
    classDef db fill:#FCE5CD,stroke:#E69138,color:#E69138;
    classDef external fill:#E6E0F8,stroke:#7E57C2,color:#7E57C2;
    classDef infra fill:#F0F0F0,stroke:#999999,color:#333333;
```
