System Architecture

Complete overview of Lager Guru's architecture, components, and design patterns.

Overview

Lager Guru is built as a modern, scalable multi-tenant SaaS application using React, TypeScript, and Supabase. The architecture emphasizes security, performance, and maintainability.

High-Level Architecture

graph TB
    subgraph "Client Layer"
        A[React PWA] --> B[Supabase Client]
        A --> C[React Router]
        A --> D[State Management]
    end
    
    subgraph "API Layer"
        B --> E[Supabase API]
        E --> F[PostgreSQL]
        E --> G[Row-Level Security]
        E --> H[Realtime]
        E --> I[Storage]
    end
    
    subgraph "Services"
        J[Routing Engine] --> F
        K[Slotting AI] --> F
        L[Auto Assignment] --> F
    end
    
    subgraph "External"
        M[SSO Providers] --> E
        N[Barcode Scanners] --> A
    end
    
    style A fill:#3b82f6
    style E fill:#10b981
    style F fill:#f59e0b

Technology Stack

Layer	Technology	Purpose
Frontend Framework	React 18	UI components and state management
Language	TypeScript	Type safety and developer experience
Build Tool	Vite	Fast development and optimized builds
Styling	Tailwind CSS	Utility-first CSS framework
UI Components	shadcn/ui	Accessible component library
Backend	Supabase	PostgreSQL, Auth, Realtime, Storage
Database	PostgreSQL 15+	Relational database with RLS
Routing	React Router v6	Client-side routing
State	React Context + React Query	Global and server state
Charts	Recharts	Data visualization
PWA	Workbox	Service workers and offline support

Component Architecture

graph LR
    A[Pages] --> B[Components]
    B --> C[UI Components]
    B --> D[Business Logic]
    D --> E[API Layer]
    E --> F[Supabase]
    
    style A fill:#3b82f6
    style B fill:#10b981
    style E fill:#f59e0b

Layer Responsibilities

1. Pages: Route-level components, layout
2. Components: Reusable business components
3. UI Components: Base UI primitives (shadcn/ui)
4. Business Logic: Domain-specific functions
5. API Layer: Supabase client wrapper
6. Supabase: Backend services

Data Flow

sequenceDiagram
    participant User
    participant Component
    participant API
    participant RLS
    participant Database
    
    User->>Component: User Action
    Component->>API: API Call
    API->>RLS: Check Permissions
    RLS->>Database: Filter by tenant_id
    Database->>RLS: Return Data
    RLS->>API: Authorized Data
    API->>Component: Response
    Component->>User: Update UI

Security Architecture

Multi-Layer Security

graph TB
    A[User Request] --> B[JWT Authentication]
    B --> C[Tenant Context]
    C --> D[RLS Policies]
    D --> E[Database]
    
    F[Service Role] --> E
    
    style B fill:#ef4444
    style D fill:#f59e0b
    style E fill:#10b981

Security Layers

1. Authentication: JWT tokens via Supabase Auth
2. Authorization: Role-based access control
3. Tenant Isolation: Row-Level Security (RLS)
4. Data Validation: Input validation and sanitization
5. Service Role: Secure backend operations only

Multi-Tenant Architecture

Tenant Isolation Strategy

graph LR
    A[Tenant A] --> B[RLS Filter]
    C[Tenant B] --> B
    D[Tenant C] --> B
    B --> E[Shared Database]
    
    style A fill:#3b82f6
    style C fill:#10b981
    style D fill:#f59e0b
    style E fill:#6366f1

Isolation Mechanisms

1. Database Level: RLS policies filter by tenant_id
2. Application Level: Automatic tenant context injection
3. API Level: Tenant validation on all requests
4. UI Level: Tenant context in React Context

Performance Optimization

Caching Strategy

graph TB
    A[Request] --> B{Cache Hit?}
    B -->|Yes| C[Return Cached]
    B -->|No| D[Fetch from DB]
    D --> E[Store in Cache]
    E --> F[Return Data]
    
    style B fill:#3b82f6
    style C fill:#10b981

Optimization Techniques

1. Query Optimization: Indexed queries, batch operations
2. Caching: React Query cache, local storage
3. Lazy Loading: Code splitting, route-based chunks
4. Pre-computation: Distance calculations, route optimization
5. CDN: Static asset delivery

Scalability

Horizontal Scaling

• Database: Supabase handles PostgreSQL scaling
• API: Stateless API allows horizontal scaling
• Frontend: CDN distribution
• Realtime: Supabase Realtime scaling

Vertical Scaling

• Database: PostgreSQL connection pooling
• API: Efficient query patterns
• Frontend: Code splitting and lazy loading

Related Documentation

• Multi-Tenant Architecture - Tenant isolation details
• Database Schema - Database structure
• RLS Policies - Security policies
• Developer Guide - Development practices