docs: add project review findings

[poyrazK]

Summary

• add docs/project-review-findings.md to preserve the architectural and product review findings in the repository
• capture the major trustworthiness, security, reliability, and product gaps identified during the review
• provide a prioritized reference document for future hardening work

Summary by CodeRabbit

• Documentation
  • Added project review findings documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new documentation file was created capturing a comprehensive project review that identifies security, reliability, and correctness issues, including websocket safety concerns, credential management gaps, async reliability problems, and concurrency issues in cron execution.

Changes

Cohort / File(s)	Summary
Documentation docs/project-review-findings.md	Added project review findings documenting critical and high-severity issues across websocket handling, API key credential storage and caching, cache invalidation, async queue reliability, goroutine lifecycle management, and cron job execution concurrency. Includes executive summary, prioritized findings (P0–P2), and assessment of operational trust gaps.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A whisker-twitching truth unfolds,
Of websockets uncontrolled,
Keys exposed in Redis's keep,
While goroutines crash through sleep.
The findings hop from great to small—
Trust's the fortress, build it all! 🔐

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add project review findings' directly and accurately summarizes the main change—adding a new documentation file with project review findings. It is concise, clear, and clearly conveys the primary change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/project-review-findings

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/project-review-findings.md (2)

49-55: Make recommendations directly actionable with ownership + acceptance criteria.

The priority guidance is strong, but execution will be easier if each recommendation includes an owner and a concrete “done” condition.

Suggested structure

 Recommendation:
 - Use one hub instance.
 - Move websocket delivery behind a port instead of importing transport code into services.
 - Scope subscriptions by tenant and possibly user.
 - Stop using query-string API keys.
 - Enforce strict origin validation.
+Owner: Platform Backend
+Done when:
+- Event publish/subscribe uses a single shared hub in production wiring
+- Cross-tenant websocket delivery tests fail closed
+- Websocket auth no longer accepts API keys in query params

Also applies to: 71-76, 89-92, 107-110, 127-131, 148-152, 165-168, 183-186, 199-202, 217-220, 235-239, 257-259, 271-273

🤖 Prompt for AI Agents

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

In `@docs/project-review-findings.md` around lines 49 - 55, Convert each
high-level recommendation (e.g., "Use one hub instance", "Move websocket
delivery behind a port", "Scope subscriptions by tenant and possibly user",
"Stop using query-string API keys", "Enforce strict origin validation") into a
short actionable item that includes an owner (role or team) and a clear
acceptance criterion; for example, for "Use one hub instance" specify the owning
team, the migration plan, and the done condition (all services routed to the
single hub and tests passing), and repeat this pattern for every recommendation
and the other repeated blocks (those same recommendation lines elsewhere) so
each entry has an Owner and a concrete "Done" condition that can be validated.

---

3-3: Add immutable traceability metadata for this review snapshot.

Since this doc relies heavily on file/line references, add commit SHA (and optionally branch) so findings can be mapped back after refactors.

Proposed doc tweak

 Date: 2026-04-04
+Reviewed commit: <git-sha>
+Reviewed branch: main

Also applies to: 16-17

🤖 Prompt for AI Agents

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

In `@docs/project-review-findings.md` at line 3, Add immutable traceability
metadata to the document header by inserting a commit SHA (required) and
optionally a branch name next to the existing Date line (e.g., add "Commit SHA:
<full-sha>" and "Branch: <name>"); update the top section where "Date:
2026-04-04" appears and also apply the same metadata addition to the referenced
secondary location (lines 16-17) so every finding can be mapped back after
refactors.

🤖 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/project-review-findings.md`:
- Line 265: In the sentence referencing authentication within doc.go:54-58,
replace the informal phrasing "still talks about JWT-based authentication" with
a more formal alternative such as "still states JWT-based authentication" (or
similar formal wording) to match the report tone; update any adjacent phrasing
to ensure consistency with the rest of the document's formal register and run a
quick skim of doc.go:54-58 to confirm punctuation and tense align with
surrounding sentences.

---

Nitpick comments:
In `@docs/project-review-findings.md`:
- Around line 49-55: Convert each high-level recommendation (e.g., "Use one hub
instance", "Move websocket delivery behind a port", "Scope subscriptions by
tenant and possibly user", "Stop using query-string API keys", "Enforce strict
origin validation") into a short actionable item that includes an owner (role or
team) and a clear acceptance criterion; for example, for "Use one hub instance"
specify the owning team, the migration plan, and the done condition (all
services routed to the single hub and tests passing), and repeat this pattern
for every recommendation and the other repeated blocks (those same
recommendation lines elsewhere) so each entry has an Owner and a concrete "Done"
condition that can be validated.
- Line 3: Add immutable traceability metadata to the document header by
inserting a commit SHA (required) and optionally a branch name next to the
existing Date line (e.g., add "Commit SHA: <full-sha>" and "Branch: <name>");
update the top section where "Date: 2026-04-04" appears and also apply the same
metadata addition to the referenced secondary location (lines 16-17) so every
finding can be mapped back after refactors.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a7130578-c1f8-4676-9426-06d7b186a99f

📥 Commits

Reviewing files that changed from the base of the PR and between 42f7249 and 2f3037a.

📒 Files selected for processing (1)

• docs/project-review-findings.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Use more formal wording for consistency with the rest of the report.

Replace “still talks about” with a more formal phrase (for example, “still states”).

🧰 Tools

🪛 LanguageTool

[style] ~265-~265: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ...: Low Examples: - doc.go:54-58 still talks about JWT-based authentication, but the runni...

(TALK_ABOUT_DISCUSS)

🤖 Prompt for AI Agents

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

In `@docs/project-review-findings.md` at line 265, In the sentence referencing
authentication within doc.go:54-58, replace the informal phrasing "still talks
about JWT-based authentication" with a more formal alternative such as "still
states JWT-based authentication" (or similar formal wording) to match the report
tone; update any adjacent phrasing to ensure consistency with the rest of the
document's formal register and run a quick skim of doc.go:54-58 to confirm
punctuation and tense align with surrounding sentences.

[Copilot]

Pull request overview

Adds a repository document capturing architectural/product review findings, focused on trustworthiness gaps (security, correctness, reliability) to guide future hardening work.

Changes:

• Introduce docs/project-review-findings.md with prioritized review findings and recommendations.
• Document major risks across realtime/WebSocket, API key handling, async workers/queues, migrations/tests, and multi-tenancy consistency.

---

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

[Copilot]

This document contains detailed, actionable descriptions of critical security/reliability weaknesses (with precise file/line pointers). If this repository is public (or mirrored externally), committing this as-is can materially increase attacker effectiveness. Consider adding an explicit confidentiality / responsible-disclosure note (e.g., "internal-only"), and/or relocating to a private security review artifact or redacting the most exploitable specifics while keeping the prioritized themes.