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.
- 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.
- 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.
1---2name: conventions-scale3description: "Apply when making architectural decisions, designing endpoints or workers, adding database tables, or changing data-volume behavior."4metadata:5 source: https://skillmd.com/skills/stella/conventions-scale6---78# Scalability Conventions910Apply when making architectural decisions, designing endpoints or workers,11adding database tables, or changing data-volume behavior.1213## Principle1415Design for 2,000–5,000+ lawyers and millions of documents without requiring a16rewrite. Choose the scalable shape when it costs roughly the same. When it is17materially more expensive, isolate the simpler implementation behind a clear18contract so callers do not depend on its limitations.1920## Required Shape2122- **Tenant isolation.** Stella already uses PostgreSQL RLS plus query-level23 authorization. Every tenant table carries an RLS policy.24 [test: apps/api/src/tests/security/rls-coverage.test.ts]25- **Query-level tenant boundary.** Workspace reads and writes go through26 authorized `scopedDb` and include the tenant boundary in the query. `SafeId`27 and handler permission checks complement RLS; none replaces the others. Root28 DB access is reserved for demonstrated system-level operations with an29 explicit deny-by-default policy. [review]30- **Stateless services.** API processes must work behind a load balancer with N31 replicas. Do not depend on process-local mutable state for ownership, queues,32 locks, required caches, or progress. Use durable queues, database leases,33 compare-and-set transitions, and external caches where appropriate.34 [check: ratchet:module-level-mutable-collections]35- **Bounded background work.** Workers use durable checkpoints, deterministic36 job identity, bounded concurrency, backpressure, and per-item failure records.37 A retry or overlapping run must converge instead of duplicating effects.38 [review]39- **Indexes and access paths.** Add an index with every new request-path filter,40 sort, or join; lead composite indexes with tenant scope. Check the query plan41 for large-table or high-frequency paths rather than inferring performance from42 the schema. [review]43- **Short transactions.** Keep external I/O outside transactions and design for44 an external pooler. Long-running workflows persist progress between short45 transactions. [review]46- **Replaceable providers.** AI, search, object storage, email, conversion, and47 connector providers stay behind typed boundaries. Business logic must not48 depend on one provider's model names, pagination quirks, or retry semantics.49 [review]5051## Valkey Usage Doctrine5253Valkey runs as a single node today. The code must already tolerate losing it54and must already be legal on a cluster, so growing the deployment (managed55Multi-AZ, then cluster mode) is a connection-module change, not an application56rewrite. Two requirements, each with a named enforcement mechanism.57581. **Valkey holds only ephemeral coordination.** Queue transport, pub/sub59 events, TTL'd counters and caches, short locks. Never a fact that exists60 nowhere else: every value must be reconstructible from PostgreSQL, object61 storage, or the request that produced it. A Valkey flush must degrade the62 system, never corrupt it, and every consumer must have a written degraded63 path (fail open, in-memory fallback, durable replay, or an explicit captured64 error). [test: apps/api/src/lib/redis-outage.test.ts]6566Enforced by: `no-restricted-imports` in `oxlint.config.ts` confines67`@/api/lib/redis-client` to a named allowlist of coordination facades, so a68new store cannot appear without review; and69`apps/api/src/lib/redis-outage.test.ts` pins each facade's degraded behavior70against a real client aimed at a closed port.71722. **Every usage is cluster-legal.** A multi-key command or Lua script may only73 touch keys that share one hashtag. No `KEYS`, no numbered databases, no74 `SELECT`. `SCAN` is per-node, so it may only ever be an optimization over a75 durable source of truth, never the only way to find something. Pub/sub76 carries no durability guarantee: a subscriber must tolerate lost,77 duplicated, and out-of-order messages, and reconcile from the database on78 reconnect. [review]7980Enforced by: `apps/api/src/lib/redis-keys.ts` builds every non-queue key and81brands the result, so a raw string cannot reach a key position; and the82`require-coordination-key` oxlint rule rejects string literals in the key83argument of a Valkey command outside that module.8485**Queue keys are the documented exception.** BullMQ owns its own key layout86under a prefix, and changing that prefix strands every in-flight job. The87prefix therefore flips only at the cluster migration itself, behind a queue88drain. The decision and its drain step are recorded at the connection factory89in `apps/api/src/lib/redis-client.ts`.9091## Evidence Before Exceptions9293Do not keep a hand-maintained list of today's scale gaps in this skill; it94becomes stale. Inspect live baselines and code instead:9596- `bun scripts/perf-hotspots.ts` for current network/query debt;97- affected query plans and table cardinality for database work;98- `scripts/typecheck-baseline.ts` for type-instantiation growth;99- bundle and route network baselines for frontend changes.100101When accepting a temporary limitation, record its bound, the replacement102boundary, the signal that triggers migration, and the strongest guard that103prevents new code from making it worse.