Repository Quality

How do you know repositories are fast AND predictable?

Speed without consistency is chaos. Consistency without speed is stagnation. The scorecard below grades both — runtime performance AND structural discipline — so you catch drift before it compounds.

Three Families

Family	What It Measures	Why It Matters
Runtime	Query latency, transaction duration, DB calls	Users feel this directly
Consistency	Method presence, ordering, policy compliance	Developers feel this during maintenance
Change Effectiveness	Churn rate, migration safety, review friction	The team feels this across quarters

Runtime SLOs

Measure at the repository method level, not the endpoint level. Endpoints aggregate — repositories reveal.

Metric	p50 Target	p95 Target	p99 Target	Breach Action
Single-row read	< 2ms	< 10ms	< 50ms	Check index coverage
List query (100 row)	< 15ms	< 50ms	< 200ms	Check query plan, add pagination
Write (insert/upsert)	< 5ms	< 25ms	< 100ms	Check constraint overhead
Transaction block	< 20ms	< 80ms	< 300ms	Reduce scope or split
DB calls per request	<= 3	<= 5	<= 8	Consolidate or batch

Consistency Rules

Ten structural checks. Each scores pass (1) or fail (0). Total = consistency percentage.

#	Rule	Checks
1	Method presence	Every repo has findById, findMany, create, update
2	Section ordering	Type imports, then queries, then mutations, then helpers
3	Soft-delete policy	deletedAt IS NULL in every read, or hard-delete with audit log
4	Sort safety	Default ORDER BY on every findMany
5	Transaction readiness	Methods accept db | tx executor parameter
6	Prepared statements	Hot-path reads use .prepare()
7	Error mapping	DB errors map to domain result types, not raw throws
8	Type safety	Zero any in method signatures
9	Mapper policy	Row-to-entity mapping in one place per entity
10	Query builder policy	Composable filters, not string concatenation

Weighted Scorecard

Dimension	Weight	Source
Runtime performance	40%	p50/p95/p99 against SLOs above
Structural consistency	35%	10-rule checklist pass rate
Type integrity	15%	Zero any, zero @ts-ignore in repo layer
Change effectiveness	10%	Churn rate < 15%, migration passes first time

Grading Tiers

Score	Grade	Action
90-100	Gold	Maintain, share as reference
80-89	Acceptable	Minor drift — schedule cleanup
70-79	Drift	Dedicated sprint to remediate
< 70	Refactor	Stop features, fix foundations

Anti-Vanity Rules

Trap	Why It Lies	Use Instead
Average latency	Hides p99 spikes that users remember	Percentile distribution
Lines of code	Conflates complexity with capability	Method count + consistency %
Test count	500 tests testing nothing useful is worse than 50	Mutation score or branch cov
"Zero errors"	Suppressed errors still exist	any count + ts-ignore sum

Analysis Slicing

Cut the scorecard by different axes to find where problems cluster.

Slice	Reveals
By repository	Which entity is the weakest link
By method type	Reads fast but writes slow? Or vice versa
By generator	Scaffold quality vs hand-written quality
By age	Old repos drifting from current standards

Four Buckets

Every repository falls into one of four states. The bucket determines the fix.

State	Runtime	Consistency	Prescription
Fast + consistent	Pass	Pass	Gold standard — extract patterns
Fast + inconsistent	Pass	Fail	Structural refactor (low risk)
Consistent + slow	Fail	Pass	Performance tuning (index, query)
Slow + inconsistent	Fail	Fail	Rewrite candidate — highest priority

Context

• Data Engineering — Repository standards the consistency rules enforce
• Drizzle ORM — Implementation patterns for prepared statements, tx executors, error mapping
• Engineering Quality Benchmarks — Broader thresholds this scorecard feeds into
• Software Development Metrics — Parent: DORA + leading indicators
• Hexagonal Architecture — The pattern that separates repository concerns from domain logic

Questions

When a repository scores gold on consistency but fails runtime SLOs, is the structure helping or hiding the problem?

• Which of the ten consistency rules catches the most violations in your codebase — and does that reveal a training gap or a tooling gap?
• If you grade repositories by age, does quality degrade linearly or does it cliff at a specific point?
• What changes when you measure repository quality per entity rather than per service?