| 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. Use when this capability is needed. |
| metadata | {"author":"aias"} |
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:
- List images needing alt text:
rcr media list --type=image --alt-text=false --limit=100 --order=recordCreatedAt
- Get item with parent record context:
rcr media get <id> --with-record
Returns media item plus record: { id, title, type, mediaCaption, url }.
- Update:
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 — claim your Tome and manage your conversions.
