Architecture Overview

System Architecture

AcqMarketplace follows a modern, serverless architecture with clear separation of concerns and scalable infrastructure.

Application Layers

1. Presentation Layer (Frontend)

Location: src/ directory
Technology: React 18 + TypeScript + Vite

src/
├── components/          # Reusable UI components
│   ├── ui/             # shadcn/ui base components
│   ├── layout/         # Layout components (Header, Footer, Sidebar)
│   ├── forms/          # Form components and validation
│   ├── admin/          # Admin-specific components
│   │   ├── analytics/  # Analytics dashboard components (refactorized)
│   │   ├── templates/  # Email template components
│   │   └── ...         # Other admin components
│   └── routing/        # Route management
├── pages/              # Page-level components
├── hooks/              # Custom React hooks
│   ├── useAnalytics.ts # Analytics data fetching hook
│   └── ...             # Other custom hooks
├── contexts/           # React Context providers
├── lib/                # Utility functions and configurations
├── integrations/       # External service integrations
└── types/              # TypeScript type definitions

2. API Layer (Backend)

Location: supabase/functions/ directory
Technology: Supabase Edge Functions (Deno runtime)

• RESTful APIs for business logic
• Real-time subscriptions for live updates
• Email service integration
• Payment processing webhooks
• File upload and processing
• AI-powered project analysis (Mistral AI integration)

3. Data Layer

Technology: PostgreSQL via Supabase

• Structured relational data with JSONB for flexibility
• Row Level Security (RLS) for access control + blur policy for sensitive fields (see docs/architecture/blur-policy.md)
• Database functions for complex operations
• Real-time triggers for notifications

4. Authentication & Authorization

Technology: Supabase Auth

• JWT-based authentication
• Role-based access control (buyer/seller/admin)
• Social login support
• Session management

Provider Architecture

The application uses a nested provider pattern defined in src/App.tsx:

// src/App.tsx:32-51
<HelmetProvider>
  <ThemeProvider>
    <DevModeProvider>
      <AuthProvider>
        <TranslationProvider>
          <TooltipProvider>
            <Toaster />
            <Sonner />
            <RealtimeNotifications />
            <DevModeLabel />
            <RouterProvider router={router} />
          </TooltipProvider>
        </TranslationProvider>
      </AuthProvider>
    </DevModeProvider>
  </ThemeProvider>
</HelmetProvider>

Provider Responsibilities

1. HelmetProvider: SEO and document head management
2. ThemeProvider: Dark/light mode theming
3. DevModeProvider: Development debugging utilities
4. AuthProvider: User authentication and session management
5. TranslationProvider: Internationalization (i18n)
6. TooltipProvider: Global tooltip functionality
7. Toaster/Sonner: Notification systems
8. RealtimeNotifications: Real-time event handling

Path Aliases

Configured in vite.config.ts:34:

resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
  },
}

This enables clean imports:

import { Button } from "@/components/ui/button"
import { useAuth } from "@/contexts/AuthContext"
import { supabase } from "@/integrations/supabase/client"

Development Server Configuration

File: vite.config.ts:9-27

Key configurations:

• Host: :: (IPv6, allows external connections)
• Port: 8080
• Proxy: /functions/v1 → http://127.0.0.1:54321 (Supabase local)
• HMR: Error overlay disabled for performance
• File Watching: Optimized with polling disabled

Build Configuration

Development

npm run dev              # Start development server
npm run build:dev        # Build in development mode

Production

npm run build           # Production build with SEO optimization
npm run preview         # Preview production build

Build Optimizations

File: vite.config.ts:37-62

• Dependency Optimization: Pre-bundled React, React-DOM, TanStack Query
• Code Splitting: Automatic route-based splitting
• External Scripts: Build scripts excluded from bundling
• ESBuild: Silent handling of ESM warnings

Real-time Architecture

Global Notifications Hook

File: src/hooks/useGlobalRealtimeNotifications.ts

Critical real-time channels:

1. Subscription Changes: User subscription updates
2. New Offers: Seller receives offer notifications
3. Listing Status: Approval/rejection notifications
4. Email Triggers: Automated email notifications

Channel Strategy

• Single Channel: critical-notifications for performance
• User-Specific Filters: Reduces payload and improves performance
• Performance Optimizations: requestIdleCallback for non-blocking updates

Error Handling Strategy

Frontend Error Boundaries

• Page-level error boundaries for graceful failures
• Form validation with react-hook-form + zod
• Toast notifications for user feedback

Backend Error Handling

• Structured error responses from Edge Functions
• Database constraint violations handled gracefully
• Email delivery failures logged and retried

Caching Strategy

TanStack Query

• Server State Caching: Automatic cache management
• Background Refetching: Stale-while-revalidate pattern
• Optimistic Updates: Immediate UI updates with rollback

Supabase Client

• Connection Pooling: Efficient database connections
• Query Result Caching: Short-term query result caching

Security Architecture

Frontend Security

• Environment Variables: No secrets in frontend code
• XSS Protection: Sanitized user inputs with DOMPurify
• CSRF Protection: SameSite cookie configuration

Backend Security

• Row Level Security: Database-level access control
• JWT Validation: Automatic token verification
• Input Validation: Strict validation on all inputs
• Rate Limiting: Protection against abuse

Monitoring & Observability

Development

• Console Logging: Structured logging with context
• Error Boundaries: Catch and report React errors
• Network Monitoring: Request/response logging

Production

• Supabase Analytics: Database performance monitoring
• Edge Function Logs: Server-side error tracking
• User Analytics: Usage patterns and performance metrics

Deployment Architecture

Static Assets

• Frontend: Deployed to Netlify with CDN
• Build Artifacts: Optimized for fast loading
• Environment Variables: Secure configuration management

Backend Services

• Supabase: Managed PostgreSQL + Edge Functions
• Stripe: Payment processing infrastructure
• Resend: Email delivery service

---

Next Steps:

• System Diagrams - Visual architecture representation
• Routing Structure - Route organization and guards
• State Management - Data flow patterns
• Admin Analytics Refactor - Analytics page refactorization details