# Conventions Scale

> Apply when making architectural decisions, designing endpoints or workers, adding database tables, or changing data-volume behavior.

- Skill: `stella/conventions-scale` (Agent Skill)
- Install (CLI): `npx get-skill add stella/conventions-scale`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stella/conventions-scale/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stella (https://skillmd.com/u/stella)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/stella/conventions-scale

---


# Scalability Conventions

Apply when making architectural decisions, designing endpoints or workers,
adding database tables, or changing data-volume behavior.

## Principle

Design for 2,000–5,000+ lawyers and millions of documents without requiring a
rewrite. Choose the scalable shape when it costs roughly the same. When it is
materially more expensive, isolate the simpler implementation behind a clear
contract so callers do not depend on its limitations.

## Required Shape

- **Tenant isolation.** Stella already uses PostgreSQL RLS plus query-level
  authorization. Every tenant table carries an RLS policy.
  [test: apps/api/src/tests/security/rls-coverage.test.ts]
- **Query-level tenant boundary.** Workspace reads and writes go through
  authorized `scopedDb` and include the tenant boundary in the query. `SafeId`
  and handler permission checks complement RLS; none replaces the others. Root
  DB access is reserved for demonstrated system-level operations with an
  explicit deny-by-default policy. [review]
- **Stateless services.** API processes must work behind a load balancer with N
  replicas. Do not depend on process-local mutable state for ownership, queues,
  locks, required caches, or progress. Use durable queues, database leases,
  compare-and-set transitions, and external caches where appropriate.
  [check: ratchet:module-level-mutable-collections]
- **Bounded background work.** Workers use durable checkpoints, deterministic
  job identity, bounded concurrency, backpressure, and per-item failure records.
  A retry or overlapping run must converge instead of duplicating effects.
  [review]
- **Indexes and access paths.** Add an index with every new request-path filter,
  sort, or join; lead composite indexes with tenant scope. Check the query plan
  for large-table or high-frequency paths rather than inferring performance from
  the schema. [review]
- **Short transactions.** Keep external I/O outside transactions and design for
  an external pooler. Long-running workflows persist progress between short
  transactions. [review]
- **Replaceable providers.** AI, search, object storage, email, conversion, and
  connector providers stay behind typed boundaries. Business logic must not
  depend on one provider's model names, pagination quirks, or retry semantics.
  [review]

## Valkey Usage Doctrine

Valkey runs as a single node today. The code must already tolerate losing it
and must already be legal on a cluster, so growing the deployment (managed
Multi-AZ, then cluster mode) is a connection-module change, not an application
rewrite. Two requirements, each with a named enforcement mechanism.

1. **Valkey holds only ephemeral coordination.** Queue transport, pub/sub
   events, TTL'd counters and caches, short locks. Never a fact that exists
   nowhere else: every value must be reconstructible from PostgreSQL, object
   storage, or the request that produced it. A Valkey flush must degrade the
   system, never corrupt it, and every consumer must have a written degraded
   path (fail open, in-memory fallback, durable replay, or an explicit captured
   error). [test: apps/api/src/lib/redis-outage.test.ts]

Enforced by: `no-restricted-imports` in `oxlint.config.ts` confines
`@/api/lib/redis-client` to a named allowlist of coordination facades, so a
new store cannot appear without review; and
`apps/api/src/lib/redis-outage.test.ts` pins each facade's degraded behavior
against a real client aimed at a closed port.

2. **Every usage is cluster-legal.** A multi-key command or Lua script may only
   touch keys that share one hashtag. No `KEYS`, no numbered databases, no
   `SELECT`. `SCAN` is per-node, so it may only ever be an optimization over a
   durable source of truth, never the only way to find something. Pub/sub
   carries no durability guarantee: a subscriber must tolerate lost,
   duplicated, and out-of-order messages, and reconcile from the database on
   reconnect. [review]

Enforced by: `apps/api/src/lib/redis-keys.ts` builds every non-queue key and
brands the result, so a raw string cannot reach a key position; and the
`require-coordination-key` oxlint rule rejects string literals in the key
argument of a Valkey command outside that module.

**Queue keys are the documented exception.** BullMQ owns its own key layout
under a prefix, and changing that prefix strands every in-flight job. The
prefix therefore flips only at the cluster migration itself, behind a queue
drain. The decision and its drain step are recorded at the connection factory
in `apps/api/src/lib/redis-client.ts`.

## Evidence Before Exceptions

Do not keep a hand-maintained list of today's scale gaps in this skill; it
becomes stale. Inspect live baselines and code instead:

- `bun scripts/perf-hotspots.ts` for current network/query debt;
- affected query plans and table cardinality for database work;
- `scripts/typecheck-baseline.ts` for type-instantiation growth;
- bundle and route network baselines for frontend changes.

When accepting a temporary limitation, record its bound, the replacement
boundary, the signal that triggers migration, and the strongest guard that
prevents new code from making it worse.

