# src/lib/ - Core Utilities

<!-- Parent: ../AGENTS.md -->

## Overview

Shared utilities and infrastructure layers used across the application.

## Key Files

### Validation Layer (`validations.ts`)

**Purpose**: Input validation and type safety using Zod schemas

- `ProjectInputSchema`: Project data validation (1-10 tags, 1-10 links)
- `WebhookPayloadSchema`: Webhook request validation with API key auth
- `KeywordInputSchema`: Keyword cloud data with visual config
- `ProjectQuerySchema`: Query parameter validation (search, tags, status, pagination)
- `ExternalLinkSchema`: URL validation with http/https protocol check
- `TaskStatusEnum`: Discovery task states (PENDING/IN_PROGRESS/COMPLETED/FAILED)

### Prisma Client (`prisma.ts`)

**Purpose**: Singleton database client pattern

```typescript
import { prisma } from "@/lib/prisma";
```

### Utilities

- `utils.ts`: `cn()` - Tailwind class merging with clsx/twMerge
- `slug.ts`: `generateSlug()` - URL-friendly slug generation (prefers English, max 100 chars)

### GitHub Integration

- `github/api.ts`: `getGitHubStats()` - Fetch repo stats (stars, forks, license) with 5min cache
- `github/badges.ts`: `parseGitHubUrl()`, `getGitHubStarsBadgeUrl()`, `getAllGitHubBadgeUrls()`

## Usage Patterns

**Validation**:

```typescript
import { ProjectInputSchema } from "@/lib/validations";
const validated = ProjectInputSchema.parse(inputData);
```

**Database**:

```typescript
import { prisma } from "@/lib/prisma";
const projects = await prisma.project.findMany();
```

**GitHub Badges**:

```typescript
import { getGitHubBadgesFromLinks } from "@/lib/github/badges";
const { stars } = getGitHubBadgesFromLinks(project.externalLinks);
```

## Key Design Decisions

- Singleton Prisma client prevents connection pool exhaustion in dev
- All enums use Zod for runtime type checking
- API key minimum length: 32 characters
- URL validation enforces http/https protocol only