Developer Guide

Complete guide for developers working on Lager Guru.

Overview

This guide provides everything you need to start developing on Lager Guru, including setup instructions, coding standards, testing practices, and contribution guidelines.

Quick Start

Prerequisites

• Node.js 18+ and npm
• Git
• Supabase account (or local Supabase instance)
• Code editor (VS Code recommended)

Setup Steps

1. Clone Repository

   git clone <repository-url>
   cd lager-guru

2. Install Dependencies

   npm install

3. Environment Setup

   cp .env.example .env.local
   # Edit .env.local with your Supabase credentials

4. Start Development Server

   npm run dev

5. Run Database Migrations

   npx supabase migration up

Project Structure

lager-guru/
├── src/
│   ├── components/       # React components
│   │   ├── admin/        # Admin components
│   │   ├── dashboard/    # Dashboard components
│   │   └── ui/           # UI primitives
│   ├── lib/              # Business logic
│   │   ├── inventory.ts  # Inventory functions
│   │   ├── pickpack.ts   # Pick & Pack functions
│   │   └── routingEngine.ts  # Routing functions
│   ├── pages/            # Route pages
│   ├── contexts/         # React contexts
│   └── hooks/            # Custom hooks
├── supabase/
│   ├── migrations/       # Database migrations
│   └── functions/        # Edge functions
├── docs/                 # Documentation
└── scripts/               # Utility scripts

Coding Standards

TypeScript

• Strict Mode: Always use strict TypeScript
• Types: Define interfaces for all data structures
• No any: Avoid any type, use unknown if needed

// ✅ GOOD
interface InventoryItem {
  id: string;
  sku: string;
  quantity: number;
}

// ❌ BAD
const item: any = { ... };

React Components

• Functional Components: Use function components with hooks
• Props Interface: Define props interface
• Error Boundaries: Wrap components in error boundaries

// ✅ GOOD
interface InventoryListProps {
  items: InventoryItem[];
  onItemClick: (item: InventoryItem) => void;
}

export function InventoryList({ items, onItemClick }: InventoryListProps) {
  // Component logic
}

Database Queries

• Always Filter by Tenant: Every query must include tenant_id filter
• Use RLS: Rely on RLS but also filter explicitly
• Error Handling: Always handle errors

// ✅ GOOD
const tenantId = await getCurrentUserTenantId();
const { data, error } = await supabase
  .from('shipments')
  .select('*')
  .eq('tenant_id', tenantId);

if (error) {
  console.error('Error fetching shipments:', error);
  return;
}

File Naming

• Components: PascalCase (InventoryList.tsx)
• Functions: camelCase (getInventoryItems.ts)
• Constants: UPPER_SNAKE_CASE (MAX_QUANTITY.ts)

Testing

Unit Tests

// tests/lib/inventory.test.ts
import { describe, it, expect } from 'vitest';
import { createItem } from '@/lib/inventory';

describe('createItem', () => {
  it('should create item with correct data', async () => {
    const { data, error } = await createItem({
      sku: 'TEST-001',
      name: 'Test Item',
    });
    
    expect(error).toBeNull();
    expect(data?.sku).toBe('TEST-001');
  });
});

Integration Tests

// tests/integration/pickpack.test.ts
import { describe, it, expect } from 'vitest';
import { createPickList } from '@/lib/pickpack';

describe('Pick & Pack Integration', () => {
  it('should create pick list with optimal route', async () => {
    // Test implementation
  });
});

Multi-Tenant Standards

CRITICAL: Follow Multi-Tenant Standards strictly:

1. ✅ Every table has tenant_id
2. ✅ Every query filters by tenant_id
3. ✅ Every RLS policy checks tenant access
4. ✅ No cross-tenant data exposure
5. ✅ Seeds use service role
6. ✅ Scripts set tenant context

Git Workflow

Branch Naming

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation
• refactor/ - Code refactoring

Commit Messages

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code refactoring
• test: Tests
• chore: Maintenance

Example:

feat(inventory): add low stock alerts

- Add getLowStockItems function
- Add UI component for alerts
- Add tests

Code Review Checklist

Before submitting PR:

• [ ] Code follows TypeScript standards
• [ ] All queries filter by tenant_id
• [ ] RLS policies are correct
• [ ] Tests pass
• [ ] No console.logs in production code
• [ ] Error handling implemented
• [ ] Documentation updated
• [ ] No breaking changes

Related Documentation

• Multi-Tenant Standards - Strict rules
• Architecture - System design
• API Reference - API documentation
• Database Schema - Database structure