From 7a7c0f543b8e478d04115c5087e377d8011e01a0 Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Wed, 1 Jul 2026 01:28:10 -0400 Subject: [PATCH] chore(docs): document projection runtime boundary Signed-off-by: Yordis Prieto --- docs/README.md | 6 +++++ docs/architecture.md | 64 ++++++++++++++++++++++++++++++++++++++++++++ docs/projections.md | 14 ++++++++++ docs/sidebar.js | 1 + 4 files changed, 85 insertions(+) create mode 100644 docs/architecture.md diff --git a/docs/README.md b/docs/README.md index 7cead2bb10..2751900734 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,12 @@ Find out [what's new](whatsnew.md) in this release to get details on new feature Check the [installation guide](installation.md) for database setup and first-run guidance. +## Architecture direction + +Read the [architecture direction](architecture.md) before expanding database-node features. The project keeps +the core node focused on durable event-log behavior and treats projection execution, rich read models, and +custom query surfaces as external component work by default. + ## Support ### EventStoreDB community diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000000..2b1ac2fc74 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,64 @@ +--- +title: Architecture direction +--- + +# Architecture direction + +TrogonEventStore keeps the database node focused on the durable event log and +the operational work required to keep that log correct, available, and +observable. + +The core node owns: + +- Appending events to streams +- Reading events from streams and `$all` +- Replication and cluster membership +- Storage, scavenging, and archive recovery +- Authentication, authorization, diagnostics, and health +- Native indexes only when they are part of core database read semantics + +This boundary keeps stream ownership simple and leaves room for future storage +and sharding work. Features that need their own compute model, query model, or +serving model should be separate components that consume the database through +subscriptions or reads. + +## Projection execution + +Projection execution is future external component work by default. + +User-defined projection runtimes, rich read models, custom query models, and +parallel projection engines should run outside the database process unless they +become an explicitly accepted native database capability. + +This keeps the node from coupling append/read correctness to user code, +scripting runtimes, read-model storage, or projection-specific checkpoint +semantics. External projection components can scale independently, own their +checkpoint and read-model storage, and fail without taking the database node +with them. + +## System projections + +Built-in system projections are different from a general projection execution +platform. + +System projections such as `$streams`, `$by_category`, `$by_event_type`, +`$by_correlation_id`, and `$stream_by_category` exist for compatibility and +query convenience. They may remain as optional in-node behavior while clients +still depend on those streams. + +New work should avoid expanding system projections into a broader in-node query +or read-model platform. If a capability can be implemented as an external +projection or subscription component, prefer the external boundary. + +## Multi-stream append + +Multi-stream append is not required for the current system projection model. + +Any future design that needs atomic writes across unrelated streams must be +reviewed as a core database semantics decision, not as projection plumbing. That +decision has consequences for stream independence, storage layout, and future +sharding. + +Projection engines that need atomic checkpoint, state, and emitted-event writes +should prefer external checkpointing or component-owned storage unless the core +database explicitly accepts cross-stream write semantics. diff --git a/docs/projections.md b/docs/projections.md index 8fdae9bcbb..e75f6504e6 100644 --- a/docs/projections.md +++ b/docs/projections.md @@ -35,6 +35,12 @@ in the stock market. It's important to remember the types of problems that projections help to solve. Many problems are not a good fit for projections and are better served by hosting another read model populated by a catchup subscription. +::: tip Future direction +TrogonEventStore treats user-defined projection execution as external component work by default. The database +node should stay focused on append, read, replication, storage, and native read semantics. See the +[architecture direction](architecture.md#projection-execution) for the boundary. +::: + ### Continuous querying Projections support the concept of continuous queries. When running a projection you can choose whether the @@ -52,6 +58,10 @@ There are two types of projections in EventStoreDB: - [User-defined JavaScript projections](#user-defined-projections) which you create via the API or the admin UI +System projections are compatibility and query-convenience features. They should not be treated as approval to +grow a general in-node projection runtime. New projection engines, rich read models, and custom query models +belong outside the database process unless they are explicitly accepted as native database behavior. + ### Performance impact Keep in mind that all projections emit events as a reaction to events that they process. We call this effect _write amplification_ @@ -102,6 +112,10 @@ When you start EventStoreDB from a fresh database, these projections are present their statuses returns `Stopped`. You can enable a projection from the Admin UI or through the projection management gRPC surface, which switches the status of the projection from `Stopped` to `Running`. +Use system projections when existing clients depend on the streams they produce. Prefer external projection +components for new read-model workloads, especially when the workload needs custom compute, independent +scaling, or component-owned storage. + ### By category The `$by_category` projection links existing events from diff --git a/docs/sidebar.js b/docs/sidebar.js index 93d4bed80c..5e3bec3653 100644 --- a/docs/sidebar.js +++ b/docs/sidebar.js @@ -3,6 +3,7 @@ module.exports = [ text: "Server Quick Start", children: [ "README.md", + "architecture.md", "whatsnew.md", "installation.md", "usage-telemetry.md"