Monorepo consolidation: workspace, shared types, transport plans, docker/swam assets

projection/docs/scaling.md

@@ -0,0 +1,28 @@
+# Scaling & Provisioning
+
+## Consumer Modes
+
+The projection supports two JetStream consumption modes (configured via `PROJECTION_CONSUMER_MODE`):
+
+- `single`: one durable consumer per projection process. Each message is processed once and the projection updates all `view_type`s defined in the manifest for that message.
+- `per_view`: one durable consumer per `view_type`. Each consumer processes all events, but only updates its own `view_type` (checkpoint isolation and independent scaling).
+
+In `per_view` mode, durable names are derived as:
+
+`{PROJECTION_DURABLE_NAME}_{view_type}` (with non `[A-Za-z0-9_-]` replaced by `_`).
+
+## Replica Scaling
+
+To scale replicas, run multiple instances with the same durable name(s):
+
+- `single` mode: all replicas share one durable consumer and work-steal messages from that consumer.
+- `per_view` mode: all replicas share a durable consumer per `view_type`.
+
+## Sharding
+
+JetStream subject filtering does not support “hash/range shard by aggregate_id” on the consumer side.
+
+If strict per-entity ordering is required across replicas, sharding must be encoded in the published subjects (for example `shard.<n>.tenant.<id>.aggregate.<type>.<id>`), and each shard must run with a matching `PROJECTION_SUBJECT_FILTERS` value.
+
+Without subject-based sharding, multiple replicas can process events for the same `view_id` concurrently, which can break projections that depend on ordered read-modify-write updates.
+