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

Bounded reads. Never return or scan an unbounded growing collection in a request or repair job. List endpoints accept a normalized limit and opaque cursor and return Page<T> from apps/api/src/lib/pagination.ts: { items, nextCursor, limit }. Offset pagination, totalCount, and unbounded lists require explicit justification.

Tenant isolation. Stella already uses PostgreSQL RLS plus query-level authorization. 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.

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.

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.

Streaming and batching. Stream large files and exports; do not buffer them entirely in memory. Batch database and remote operations and avoid per-row network/query fan-out. Put explicit ceilings on batch size, payload size, parallelism, retries, and execution time.

Configuration-owned limits. Growing-domain limits live in the owning slice's named configuration or shared limit primitives, not as scattered magic numbers. Defaults, hard ceilings, and normalized server-applied values must be distinguishable.

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.

Short transactions. Keep external I/O outside transactions and design for an external pooler. Long-running workflows persist progress between short transactions.

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.

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

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. Keys carry a {hashtag} naming the colocation unit; 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.

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.