# Rcr Backend

> 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. Use when this capability is needed.

- Skill: `tomevault-io/rcr-backend` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/rcr-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rcr-backend/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/rcr-backend

---


# 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:generate` to generate migration files (safe for agent)
- `bun run db:studio` for database inspection
- Never run migrations (`bun run db:migrate`, `bunx drizzle-kit migrate`) — always provide the command for the user to run
- Never run destructive operations without explicit user permission
- Backups are named by environment (`prod-{timestamp}.dump`, `dev-{timestamp}.dump`), not database name

## 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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/aias) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->