fix: updated diagrams and docs

[HardMax71]

---

Summary by cubic

Updated system diagram and docs: middleware order with CORS/CSRF (frontend header), rate-limit config via TOML, declarative Beanie indexes, new /admin/executions route, uv run command, and tracing OTLP + K8s CPU request defaults.

^{Written for commit a22c331. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Updated middleware docs: reordered middleware stack, added CSRF protection details, frontend token injection behavior, and CSRF metrics.
  • Added admin route for execution management.
  • Switched tracing docs from Jaeger to OTLP endpoint and adjusted sampling/default notes; updated pod CPU request default.
  • Revised schema management docs to declarative, idempotent index model.
  • Clarified rate-limiting configuration source and adjusted worker debug command example.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates across architecture, components, frontend, and configuration: middleware stack reordered with MetricsMiddleware outermost and CSRF protection documented; schema management moved from migrations to declarative per-document indexes via Beanie; worker debug command prefixed with uv run; new admin executions route added; rate-limiting described as TOML-configured; tracing moved from Jaeger to OTLP and pod CPU request adjusted.

Changes

Cohort / File(s)	Summary
Architecture — Middleware & Rate Limiting docs/architecture/middleware.md, docs/architecture/rate-limiting.md	Reordered middleware stack (MetricsMiddleware outermost); added CSRF Protection section (double-submit cookie, token issuance, validation, safe-method exemptions, frontend interceptor behavior); rate-limiting config source clarified as TOML.
Schema Management docs/components/schema-manager.md	Replaced migrations-based SchemaManager with declarative per-document indexes/validators using Beanie (init_beanie idempotent index creation); removed migrations, schema_versions tracking, and schema_manager references; updated startup and rebuild guidance.
Workers docs docs/components/workers/index.md	Updated debugging command to uv run python -m workers.run_saga_orchestrator.
Frontend Routing docs/frontend/routing.md	Added admin route /admin/executions → AdminExecutions.svelte; requires auth and admin.
Configuration Reference docs/reference/configuration.md	Kubernetes pod CPU request changed (1000m → 200m); tracing config switched from Jaeger keys to OTLP_TRACES_ENDPOINT; TRACING_SAMPLING_RATE default adjusted in config.toml to 1.0 (code default note remains).

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Browser
participant FrontendInterceptor
participant APIServer
participant Metrics
Browser->>FrontendInterceptor: User action (login / request)
FrontendInterceptor->>Browser: Reads CSRF cookie
FrontendInterceptor->>APIServer: Send request with X-CSRF-Token header
APIServer->>APIServer: CSRF Middleware validates token (double-submit)
APIServer->>Metrics: Emit request / CSRF metric
APIServer-->>FrontendInterceptor: Response (token refresh on login if set)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• chore: better documentation about workers #61: Overlapping edits to workers and component docs (workers/index.md, routing.md, schema-manager.md).
• chore: reorganize docs with snippet references and diagrams #59: Related middleware and CSRF documentation changes in docs/architecture/middleware.md.

Poem

🐰
I hopped through docs with nimble feet,
Stacked metrics high and guarded the fleet,
Tokens tucked in cookie’s nest,
Indexes declared for tidy rest,
A tiny route for admin to greet. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'fix: updated diagrams and docs' is overly vague and generic. It does not convey specific information about the substantive changes such as CSRF middleware documentation, schema management refactoring, rate limiting configuration updates, or Kubernetes/tracing defaults.	Provide a more descriptive title that highlights the primary change, such as 'docs: document CSRF middleware stack and update configuration references' or 'docs: refactor schema management and update infrastructure documentation'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/general_schema

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 1 file

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/reference/configuration.md (1)

110-110: Clarify “Default” vs “example in config.toml” wording.

This line currently reads like both “no default” and “has a default.” Consider explicitly splitting as “code default: none” and “config.toml default: http://jaeger:4317” to avoid operator confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/configuration.md` at line 110, The table row for
OTLP_TRACES_ENDPOINT is ambiguous about defaults; update the entry for
`OTLP_TRACES_ENDPOINT` so it clearly shows two distinct defaults: "code default:
none" (or "no default") and "config.toml example/default: `http://jaeger:4317`",
e.g., replace the current cell text with something like "code default: none;
config.toml default/example: `http://jaeger:4317`" so readers cannot confuse the
absence of a runtime default with the example value in config.toml.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture/middleware.md`:
- Around line 90-93: Update the CSRF section to document the double-submit
cookie pattern used by CSRFMiddleware: specify that the server issues two
cookies—an httpOnly access_token cookie and a readable csrf_token cookie—and
that mutating requests (POST/PUT/DELETE) must include the csrf_token value in
the X-CSRF-Token header; note GET and safe methods are exempt. Mention the
frontend behavior: files matching frontend/src/**/*.{ts,svelte} auto-inject
authStore.csrfToken into the X-CSRF-Token header for non-GET requests and that
implementations must read the csrf_token cookie and send it in the header to
match CSRFMiddleware validation. Ensure the doc references the exact symbols:
CSRFMiddleware, access_token, csrf_token, X-CSRF-Token, and authStore.csrfToken.

---

Nitpick comments:
In `@docs/reference/configuration.md`:
- Line 110: The table row for OTLP_TRACES_ENDPOINT is ambiguous about defaults;
update the entry for `OTLP_TRACES_ENDPOINT` so it clearly shows two distinct
defaults: "code default: none" (or "no default") and "config.toml
example/default: `http://jaeger:4317`", e.g., replace the current cell text with
something like "code default: none; config.toml default/example:
`http://jaeger:4317`" so readers cannot confuse the absence of a runtime default
with the example value in config.toml.

---

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d9f86f9 and b383120.

⛔ Files ignored due to path filters (1)

• docs/assets/images/system_diagram.svg is excluded by !**/*.svg

📒 Files selected for processing (6)

• docs/architecture/middleware.md
• docs/architecture/rate-limiting.md
• docs/components/schema-manager.md
• docs/components/workers/index.md
• docs/frontend/routing.md
• docs/reference/configuration.md

[cubic-dev-ai]

5 issues found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/architecture/middleware.md">

<violation number="1" location="docs/architecture/middleware.md:11">
P2: The documented "outermost first" middleware order is reversed; `CORSMiddleware` should be listed before `MetricsMiddleware` for actual request-entry order.</violation>

<violation number="2" location="docs/architecture/middleware.md:92">
P2: The CSRF documentation omits `PATCH`, but the middleware validates CSRF tokens for PATCH requests too.</violation>

<violation number="3" location="docs/architecture/middleware.md:92">
P2: The CSRF protection documentation is incomplete and could lead to incorrect implementations. The actual CSRF mechanism uses a double-submit cookie pattern: an `httpOnly` `access_token` cookie, a readable `csrf_token` cookie, and the `X-CSRF-Token` header — all three are required on state-changing requests. Only mentioning the header omits critical details about the cookie components of the protection scheme.</violation>
</file>

<file name="docs/components/schema-manager.md">

<violation number="1" location="docs/components/schema-manager.md:9">
P2: The docs claim Beanie `Settings` declaratively defines MongoDB validators, but the codebase only defines indexes there. This is inaccurate documentation.</violation>

<violation number="2" location="docs/components/schema-manager.md:11">
P2: The docs incorrectly state that MongoDB documents define a TTL index for idempotency keys; idempotency is stored in Redis, not MongoDB documents.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud