# benmed00/lucid-web-craftsman architecture

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

- Interactive diagram: https://gitdiagram.com/benmed00/lucid-web-craftsman
- Repository: https://github.com/benmed00/lucid-web-craftsman

## Overview

##### Project type and purpose
- This is a full-stack e-commerce web application (“Lovable”) built with a React+TypeScript SPA on Vite, a lightweight Node.js server layer, and Supabase (Postgres + auth) plus Stripe for payments. It offers public pages (products, blog, cart, checkout) and a protected admin dashboard for managing inventory, orders, customers, marketing assets, etc.

##### File structure
- Top level:
- public/ – static assets served verbatim
- src/ – main app source
- server.js / server.cjs – Node.js server entry points (serves built SPA, handles any SSR, API proxying)
- supabase/ – DB migration configs
- Within src/:
- pages/ – React page components (public and /admin)
- components/ – UI and layout components, including shadcn-ui primitives
- context/ + hooks/ – state management and custom hooks (auth, cart, CSRF, toast)
- services/ + integrations/ – wrappers around HTTP calls to Supabase or 3rd-party APIs (stripe via src/lib/stripe.ts)
- api/mockApiService.ts – mock implementations for local dev/testing
- Configs: Vite, Tailwind, tsconfig, ESLint, Prettier

##### README for additional insights
- Confirms Vite + TypeScript + React + shadcn-ui + Tailwind CSS
- Deployment via Lovable platform (essentially static hosting + serverless supabase/stripe)
- No separate microservices—everything lives in one repo

a. Main components:
1. User’s Web Browser (client)
2. Frontend SPA (React on Vite)
3. Node.js Server (server.js)
4. Supabase Backend (Postgres DB + Auth)
5. Stripe Payments
6. Static Asset Store (public/assets)
7. Mock API Service (dev/testing only)
b. Relationships & interactions:
- Browser ↔ Frontend SPA: React UI pages call hooks/services → Node.js server or directly to Supabase
- Frontend ↔ Node.js Server: asset requests; optional API proxy (e.g., CSRF tokens, SSR)
- Frontend ↔ Supabase: data read/write (products, cart, orders, user profile) via src/integrations/supabase/client.ts
- Frontend ↔ Stripe: checkout creation through src/lib/stripe.ts or via server endpoint
- Node.js Server ↔ Supabase/Stripe: used for protected operations or securing secret keys
- Node.js Server ↔ Static Asset Store: returns images, robots.txt, index.html
- Dev/Test: SPA ↔ mockApiService (when supabase is unavailable)
c. Architectural patterns & principles:
- SPA separation: pages ↔ shared components ↔ UI primitives
- Context API for global state (CartContext, Auth context)
- Service layer (src/services) for encapsulating API calls
- Integration layer (src/integrations) for 3rd-party clients
- Admin protected routes and RBAC via ProtectedAdminRoute
- Migrations defined under supabase/ for versioned schema
d. Key technologies:
- Vite (dev server & build)
- React + TypeScript + shadcn-ui + Tailwind CSS
- Node.js + Express-style static serving (server.js)
- Supabase (Postgres + Auth + Storage)
- Stripe SDK
- Vitest/Jest for tests (src/tests)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Browser
    Browser["User Browser"]:::external

    %% Frontend Container
    subgraph "Frontend SPA (React + Vite)" 
        direction TB
        Main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        Pages["Pages<br/>(public & admin)"]:::frontend
        Components["Shared UI Components"]:::frontend
        AdminComponents["Admin Components"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
        ProtectedRoute["ProtectedAdminRoute"]:::frontend
        Context["Global Context"]:::frontend
        Hooks["Custom Hooks"]:::frontend
        Services["Service Layer"]:::frontend
        Integrations["Integration Layer"]:::frontend
    end

    %% Backend & External
    subgraph "Backend & Services"
        direction TB
        Server["Node.js Server"]:::backend
        subgraph "Supabase Backend"
            Auth["Auth"]:::db
            Database["Postgres DB"]:::db
            Storage["Storage"]:::db
        end
        Stripe["Stripe SDK"]:::external
        StaticAssets["Static Assets Store"]:::backend
    end

    %% Mock for Dev/Test
    MockService["Mock API Service"]:::optional

    %% Supabase Config & Migrations
    subgraph "DB Config & Migrations"
        Config["config.toml"]:::db
        Migrations["migrations/"]:::db
    end

    %% Interactions
    Browser -->|"loads SPA"| Main
    Main -->|"app init"| App
    App -->|"renders pages"| Pages
    Pages -->|"uses components"| Components
    Pages -->|"uses admin comps"| AdminComponents
    Components -->|"UI primitives"| UIPrimitives
    Pages -->|"guarded by"| ProtectedRoute
    App -->|"global state"| Context
    App -->|"hooks usage"| Hooks
    App -->|"calls services"| Services
    Services -->|"calls integrations"| Integrations

    %% Runtime data flows
    Services -->|"fetch products"| Integrations
    Integrations -->|"supabase.from('products').select()"| Database
    Integrations -->|"auth functions"| Auth
    Services -->|"create checkout"| Stripe
    App -->|"upload files"| Storage

    %% Server flows
    Browser -->|"requests assets / proxy"| Server
    Server -->|"serves static"| StaticAssets
    Server -->|"SSR / proxy"| Auth
    Server -->|"db operations"| Database
    Server -->|"stripe webhooks"| Stripe

    %% Mock path
    App -.->|"dev replace"| MockService
    MockService -.->|"mock data"| Services

    %% Config & Migrations
    Config -->|applied to| Database
    Migrations -->|version control| Database

    %% Click Events
    click Main "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/main.tsx"
    click App "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/App.tsx"
    click Pages "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/pages/"
    click Components "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/components/"
    click AdminComponents "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/components/admin/"
    click UIPrimitives "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/components/ui/"
    click ProtectedRoute "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/components/ProtectedAdminRoute.tsx"
    click Context "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/context/"
    click Hooks "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/hooks/"
    click Services "https://github.com/benmed00/lucid-web-craftsman/tree/main/src/services/"
    click Integrations "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/integrations/supabase/client.ts"
    click Stripe "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/lib/stripe.ts"
    click MockService "https://github.com/benmed00/lucid-web-craftsman/blob/main/src/api/mockApiService.ts"
    click StaticAssets "https://github.com/benmed00/lucid-web-craftsman/tree/main/public/assets/"
    click Server "https://github.com/benmed00/lucid-web-craftsman/blob/main/server.js"
    click Config "https://github.com/benmed00/lucid-web-craftsman/blob/main/supabase/config.toml"
    click Migrations "https://github.com/benmed00/lucid-web-craftsman/tree/main/supabase/migrations/"

    %% Legend
    subgraph Legend
      L1["Blue = Frontend"]:::frontend
      L2["Green = Backend"]:::backend
      L3["Orange = Database"]:::db
      L4["Red = External"]:::external
      L5["Dashed = Optional/Mock"]:::optional
    end

    classDef frontend fill:#1E90FF,stroke:#333,color:#fff;
    classDef backend fill:#8FBC8F,stroke:#333,color:#000;
    classDef db fill:#FFA500,stroke:#333,color:#000;
    classDef external fill:#DC143C,stroke:#333,color:#fff;
    classDef optional fill:#CCCCCC,stroke:#666,stroke-dasharray: 5 5;color:#000;
```
