GRC Data Model & Form Standards

This skill provides comprehensive guidance for working with the local-city-places codebase, covering GRC certificate inventory management, form field patterns, server-side pagination, and table layout standards.

Instructions

When working with this codebase, follow these guidelines in order:

1. GRC Data Model Understanding

**Before modifying any GRC-related code**, understand the critical two-table flow:

**Tables:**

`grcPurchases` - Tracks merchant inventory purchases (created when merchant submits purchase order)

`grcs` - Individual certificates issued to customers (created when merchant issues GRC to customer)

**Flow:**

1. Merchant purchases GRCs → Creates `grcPurchases` record with `paymentStatus: "pending"`

2. Admin approves payment → Updates `grcPurchases.paymentStatus` to `"confirmed"` (does NOT create grcs records)

3. Merchant issues GRC to customer → Creates `grcs` record linked to customer, inventory decreases

**Inventory Calculation:**

```typescript

available = sum(grcPurchases.quantity where confirmed) - count(grcs)

```

**Critical Rule:** The `grcs` table should ONLY contain certificates issued to customers. Never pre-create GRC records at approval time - they are created on-demand when a merchant issues to a customer.

2. Form Field Patterns

**Label Spacing:**

Labels have `mb-2` bottom margin built-in

Use `space-y-4` on form/parent container for field spacing

**Required Fields:**

Mark with `*` in label text: `<Label>Email *</Label>`

**Structure:**

```tsx

<div>

<Label htmlFor="email">Email *</Label>

<p className="text-xs text-muted-foreground mt-1">Helper text</p>

</div>

```

**City/State Fields:**

Always combine into single UI field displayed as "City, State" (e.g., "Denver, CO")

Store separately in database: `city` (varchar 100) and `state` (varchar 2, uppercase)

Use `parseCityState()` helper to split input

Format combined for display when loading from API

```tsx

const [cityState, setCityState] = useState("");

function parseCityState(value: string): { city: string; state: string } {

const parts = value.split(",").map(p => p.trim());

if (parts.length >= 2) {

const state = parts[parts.length - 1].toUpperCase().slice(0, 2);

const city = parts.slice(0, -1).join(", ");

return { city, state };

}

return { city: value.trim(), state: "" };

}

// UI

<Input id="cityState" placeholder="City, State" value={cityState} onChange={(e) => setCityState(e.target.value)} />

```

**Phone Number Fields:**

UI format: `(425) 451-8599`

Database storage: `4254518599` (digits only)

Use utilities from `/src/lib/utils.ts`:

```tsx

import { formatPhoneNumber, stripPhoneNumber } from "@/lib/utils";

// On input

<Input type="tel" value={phone} onChange={(e) => setPhone(formatPhoneNumber(e.target.value))} placeholder="(425) 451-8599" />

// On submit

phone: stripPhoneNumber(phone) || null

```

3. Preventing Layout Shift (CLS)

Reserve space for asynchronously loaded content:

```tsx

// Use fixed min-height to prevent shift

{isLoading ? "Loading..." : items.map(...)}

</div>

```

**Common patterns:**

Inventory chips: `min-h-[32px]`

Tables: Use `table-fixed` with `<colgroup>` for fixed column widths

Images: Always set `width` and `height` attributes

4. Server-Side Pagination Pattern

**API Endpoints:**

Support these query params:

`page` (default: 1)

`limit` (default: 20, max: 100)

`status` (optional filter)

`search` (optional search query)

Response format:

```json

{

"data": [...],

"pagination": {

"total": 150,

"page": 1,

"limit": 20,

"totalPages": 8

}

```

**Implementation (Drizzle):**

```typescript

const page = Math.max(1, parseInt(searchParams.get("page") || "1"));

const limit = Math.min(100, Math.max(1, parseInt(searchParams.get("limit") || "20")));

const offset = (page - 1) * limit;

const [{ count }] = await db.select({ count: sql<number>`count(*)` }).from(table).where(whereClause);

const totalPages = Math.ceil(count / limit);

const data = await db.select().from(table).where(whereClause).limit(limit).offset(offset);

return { data, pagination: { total: count, page, limit, totalPages } };

```

