| name | backend |
| description | Backend architecture patterns. Repository pattern, caching, queues, N+1 prevention, transactions. Triggers: backend, server, database, cache, redis, queue, repository, service. |
| allowed-tools | Read, Bash, Write, Edit, Grep, Glob |
Separate concerns: repositories for data, services for logic, handlers for HTTP.
N+1 queries kill performance. Batch fetch, don't loop.
Cache reads, not writes. Invalidate on mutation.
AgentDB read-start has run. Check existing patterns in codebase.
Identify ORM (Prisma, Drizzle, TypeORM) and cache (Redis, in-memory).
Skill-specific: skills/backend/reference/backend-research.md
-
Identify layer — determine which layer the change touches: handler / service / repository / DB.
(gate: layer is named; no logic crosses two layers in a single function)
-
Repository pattern — abstract all data access behind an interface.
- Interface defines: findById, findAll, create, update, delete.
- Implementation depends on ORM/DB; swap without touching service.
- (gate: no raw DB calls outside repository files)
- Reference: backend-research.md §Repository Pattern Deep Dive
-
Service layer — business logic only; no HTTP, no DB calls.
- Constructor-inject repositories and external services.
- Validate, transform, orchestrate; throw typed errors on failure.
- (gate: no
req/res objects; no supabase/prisma/drizzle imports)
- Reference: backend-research.md §Service Layer Patterns
-
N+1 prevention — before any loop over a result set, check for nested queries.
- Collect IDs → single batch fetch → build Map → attach in-memory.
- Alternative: JOIN in query or DataLoader for GraphQL.
- (gate: zero
await repo.findById calls inside a for/forEach/.map)
- Reference: backend-research.md §N+1 Query Solutions
-
Cache-aside — for read-heavy data: check cache → miss → fetch DB → populate cache.
- Invalidate on every mutation (
redis.del(key) after update/delete).
- TTL: 5 min default; shorter for volatile data.
- (gate: no cache writes on mutation paths; only invalidation)
- Reference: backend-research.md §Caching Strategies
-
Transactions — multi-step mutations must be atomic.
- Use DB transaction block or Supabase RPC for cross-table ops.
- Rollback must be automatic on any error.
- (gate: no two-step mutations without wrapping transaction)
- Reference: backend-research.md §Transactions
-
Error handling — typed error hierarchy; never expose stack traces.
- AppError → NotFoundError / ValidationError / UnauthorizedError.
- Global handler: map known errors to HTTP status; log + return generic 500 for unknown.
- (gate: no raw
Error thrown from service; no stack trace in response body)
- Reference: backend-research.md §Error Handling
-
Retry with backoff — transient failures (network, lock contention) get exponential backoff.
- Max 3 retries; delays: 1 s, 2 s, 4 s.
- (gate: idempotent operations only; never retry mutations without idempotency key)
- Reference: backend-research.md §Retry Pattern
-
Queue pattern — fire-and-forget or deferred work uses a job queue.
- Failed jobs: retry up to maxAttempts, then dead-letter queue.
- (gate: queue is not blocking the HTTP response)
- Reference: backend-research.md §Queue Patterns
<anti_patterns>
Querying in loops. Batch fetch with IN clauses or joins.
SELECT * is wasteful. Select only needed columns.
Multi-step mutations without transactions. All or nothing.
Caching write-heavy data. Cache reads, invalidate on writes.
Business logic in HTTP handlers. Use service layer.
Stack traces to users. Log details, return generic message.
</anti_patterns>
<on_complete>
agentdb write-end '{"skill":"backend","patterns_used":["repository","service","cache-aside"],"n_plus_one_fixed":,"cache_keys":[""]}'
Record patterns applied and performance improvements.
</on_complete>