How kubiknyc/supersitehero works
Project type and purpose
• This is a full-stack, offline-first Progressive Web App (PWA) for construction field management.
• Frontend: React + Vite + TypeScript + TailwindCSS + React Router + TanStack Query + Zustand + Vite PWA plugin + Service Workers + IndexedDB.
• Backend: Supabase (PostgreSQL, Auth, Storage, Realtime, RLS).
• Purpose: unify daily reports, RFIs, change orders, punch lists, safety, inspections, photos, etc., with robust offline sync.
Main architectural components
a. Frontend PWA (browser)
• App Shell (index.html, App.tsx, main.tsx)
• Feature modules under src/features (daily-reports, workflows, etc.)
• Reusable components under src/components (layout, ui, notifications, sync indicators)
• Pages under src/pages for routing
• State & data layer: TanStack Query + React Query hooks + Zustand stores
• Validation & form handling with Zod schemas
b. API Abstraction
• src/lib/api/client.ts (Supabase client wrapper)
• src/lib/api/services/*.ts (per-feature service modules)
• src/lib/hooks/useApiCall.ts + useMutationWithNotification.ts
c. Offline layer
• Service Worker (Vite PWA plugin)
• IndexedDB (selective sync store under src/features/.../store & custom hooks)
• Sync queue & indicators (components under src/components/sync)
d. Backend as a Service
• Supabase Auth (sign up, login, role-based JWT tokens)
• Supabase Postgres with Row-Level Security policies (multi-tenant)
• Storage buckets for documents, photos, drawings, reports
• Realtime subscriptions for live updates
• Database migrations (migrations/ & supabase/migrations/)
e. External dependencies
• Supabase hosted services
• Vercel/Netlify for hosting static build
• Git for version control
• CI/CD scripts (auto-deploy.js, deploy.js, run-migrations.py)
Relationships & data flows
• User interacts with UI components → React Router → Feature pages/components
• Components call React Query hooks → API client → Supabase REST/Realtime
• Service Worker intercepts network requests → serves cached assets or falls back to IndexedDB
• On offline, data‐mutation hooks enqueue operations in IndexedDB → Sync queue service picks up when online → invokes Supabase APIs → updates local store
• Supabase Realtime pushes notifications/updates → frontend subscription hooks → React Query cache/update UI
• Migrations scripts push schema changes to Supabase Postgres prior to feature rollout
Architectural patterns & design principles
• Offline-first synchronization (Command queue, conflict resolution)
• Feature-folder structure (separation of concerns)
• API/Service abstraction (thin client wrapper + per-feature services)
• Container/Presentational component separation under src/components & src/features/*/components
• Typed contracts end-to-end with TypeScript and generated database types
• Multi-tenant, role-based access using RLS
a. Components
• User’s Browser (PWA)
• Service Worker & Cache / IndexedDB
• Frontend Modules (UI, Features, State)
• API Layer (Supabase client)
• Supabase Backend: Auth, Postgres DB, Storage, Realtime
• CI/CD & Deployment Targets (Vercel/Netlify)
b. Interactions
• Realtime push: Supabase → frontend subscription hooks → UI
• Migrations: Local scripts → Supabase DB
c. Technologies
• Component with frameworks/libraries (e.g., React, Vite, TanStack Query, Supabase)
d. Patterns
• Use grouped containers to show “Feature modules” vs. “Shared components” vs. “lib/api”
Detail level
• How migrations folder and deployment scripts feed into the Supabase DB
• Multi-tenant RLS enforcement at the DB layer
• Don’t overload with every React component, focus on layers: UI → State/API → Backend