# kubiknyc/supersitehero architecture

> Architecture diagram of the GitHub repository kubiknyc/supersitehero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubiknyc/supersitehero
- Repository: https://github.com/kubiknyc/supersitehero

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser / PWA Layer
    subgraph "Browser / PWA" 
        direction TB
        subgraph "App Shell" 
            direction TB
            AS_index["index.html"]:::frontend
            AS_main["src/main.tsx"]:::frontend
            AS_app["src/App.tsx"]:::frontend
        end
        subgraph "Routing Pages" 
            direction TB
            Pages["src/pages"]:::frontend
        end
        subgraph "Feature Modules" 
            direction TB
            FM_CHANGE["Change Orders"]:::frontend
            FM_DAILY["Daily Reports"]:::frontend
            FM_DOCS["Documents"]:::frontend
            FM_PROJ["Projects"]:::frontend
            FM_PUNCH["Punch Lists"]:::frontend
            FM_RFI["RFIs"]:::frontend
            FM_SUB["Submittals"]:::frontend
            FM_TASKS["Tasks"]:::frontend
            FM_WF["Workflows"]:::frontend
            FM_REP["Reports"]:::frontend
        end
        subgraph "Shared UI Components" 
            direction TB
            UI_LAY["Layout"]:::frontend
            UI_PRIM["UI Primitives"]:::frontend
            UI_NOTIF["Notifications"]:::frontend
            UI_ERROR["Error Handling"]:::frontend
        end
        subgraph "State & Data Layer" 
            direction TB
            State_Q["TanStack Query Hooks"]:::frontend
            State_Z["Zustand Stores"]:::frontend
        end
        subgraph "Offline Layer" 
            direction TB
            SW["Service Worker"]:::offline
            IDX["IndexedDB Store"]:::offline
            subgraph "Sync Indicators" 
                direction TB
                SI_1["OfflineIndicator"]:::offline
                SI_2["SyncQueueBadge"]:::offline
                SI_3["SyncStatusBar"]:::offline
                SI_4["SyncStatusIndicator"]:::offline
            end
        end
    end

    %% API Abstraction
    subgraph "API Abstraction" 
        direction TB
        API_CLIENT["Supabase Client Wrapper"]:::api
        API_SVC["Service Modules"]:::api
        API_ERR["API Error Types"]:::api
        API_HOOKS["API Hooks"]:::api
    end

    %% Supabase Backend
    subgraph "Supabase Backend" 
        direction TB
        SB_AUTH["Auth"]:::backend
        SB_DB["Postgres + RLS"]:::backend
        SB_STORAGE["Storage Buckets"]:::backend
        SB_RT["Realtime"]:::backend
        subgraph "Migrations" 
            direction TB
            MIG_LOCAL["migrations/*.sql"]:::backend
            MIG_CLI["supabase/migrations/*.sql"]:::backend
        end
    end

    %% External / Deployment
    subgraph "External / Deployment" 
        direction TB
        Host["Vercel / Netlify"]:::external
        subgraph "CI/CD Scripts" 
            direction TB
            CD1["auto-deploy.js"]:::external
            CD2["deploy.js"]:::external
            CD3["run-migrations.py"]:::external
            CD4["deploy-migration.js"]:::external
        end
    end

    %% Connections
    AS_app -->|"renders UI"| FM_CHANGE
    AS_app --> FM_DAILY
    AS_app --> FM_DOCS
    AS_app --> FM_PROJ
    AS_app --> FM_PUNCH
    AS_app --> FM_RFI
    AS_app --> FM_SUB
    AS_app --> FM_TASKS
    AS_app --> FM_WF
    AS_app --> FM_REP

    FM_CHANGE -->|"useQuery/useMutations"| State_Q
    FM_DAILY --> State_Q
    FM_CHANGE --> State_Z
    FM_DAILY --> State_Z

    UI_LAY --> Pages
    UI_NOTIF --> FM_CHANGE

    SW -->|"intercepts requests"| API_CLIENT
    IDX -->|"enqueue mutations"| API_CLIENT
    FM_DAILY -->|"read/write offline"| IDX
    FM_DAILY -->|"show status"| SI_1

    API_CLIENT -->|"calls Supabase REST"| SB_DB
    API_SVC --> SB_DB
    API_CLIENT --> SB_AUTH
    API_CLIENT --> SB_STORAGE
    API_CLIENT --> SB_RT

    SB_RT -->|"realtime subscribe"| API_HOOKS
    API_HOOKS --> State_Q
    State_Q --> UI_LAY

    CD3 --> SB_DB
    CD4 --> SB_DB
    CD1 --> Host
    CD2 --> Host

    %% Click Events
    click AS_index "https://github.com/kubiknyc/supersitehero/blob/main/index.html"
    click AS_main "https://github.com/kubiknyc/supersitehero/blob/main/src/main.tsx"
    click AS_app "https://github.com/kubiknyc/supersitehero/blob/main/src/App.tsx"
    click FM_CHANGE "https://github.com/kubiknyc/supersitehero/tree/main/src/features/change-orders"
    click FM_DAILY "https://github.com/kubiknyc/supersitehero/tree/main/src/features/daily-reports"
    click FM_DOCS "https://github.com/kubiknyc/supersitehero/tree/main/src/features/documents"
    click FM_PROJ "https://github.com/kubiknyc/supersitehero/tree/main/src/features/projects"
    click FM_PUNCH "https://github.com/kubiknyc/supersitehero/tree/main/src/features/punch-lists"
    click FM_RFI "https://github.com/kubiknyc/supersitehero/tree/main/src/features/rfis"
    click FM_SUB "https://github.com/kubiknyc/supersitehero/tree/main/src/features/submittals"
    click FM_TASKS "https://github.com/kubiknyc/supersitehero/tree/main/src/features/tasks"
    click FM_WF "https://github.com/kubiknyc/supersitehero/tree/main/src/features/workflows"
    click FM_REP "https://github.com/kubiknyc/supersitehero/tree/main/src/features/reports"
    click UI_LAY "https://github.com/kubiknyc/supersitehero/blob/main/src/components/layout/AppLayout.tsx"
    click UI_PRIM "https://github.com/kubiknyc/supersitehero/tree/main/src/components/ui"
    click UI_NOTIF "https://github.com/kubiknyc/supersitehero/blob/main/src/components/notifications/ToastContainer.tsx"
    click UI_ERROR "https://github.com/kubiknyc/supersitehero/blob/main/src/components/errors/ErrorBoundary.tsx"
    click SI_1 "https://github.com/kubiknyc/supersitehero/blob/main/src/components/sync/OfflineIndicator.tsx"
    click SI_2 "https://github.com/kubiknyc/supersitehero/blob/main/src/components/sync/SyncQueueBadge.tsx"
    click SI_3 "https://github.com/kubiknyc/supersitehero/blob/main/src/components/sync/SyncStatusBar.tsx"
    click SI_4 "https://github.com/kubiknyc/supersitehero/blob/main/src/components/sync/SyncStatusIndicator.tsx"
    click Pages "https://github.com/kubiknyc/supersitehero/tree/main/src/pages"
    click API_CLIENT "https://github.com/kubiknyc/supersitehero/blob/main/src/lib/api/client.ts"
    click API_SVC "https://github.com/kubiknyc/supersitehero/tree/main/src/lib/api/services"
    click API_ERR "https://github.com/kubiknyc/supersitehero/blob/main/src/lib/api/errors.ts"
    click API_HOOKS "https://github.com/kubiknyc/supersitehero/blob/main/src/lib/hooks/useApiCall.ts"
    click API_HOOKS "https://github.com/kubiknyc/supersitehero/blob/main/src/lib/hooks/useMutationWithNotification.ts"
    click State_Z "https://github.com/kubiknyc/supersitehero/blob/main/src/features/daily-reports/store/offlineReportStore.ts"
    click MIG_LOCAL "https://github.com/kubiknyc/supersitehero/tree/main/migrations/"
    click MIG_CLI "https://github.com/kubiknyc/supersitehero/tree/main/supabase/migrations/"
    click CD1 "https://github.com/kubiknyc/supersitehero/blob/main/auto-deploy.js"
    click CD2 "https://github.com/kubiknyc/supersitehero/blob/main/deploy.js"
    click CD3 "https://github.com/kubiknyc/supersitehero/blob/main/run-migrations.py"
    click CD4 "https://github.com/kubiknyc/supersitehero/blob/main/deploy-migration.js"

    %% Styles
    classDef frontend fill:#E0F2FE,stroke:#0284C7,stroke-width:2px
    classDef offline fill:#FEF3C7,stroke:#D97706,stroke-width:2px
    classDef api fill:#D1FAE5,stroke:#059669,stroke-width:2px
    classDef backend fill:#FFEDD5,stroke:#EA580C,stroke-width:2px
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:2px
```
