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

# Coding Conventions

> File naming, import patterns, state management, and code organization rules

# Coding Conventions

This page covers the coding standards and conventions used throughout the HostMetrics codebase. All contributors should follow these rules to maintain consistency.

## File Naming

| Type             | Convention                        | Example                                |
| ---------------- | --------------------------------- | -------------------------------------- |
| Components       | `PascalCase.tsx`                  | `StatCard.tsx`, `TripTable.tsx`        |
| Hooks            | `useCamelCase.ts`                 | `useBookings.ts`, `useKPIs.ts`         |
| Utilities        | `camelCase.ts`                    | `dateUtils.ts`, `formatters.ts`        |
| Database modules | `camelCase.ts` or `kebab-case.ts` | `partners.ts`, `import-service.ts`     |
| Test files       | `Name.test.tsx` or `name.test.ts` | `StatCard.test.tsx`, `useKPIs.test.ts` |

## Import Path Alias

All imports use the `@/` alias which maps to `src/`:

```typescript theme={null}
// Correct - use the alias
import { cn } from "@/lib/utils";
import { trips } from "@/lib/db";
import { useAuth } from "@/components/auth/AuthProvider";
import { Button } from "@/components/ui/button";

// Incorrect - never use relative paths across module boundaries
import { cn } from "../../../lib/utils";
```

## Client vs Server Components

Next.js App Router defaults to server components. Add the `'use client'` directive only for interactive components that need browser APIs, hooks, or event handlers:

```tsx theme={null}
'use client';

import { useState } from "react";
import { Button } from "@/components/ui/button";

export function InteractiveWidget() {
  const [open, setOpen] = useState(false);
  return <Button onClick={() => setOpen(true)}>Open</Button>;
}
```

Server components (no directive needed) are used for pages that only fetch and render data.

## Conditional Class Merging

Use the `cn()` utility from `@/lib/utils` for conditional Tailwind classes. This wraps `clsx` and `tailwind-merge`:

```tsx theme={null}
import { cn } from "@/lib/utils";

<div className={cn(
  "px-4 py-2 rounded-lg",
  isActive && "bg-[#f0f5ed] text-[#6b7c5c]",
  isDisabled && "opacity-50 cursor-not-allowed"
)}>
  {label}
</div>
```

## TypeScript Strict Mode

The project uses TypeScript in strict mode. All new code must:

* Define explicit types for function parameters and return values
* Avoid `any` — use `unknown` with type narrowing when the type is truly unknown
* Define interfaces/types in `src/lib/db/schema/` for database entities
* Use generics where appropriate for reusable utilities

```typescript theme={null}
// Correct
export async function getTrip(id: string): Promise<Trip | null> {
  // ...
}

// Incorrect
export async function getTrip(id: any) {
  // ...
}
```

## Component Composition

Prefer composition over prop drilling. Pass children or render props instead of threading data through many layers:

```tsx theme={null}
// Preferred - composition
<Card>
  <CardHeader title="Fleet Stats" />
  <CardBody>
    <StatGrid stats={stats} />
  </CardBody>
</Card>

// Avoid - prop drilling
<Card title="Fleet Stats" stats={stats} renderStat={...} onStatClick={...} />
```

## State Management

HostMetrics does not use a global state library. State is managed with:

* **React hooks** (`useState`, `useReducer`) for local component state
* **React Context** (`useAuth`, etc.) for cross-cutting concerns like auth
* **Custom hooks** (`useKPIs`, `useBookings`, etc.) for data fetching and business logic
* **Supabase Realtime** for live data updates where needed

```tsx theme={null}
// Auth context — available everywhere via useAuth()
const { user } = useAuth();

// Data hooks — fetch and cache per-component
const { kpis, isLoading } = useKPIs();
const { vehicles } = useVehicles();
```

## Database Access Rules

All database operations live in `src/lib/db/`. Every query **must** filter by `user_id` to enforce row-level data isolation:

```typescript theme={null}
import { getClient, getCurrentUserId } from "./_client";

export async function listTrips() {
  const userId = await getCurrentUserId();
  const { data, error } = await getClient()
    .from("trips")
    .select("*")
    .eq("user_id", userId);

  if (error) throw error;
  return data;
}
```

Never call Supabase directly from components — always go through a `src/lib/db/` module or a hook in `src/hooks/`.

## Code Organization Summary

| What                | Where                                       |
| ------------------- | ------------------------------------------- |
| Page routes         | `src/app/(dashboard)/` or `src/app/(auth)/` |
| React components    | `src/components/{feature}/`                 |
| Base UI primitives  | `src/components/ui/`                        |
| Custom hooks        | `src/hooks/`                                |
| Database operations | `src/lib/db/`                               |
| Schema / types      | `src/lib/db/schema/`                        |
| Utility functions   | `src/lib/`                                  |
| Tests               | `src/__tests__/`                            |

## Error Handling

Database and API errors should be caught and surfaced with meaningful messages:

```typescript theme={null}
const { data, error } = await getClient()
  .from("vehicles")
  .insert(vehicle);

if (error) {
  throw new Error(`Failed to create vehicle: ${error.message}`);
}
```

Hooks should expose an `error` state so components can render appropriate error UI.