Rcr Backend

---
name: rcr-backend
description: Database, API, and integration conventions for Red Cliff Record. Use when working with Drizzle ORM, tRPC routers, database migrations, integration syncs, or media alt-text workflows in this project. Triggers on database queries, API routes, Drizzle v2, tRPC, Zod validation, integration work, or `rcr media` commands.
---

# RCR Backend

Supplements global `typescript-guidelines` skill.

## Drizzle ORM

- **Always use Drizzle v2 query syntax** for reads: `db.query.<table>.findMany/findFirst` (not `db.select().from()`)
  - Provides object-style `where`, built-in `with` for relations, and `columns` selection
- Avoid raw SQL — use query builder APIs instead of `sql` template literals
- Mutations: `db.insert()`, `db.update()`, `db.delete()`
- Always upsert with `.onConflictDoUpdate()` on insertions
- External-source PKs: `integer('id').primaryKey()` (not `serial`)
- Never edit Drizzle meta files (`snapshot.json`, `_journal.json`) — they're generated by `drizzle-kit`

## tRPC

- Routers live in `src/server/api/routers/`
- Zod v4 for input validation
- Client hooks from `src/app/trpc.ts`
- Invalidate queries after mutations

## Integrations

Canonical guide: `INTEGRATIONS.md`.

- Sync logic wrapped by `runIntegration`; exposed via `rcr sync <name>`
- File convention: `types.ts` (Zod schemas), `client.ts` (API client), `sync.ts` (orchestration)
- Respect rate limits; batch where needed; upsert for idempotency

## Database Management

Canonical operations: `README.md` and `src/server/db/db-manager.sh`.

- `bun run db:migrate` / `bun run db:studio` for migrations and inspection
- Never run destructive operations or migrations without explicit user permission

## Agent Workflow: Media Alt Text

The `rcr media` commands support CLI-based alt text updates. Workflow for looped agents:

1. **List** images needing alt text:
   ```bash
   rcr media list --type=image --alt-text=false --limit=100 --order=recordCreatedAt
   ```
2. **Get** item with parent record context:
   ```bash
   rcr media get <id> --with-record
   ```
   Returns media item plus `record: { id, title, type, mediaCaption, url }`.
3. **Update**:
   ```bash
   rcr media update <id> '{"altText": "Description of the image"}'
   ```

**Parallel processing**: pre-assign media IDs per agent to avoid overlap. Parent fetches a batch, splits into chunks, each subagent processes its assigned IDs.

Schema: `media` table has `altText` (nullable), `url`, `type`, `width`, `height`, `recordId` (FK). ~4,090 images total.