System Diagrams

High-Level Request Flow

graph TD
    A[User Browser] --> B[Netlify CDN]
    B --> C[React App]
    C --> D[React Router]
    D --> E[Protected Route Check]
    E --> F{Authenticated?}
    F -->|Yes| G[Page Component]
    F -->|No| H[Auth Page]
    G --> I[TanStack Query]
    I --> J[Supabase Client]
    J --> K[Supabase API]
    K --> L[PostgreSQL]
    K --> M[Edge Functions]
    M --> N[External APIs]
    N --> O[Stripe/Resend]

Data Flow Architecture

graph LR
    subgraph "Frontend"
        A[React Components] --> B[React Query]
        B --> C[Supabase Client]
    end
    
    subgraph "Supabase Backend"
        C --> D[API Gateway]
        D --> E[Row Level Security]
        E --> F[PostgreSQL]
        D --> G[Edge Functions]
        G --> H[External Services]
    end
    
    subgraph "External Services"
        H --> I[Stripe API]
        H --> J[Resend Email]
        H --> K[File Storage]
    end
    
    F --> L[Realtime Engine]
    L --> C

Listing Moderation Workflow

graph TD
    A[Seller Creates Listing] --> B[Status: Draft]
    B --> C[Seller Submits for Review]
    C --> D[Status: Pending]
    D --> E[Admin Reviews Listing]
    E --> F{Approved?}
    F -->|Yes| G[Status: Active]
    F -->|No| H[Status: Rejected]
    H --> I[Admin Adds Comments]
    I --> J[Seller Receives Notification]
    J --> K[Seller Edits Listing]
    K --> C
    G --> L[Visible on Marketplace]
    L --> M[Receives Offers]
    M --> N[Deal Negotiation]

Offer and Deal Flow

graph TD
    A[Buyer Makes Offer] --> B[Offer Status: Pending]
    B --> C[Seller Receives Notification]
    C --> D{Seller Decision}
    D -->|Accept| E[Offer Status: Accepted]
    D -->|Reject| F[Offer Status: Rejected]
    D -->|Counter| G[Seller Counter-Offer]
    G --> H[Buyer Receives Counter]
    H --> D
    E --> I[Transaction Created]
    I --> J[Status: Payment Required]
    J --> K[Buyer Funds Escrow]
    K --> L[Status: Funded]
    L --> M[Due Diligence Period]
    M --> N[Status: DD In Progress]
    N --> O[Asset Handover]
    O --> P[Status: Handover In Progress]
    P --> Q[Buyer Confirms Receipt]
    Q --> R[Status: Buyer Accepts]
    R --> S[Funds Released to Seller]
    S --> T[Status: Completed]
    F --> U[Deal Ends]

Authentication & Authorization Flow

graph TD
    A[User Accesses App] --> B[Check Local Storage]
    B --> C{Valid JWT?}
    C -->|Yes| D[Load User Profile]
    C -->|No| E[Redirect to Auth]
    E --> F[User Logs In]
    F --> G[Supabase Auth]
    G --> H[JWT Generated]
    H --> I[User Role Determined]
    I --> J{Role Check}
    J -->|Admin| K[Admin Routes Enabled]
    J -->|Seller| L[Seller Features Enabled]
    J -->|Buyer| M[Buyer Features Enabled]
    D --> N[Route Guard Check]
    N --> O{Access Allowed?}
    O -->|Yes| P[Render Component]
    O -->|No| Q[Redirect/Error]

Real-time Notification System

graph TD
    A[Database Change] --> B[PostgreSQL Trigger]
    B --> C[Supabase Realtime]
    C --> D[WebSocket Connection]
    D --> E[Frontend Hook]
    E --> F{Critical Event?}
    F -->|Yes| G[Update UI Immediately]
    F -->|No| H[Queue for Polling]
    G --> I[Show Toast Notification]
    I --> J[Update Query Cache]
    H --> K[Admin Polling Hook]
    K --> L[Batch Update UI]
    
    subgraph "Critical Events"
        M[Subscription Changes]
        N[New Offers]
        O[Listing Approvals]
    end
    
    subgraph "Non-Critical Events"
        P[Admin Notifications]
        Q[System Messages]
        R[Background Updates]
    end

Payment Processing Flow

graph TD
    A[User Initiates Payment] --> B[Stripe Checkout Session]
    B --> C[User Completes Payment]
    C --> D[Stripe Webhook]
    D --> E[Supabase Edge Function]
    E --> F[Verify Webhook Signature]
    F --> G{Valid Webhook?}
    G -->|Yes| H[Update Database]
    G -->|No| I[Log Error & Reject]
    H --> J[Update Subscription Status]
    J --> K[Send Confirmation Email]
    K --> L[Trigger Realtime Update]
    L --> M[Frontend Receives Update]
    M --> N[UI Updates Automatically]

File Upload and Storage Flow

