Skip to content

Document the current real-world limitations of the event-sourcing, load-testing, and chaos-engineering subsystems #1148

Description

@Mystery-CLI

Background

backend/src/eventSourcing/, backend/src/loadTesting/, and backend/src/chaos/ are each substantial, Swagger-documented API surfaces (docs/api-docs per config/swagger.js), but none has a corresponding page under docs/ explaining what they actually do, their current scope, or their known limitations — a reader only has the Swagger request/response shapes and the source code itself to go on.

Problem

  • As identified by several other issues in this batch, each of these subsystems currently has real, non-obvious limitations that aren't discoverable from their API surface alone: event-sourcing state is not currently durable across deploys or shared across task instances; load-testing cannot currently generate genuine concurrent load; chaos-engineering injections are currently bookkeeping-only and don't affect real request handling.
  • Without a documentation page stating this plainly, a future contributor (or an operator trying to use these tools for their stated purpose) has no way to know these limitations exist short of reading the source code as closely as this review did — they could reasonably assume a documented, Swagger-described API does what it appears to do.
  • docs/README.md (per the already-open #1013) is meant to be the documentation map — these three subsystems should have an entry there once written.

Proposed Solution

Add a short guide per subsystem (or one combined "Internal Tooling" guide covering all three) under docs/guides/, describing current scope, known limitations, and linking to the tracked issues that would resolve each limitation once fixed.

Implementation Steps

  1. Write docs/guides/internal-tooling.md (or three separate files if preferred) covering: what each subsystem is meant to do, its current actual behavior/limitations (ephemeral storage, serial-not-concurrent load generation, inert chaos injections), and links to the corresponding tracked issues.
  2. Cross-link from each subsystem's route file's Swagger description field to the new doc, so the limitation is visible from the API documentation itself, not just a separate guide someone has to know to look for.
  3. Register the new guide(s) in docs/README.md's index once that consolidation issue lands.
  4. Revisit and update this documentation as each underlying limitation issue is resolved, so it doesn't go stale in the other direction (claiming a limitation exists after it's been fixed).

Acceptance Criteria

  • A documentation page describes the current real-world scope and limitations of event-sourcing, load-testing, and chaos-engineering.
  • Swagger descriptions for the affected routes link to it.
  • The guide is kept current as underlying issues are fixed.

Notes

This documentation issue is best worked on after (or alongside) the underlying fixes, so it doesn't need a rewrite immediately after being written — but even documenting the current state has standalone value for anyone using these tools today.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backenddocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions