> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Quick Reference

> Version: 1.0.0 Last Updated: 2025-12-31 Target Audience: Developers

**Version:** 1.0.0\
**Last Updated:** 2025-12-31\
**Target Audience:** Developers

Quick reference for common development tasks, patterns, and gotchas in Encore Health OS Platform.

***

## Common Commands

### CodeRabbit Review

```bash theme={null}
# Review uncommitted changes
cr-uncommitted

# Full review
cr-review

# Generate markdown report by severity
cr-lovable

# Quick token-efficient review
cr-quick
```

**See:** [CODE\_REVIEW\_PROCESS.md](./CODE_REVIEW_PROCESS.md) for complete workflow

### Build & Test

```bash theme={null}
# Install dependencies
npm ci --legacy-peer-deps

# Run development server
npm run dev

# Run tests
npm test

# Run linter
npm run lint

# Build for production
npm run build
```

### Git Workflow

```bash theme={null}
# Create feature branch
git checkout -b feature/your-feature-name

# Review changes before commit
cr-uncommitted

# Commit changes
git add .
git commit -m "Your commit message"

# Push to remote
git push origin feature/your-feature-name
```

***

## Common Patterns

### Spacing Patterns

**Page Container:**

```tsx theme={null}
import { PageContainer } from '@/shared/components/PageContainer';

<PageContainer spacing="md">
  {/* Content */}
</PageContainer>
```

**Vertical Spacing:**

```tsx theme={null}
<div className="space-y-4 md:space-y-6">
  {/* Items */}
</div>
```

**Grid Spacing:**

```tsx theme={null}
<div className="grid gap-3 md:gap-4 lg:gap-6 md:grid-cols-2">
  {/* Grid items */}
</div>
```

**See:** [SPACING\_AND\_UX\_STANDARDS.md](./SPACING_AND_UX_STANDARDS.md) for complete guide

### Color Tokens

**Semantic Colors:**

```tsx theme={null}
// ✅ CORRECT: Use semantic tokens
<Badge variant="success">Published</Badge>
<div className="bg-warning/10 text-warning-foreground">Warning</div>

// ❌ WRONG: Hardcoded colors
<Badge className="bg-green-500">Published</Badge>
<div className="text-yellow-600">Warning</div>
```

**See:** [SEMANTIC\_COLORS.md](./SEMANTIC_COLORS.md) for complete color reference

### Icon Usage

**Import Pattern:**

```tsx theme={null}
import { IconName } from 'lucide-react';
```

**Size Guidelines:**

* Small: `16px` (w-4 h-4)
* Medium: `20px` (w-5 h-5)
* Large: `24px` (w-6 h-6)

**See:** [ICON\_GUIDE.md](./ICON_GUIDE.md) for complete guide

***

## Common Components

### OverviewPageWrapper

Standardized wrapper for module overview pages with pull-to-refresh:

```tsx theme={null}
import { OverviewPageWrapper } from '@/shared/components';

<OverviewPageWrapper refreshQueryKeys={['hr']}>
  <PageHeader ... />
  <QuickActionsSection ... />
  {/* Stats and widgets */}
</OverviewPageWrapper>
```

### PageContainer

Provides consistent responsive page-level padding.

```tsx theme={null}
import { PageContainer } from '@/shared/components/PageContainer';

<PageContainer spacing="md">
  <h1>Page Title</h1>
  {/* Page content */}
</PageContainer>
```

**Spacing Options:** `sm`, `md`, `lg`

### ResponsiveFormLayout

Responsive column layouts for forms.

```tsx theme={null}
import { ResponsiveFormLayout } from '@/shared/components';

<ResponsiveFormLayout columns={2} spacing="md">
  <FormField />
  <FormField />
</ResponsiveFormLayout>
```

### MobileTableWrapper

Horizontal scroll wrapper for wide tables with visual indicators.

```tsx theme={null}
import { MobileTableWrapper } from '@/shared/components';

<MobileTableWrapper>
  <Table>
    {/* Wide table content */}
  </Table>
</MobileTableWrapper>
```

### PermissionGate

Conditional rendering based on permissions.

```tsx theme={null}
import { PermissionGate } from '@/platform/permissions';

<PermissionGate permission="hr.employees.view">
  <ViewButton />
</PermissionGate>
```

### useCurrentUser Hook

Centralized user authentication hook.

```tsx theme={null}
import { useCurrentUser } from '@/platform/auth';

const { user, userId, isLoading, error } = useCurrentUser();

if (isLoading) return <AppLoadingSkeleton />;
if (error) return <ErrorDisplay error={error} />;
```

***

## Common Gotchas

### ❌ React.lazy for Routes (REQUIRED)

**❌ WRONG:**

```tsx theme={null}
import Dashboard from "./platform/dashboard/Dashboard";

<Route path="/" element={<Dashboard />} />
```

**✅ CORRECT:**

```tsx theme={null}
const Dashboard = lazy(() => import("./platform/dashboard/Dashboard"));

<Suspense fallback={<RouteLoadingSkeleton />}>
  <Route path="/" element={<Dashboard />} />
</Suspense>
```

**Why:** Code splitting improves performance and reduces initial bundle size.

### ❌ Loading States (Never Return Null)

**❌ WRONG:**

```tsx theme={null}
if (loading) return null;
```

**✅ CORRECT:**

```tsx theme={null}
if (loading) return <AppLoadingSkeleton />;
```

**Why:** Prevents layout shift and provides better UX.

### ❌ Permissions Checks

**❌ WRONG:**

```tsx theme={null}
if (user.role === 'org_admin') {
  showEditButton();
}
```

**✅ CORRECT:**

```tsx theme={null}
import { useHasPermission } from '@/platform/permissions';

const canEdit = useHasPermission('hr.employees.edit');
if (canEdit) {
  showEditButton();
}
```

**Why:** Supports granular permissions and V2 system.

### ❌ useCurrentUser Hook (REQUIRED)

**❌ WRONG:**

```tsx theme={null}
useState(() => {
  supabase.auth.getUser().then(({ data }) => {
    if (data.user) setUserId(data.user.id);
  });
});
```

**✅ CORRECT:**

```tsx theme={null}
import { useCurrentUser } from '@/platform/auth';

const { user, userId, isLoading } = useCurrentUser();
```

**Why:** Caches user across component mounts (1 API call vs 162+).

### ❌ Static Supabase Imports (REQUIRED)

**❌ WRONG:**

```tsx theme={null}
useState(() => {
  import('@/integrations/supabase/client').then(({ supabase }) => {
    // ...
  });
});
```

**✅ CORRECT:**

```tsx theme={null}
import { supabase } from '@/integrations/supabase/client';
```

**Why:** Ensures proper module initialization and avoids dynamic import issues.

### ❌ QueryClient Configuration

**❌ WRONG:**

```tsx theme={null}
const queryClient = new QueryClient();
```

**✅ CORRECT:**

```tsx theme={null}
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      gcTime: 10 * 60 * 1000, // 10 minutes
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});
```

**Why:** Optimizes performance and reduces unnecessary network requests.

***

## Quick Links

### Setup & Configuration

* [SETUP\_QUICK\_START.md](./SETUP_QUICK_START.md) - Quick setup guide
* [ENVIRONMENT\_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) - Environment configuration
* [PWA\_SETUP.md](./PWA_SETUP.md) - PWA configuration

### Standards & Patterns

* [UI\_UX\_STANDARDS.md](./UI_UX_STANDARDS.md) - Complete UI/UX guide
* [SPACING\_AND\_UX\_STANDARDS.md](./SPACING_AND_UX_STANDARDS.md) - Spacing patterns
* [SEMANTIC\_COLORS.md](./SEMANTIC_COLORS.md) - Color tokens
* [ICON\_GUIDE.md](./ICON_GUIDE.md) - Icon usage

### Code Quality

* [CODE\_REVIEW\_PROCESS.md](./CODE_REVIEW_PROCESS.md) - Review workflow
* [CODERABBIT\_GUIDE.md](./CODERABBIT_GUIDE.md) - CodeRabbit setup

### Navigation

* [mobile-navigation-guide.md](./mobile-navigation-guide.md) - Mobile navigation
* [breadcrumb-implementation-guide.md](./breadcrumb-implementation-guide.md) - Breadcrumbs

***