**Frontend:**

```tsx

import { Pagination } from "@/components/ui/pagination";

```

**Key patterns:**

Reset page to 1 when filters/search change

Debounce search input (300ms)

Pass filters to API, don't filter client-side

5. Table Layout Standards

**Page Structure Order:**

1. PageHeader (title + description)

2. Stats Row (2x2 mobile, 4-col desktop)

3. Search Input

4. Filter Tabs (+ Refresh button right-aligned)

5. Table/Cards

6. Pagination

**Responsive Pattern:**

Desktop (md+) uses `table-fixed`, mobile uses cards:

```tsx

{/* Mobile */}

{items.map(item => <MobileCard key={item.id} />)}

</div>

{/* Desktop */}

</colgroup>

</table>

```

**Loading Behavior:**

Table headers always visible

Empty tbody while loading

Refresh button shows spinner

Pagination disabled while loading

**Stats Cards (Compact):**

```tsx

<span className="text-xs sm:text-sm">Label</span>

</div>

<div className="text-lg sm:text-2xl font-bold">{count}</div>

<div className="text-xs sm:text-sm text-muted-foreground">{subtext}</div>

</div>

```

**State Management:**

```tsx

const [items, setItems] = useState([]);

const [isLoading, setIsLoading] = useState(true);

const [filter, setFilter] = useState("pending");

const [searchQuery, setSearchQuery] = useState("");

const [debouncedSearch, setDebouncedSearch] = useState("");

const [page, setPage] = useState(1);

// Debounce search

useEffect(() => {

const timer = setTimeout(() => { setDebouncedSearch(searchQuery); setPage(1); }, 300);

return () => clearTimeout(timer);

}, [searchQuery]);

// Filter change resets page

const handleFilterChange = (newFilter) => { setFilter(newFilter); setPage(1); };

// Fetch with dependencies

const fetchData = useCallback(async () => {

setIsLoading(true);

const params = new URLSearchParams({ page: page.toString(), limit: "20" });

if (filter !== "all") params.set("status", filter);

if (debouncedSearch) params.set("search", debouncedSearch);

const res = await fetch(`/api/endpoint?${params}`);

const data = await res.json();

setItems(data.items);

setIsLoading(false);

}, [page, filter, debouncedSearch]);

useEffect(() => { fetchData(); }, [fetchData]);

```

6. Environment & Deployment

**Vercel Environment Variables:**

Use `printf` instead of `echo` to avoid trailing newline:

```bash

printf "my-api-key" | vercel env add VAR_NAME production

```

**Authentication:**

JWT tokens in cookies (30-day expiry). Required env var: `JWT_SECRET`

Examples

**Example 1: Implementing GRC Purchase Approval**

When admin approves a GRC purchase:

Update `grcPurchases.paymentStatus` to `"confirmed"`

Do NOT create records in `grcs` table

Records in `grcs` are created later when merchant issues to customer

**Example 2: Creating a Paginated Table**

Follow the 6-part page structure, use server-side pagination with debounced search, responsive table/cards pattern, and proper loading states.

**Example 3: Adding City/State Field to Form**

Use single combined input, parse on submit with `parseCityState()`, store separately in database, combine when loading from API.

Constraints

Never pre-create GRC records in `grcs` table during approval

Always use `formatPhoneNumber`/`stripPhoneNumber` for phone fields

Always combine city/state into single UI field

Always use server-side pagination for lists

Always reserve space for loading content to prevent CLS

Always use `printf` not `echo` for Vercel env vars

GRC Data Model & Form Standards

GRC Data Model & Form Standards

Instructions

1. GRC Data Model Understanding

2. Form Field Patterns

3. Preventing Layout Shift (CLS)

4. Server-Side Pagination Pattern

5. Table Layout Standards

6. Environment & Deployment

Examples

Constraints

Reviews (0)