Architecture

Overview

Lager Guru is a modern Progressive Web Application (PWA) built with React, TypeScript, and Supabase. It follows a component-based architecture with clear separation of concerns.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Client (Browser)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   React App  │  │  Service     │  │   PWA        │      │
│  │   (Vite)     │  │  Worker      │  │   Manifest   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Supabase Backend                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  PostgreSQL  │  │  Realtime    │  │    Auth      │      │
│  │  Database    │  │  Subscriptions│  │  (JWT)      │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐                         │
│  │  Edge       │  │  Storage     │                         │
│  │  Functions  │  │  (Files)     │                         │
│  └──────────────┘  └──────────────┘                         │
└─────────────────────────────────────────────────────────────┘

Technology Stack

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Vite - Build tool and dev server
• shadcn/ui - Component library
• Tailwind CSS - Styling
• React Router - Client-side routing
• Framer Motion - Animations
• Recharts - Data visualization
• MapLibre GL - Maps
• @zxing/browser - Barcode scanning

Backend

• Supabase - Backend-as-a-Service
  • PostgreSQL database
  • Realtime subscriptions
  • Authentication (JWT)
  • Row-Level Security (RLS)
  • Edge Functions (Deno)

Deployment

• Docker - Containerization
• Nginx - Web server
• GitHub Actions - CI/CD

Project Structure

lager-guru/
├── src/
│   ├── components/        # React components
│   │   ├── admin/        # Admin-specific components
│   │   ├── dashboard/     # Dashboard components
│   │   ├── worker/        # Worker components
│   │   └── ui/            # Reusable UI components
│   ├── contexts/          # React context providers
│   ├── hooks/             # Custom React hooks
│   ├── integrations/      # External service integrations
│   ├── lib/               # Utility functions
│   ├── pages/             # Page components
│   └── config/            # Configuration
├── supabase/
│   ├── migrations/        # Database migrations
│   └── functions/         # Edge Functions
├── public/                # Static assets
├── docs/                  # Documentation
└── scripts/               # Build and utility scripts

Data Flow

Authentication Flow

1. User logs in via Supabase Auth
2. JWT token stored in browser
3. Token sent with all API requests
4. RLS policies enforce access control

Real-time Updates

1. Client subscribes to Supabase Realtime channels
2. Database changes trigger events
3. Client receives updates via WebSocket
4. UI updates automatically

State Management

• React Context - Global state (auth, branding)
• React Query - Server state caching
• Local State - Component-specific state
• Supabase Realtime - Real-time synchronization

Security

Authentication

• JWT-based authentication via Supabase
• Role-based access control (RBAC)
• Row-Level Security (RLS) in database

Network Security

• HTTPS enforced
• Security headers (CSP, HSTS, etc.)
• Internal network restrictions (configurable)

Data Protection

• RLS policies prevent unauthorized access
• Audit logging for sensitive operations
• Input validation and sanitization

Performance

Optimization Strategies

• Code splitting with Vite
• Lazy loading of routes
• Service Worker caching
• Image optimization
• Database query optimization
• RLS policy optimization

Caching

• Service Worker for offline support
• React Query for API response caching
• Browser caching for static assets

Scalability

Horizontal Scaling

• Stateless frontend (can be replicated)
• Supabase handles backend scaling
• Docker containers for easy deployment

Database Scaling

• PostgreSQL with connection pooling
• Indexed queries for performance
• Materialized views for analytics

Deployment Architecture

┌─────────────────┐
│  GitHub Actions │
│  (CI/CD)        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Docker Build   │
│  (GHCR)         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Production     │
│  Server         │
│  ┌───────────┐  │
│  │  Nginx    │  │
│  │  (Port 80)│  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │  Docker   │  │
│  │  Container│  │
│  └───────────┘  │
└─────────────────┘

Design Patterns

Component Patterns

• Container/Presentational - Separation of logic and UI
• Compound Components - Related components working together
• Render Props - Flexible component composition

State Management Patterns

• Context API - Global state
• Custom Hooks - Reusable state logic
• React Query - Server state management

Data Fetching Patterns

• Supabase Client - Direct database queries
• Edge Functions - REST API endpoints
• Realtime Subscriptions - Live data updates

Best Practices

Code Organization

• Feature-based folder structure
• Shared components in ui/
• Type definitions with TypeScript
• JSDoc comments for documentation

Error Handling

• Try-catch blocks for async operations
• Error boundaries for React components
• User-friendly error messages
• Logging for debugging

Testing

• Component testing (to be implemented)
• Integration testing (to be implemented)
• E2E testing (to be implemented)

Future Considerations

• Microservices architecture (if needed)
• GraphQL API layer
• Advanced caching strategies
• CDN for static assets
• Monitoring and observability