graph TD
    A[User Selects File] --> B[Frontend Validation]
    B --> C{Valid File?}
    C -->|No| D[Show Error Message]
    C -->|Yes| E[Upload to Supabase Storage]
    E --> F[Generate Public URL]
    F --> G[Store URL in Database]
    G --> H[Update UI with Image]
    
    subgraph "File Validation"
        I[File Size < 10MB]
        J[Image Format: jpg/png/webp]
        K[Document Format: pdf/doc]
    end
    
    subgraph "Storage Buckets"
        L[listing-images]
        M[user-avatars]
        N[documents]
        O[verification-docs]
    end

ERD: Admin Tables

erDiagram
  PROFILES ||--o{ ADMIN_MESSAGES : recipient_id
  PROFILES ||--o{ ADMIN_LISTING_COMMENTS : admin_id
  PROFILES ||--o{ ADMIN_CONTACT_MESSAGES : sender_id
  LISTINGS ||--o{ ADMIN_LISTING_COMMENTS : listing_id
  LISTINGS ||--o{ ADMIN_MESSAGES : listing_id

  PROFILES {
    uuid id PK
    text email
    text full_name
    text role
  }
  LISTINGS {
    uuid id PK
    uuid seller_id FK
    text title
  }
  ADMIN_MESSAGES {
    uuid id PK
    uuid listing_id FK
    uuid admin_id FK
    uuid recipient_id FK
    text subject
    text message
    timestamptz sent_at
    bool email_sent
    bool notification_sent
  }
  ADMIN_LISTING_COMMENTS {
    uuid id PK
    uuid listing_id FK
    uuid admin_id FK
    text field_key
    text comment
    bool is_resolved
  }
  ADMIN_CONTACT_MESSAGES {
    uuid id PK
    uuid sender_id FK
    text subject
    text message
    text status
  }

ERD: Messaging

erDiagram
  PROFILES ||--o{ CONVERSATION_PARTICIPANTS : user_id
  CONVERSATIONS ||--o{ CONVERSATION_PARTICIPANTS : conversation_id
  CONVERSATIONS ||--o{ MESSAGES : conversation_id
  PROFILES ||--o{ MESSAGES : sender_id
  LISTINGS ||--o{ CONVERSATIONS : listing_id

  CONVERSATIONS {
    uuid id PK
    uuid listing_id FK
    timestamptz created_at
  }
  CONVERSATION_PARTICIPANTS {
    uuid conversation_id FK
    uuid user_id FK
    timestamptz created_at
  }
  MESSAGES {
    uuid id PK
    uuid conversation_id FK
    uuid sender_id FK
    text content
    bool read
    timestamptz created_at
  }

ERD: Subscriptions & Invoices

erDiagram
  PROFILES ||--o{ SUBSCRIPTIONS : user_id
  PROFILES ||--o{ STRIPE_INVOICES : user_id
  PROFILES ||--o{ SUBSCRIPTION_INVOICES : user_id

  SUBSCRIPTIONS {
    uuid id PK
    uuid user_id FK
    text subscription_level
    text subscription_status
    timestamptz current_period_start
    timestamptz current_period_end
  }
  STRIPE_INVOICES {
    uuid id PK
    uuid user_id FK
    text stripe_invoice_id
    numeric amount
    text currency
    text status
    timestamptz created_at
  }
  SUBSCRIPTION_INVOICES {
    uuid id PK
    uuid user_id FK
    text stripe_invoice_id
    numeric amount
    text status
    timestamptz created_at
  }

Subscription and Feature Access

graph TD
    A[User Action] --> B[Check User Subscription]
    B --> C[Query Subscriptions Table]
    C --> D{Active Subscription?}
    D -->|No| E[Free Tier Limits]
    D -->|Yes| F[Check Subscription Level]
    F --> G{Subscription Level}
    G -->|Starter| H[Starter Features]
    G -->|Pro| I[Pro Features]
    E --> J[Limited Features]
    H --> K[Feature Usage Tracking]
    I --> K
    J --> L[Upgrade Prompts]
    K --> M[Database Feature Usage Log]

Error Handling and Recovery

graph TD
    A[Error Occurs] --> B{Error Type}
    B -->|Network| C[Retry with Backoff]
    B -->|Validation| D[Show User Message]
    B -->|Authentication| E[Redirect to Login]
    B -->|Permission| F[Show Access Denied]
    B -->|Server| G[Log Error]
    C --> H{Retry Successful?}
    H -->|Yes| I[Continue Operation]
    H -->|No| J[Show Error Message]
    G --> K[Error Boundary]
    K --> L[Fallback UI]
    D --> M[Form Validation Display]
    E --> N[Auth Flow]
    F --> O[Permission Error UI]

Internationalization Flow

graph TD
    A[App Starts] --> B[Detect User Language]
    B --> C[Load Translation Resources]
    C --> D[Initialize i18next]
    D --> E[User Changes Language]
    E --> F[Update Language Preference]
    F --> G[Store in Local Storage]
    G --> H[Update Database Profile]
    H --> I[Reload Translation Resources]
    I --> J[Re-render Components]
    J --> K[Update Dynamic Content]
    
    subgraph "Translation Sources"
        L[Static Translations]
        M[Database Content]
        N[API Responses]
    end

---

Related Documentation:

• Architecture Overview - Complete technical architecture
• Routing Structure - Route organization and protection
• State Management - Data flow patterns