Improve docs: accurate batch/worker flow, architecture & deployment guides#782
Improve docs: accurate batch/worker flow, architecture & deployment guides#782cmraible wants to merge 1 commit into
Conversation
…uides - Rewrite AGENTS.md request flow to reflect the default batch mode (Pub/Sub publish -> worker enrich -> Tinybird) plus synchronous proxy mode; correct the salt-store default and module map; group and complete the environment variable reference. - Add a Run modes section to the README distinguishing batch vs proxy. - Add docs/architecture.md with a Mermaid diagram of the batch pipeline, Pub/Sub, salt-store adapters, and OpenTelemetry setup. - Add docs/deployment.md documenting the Cloud Run deploy pipeline, deploy-staging label flow, and rollback.
WalkthroughThe changes expand runtime documentation for batch and proxy modes, architecture modules, request flows, configuration, Pub/Sub, salt storage, and observability. They add deployment documentation covering release workflows, Cloud Run environments, image publishing, health checks, staging deployments, rollback, CI, cleanup, and local releases. The README links these new architecture and deployment references. Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/deployment.md (1)
69-71: 🗄️ Data Integrity & Integration | 🔵 Trivial | 🏗️ Heavy liftMake the rollback scope explicit for the worker.
Normal deployments update both
analyticsandworker, but rollback currently documents onlyanalytics. Unless mixed-version operation is verified as compatible, operators can leave the ingest and worker services on different image versions; either roll back both or document the compatibility requirement and residual worker version.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/deployment.md` around lines 69 - 71, Update the rollback documentation around the rollback.yml section to explicitly cover the worker service: state whether rollback redeploys both analytics and worker, or document the required compatibility of mixed versions and identify the worker version that remains active. Align the wording with the actual workflow behavior and avoid implying analytics-only rollback without this operational detail.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture.md`:
- Around line 46-48: Specify a text/plaintext language identifier on the
service-name pattern code fence in docs/architecture.md lines 46-48 and the
Cloud Run service-name pattern code fence in docs/deployment.md lines 46-48;
leave the fenced content unchanged.
In `@docs/deployment.md`:
- Line 27: Update the “Bump Version” step description in the deployment
documentation to clarify that GH_PAT authorizes the push and tag only; remove
the implication that it allows the push to re-trigger CI or downstream
workflows, since the commit uses [skip ci] and Docker Hub is dispatched
explicitly by the following job.
---
Nitpick comments:
In `@docs/deployment.md`:
- Around line 69-71: Update the rollback documentation around the rollback.yml
section to explicitly cover the worker service: state whether rollback redeploys
both analytics and worker, or document the required compatibility of mixed
versions and identify the worker version that remains active. Align the wording
with the actual workflow behavior and avoid implying analytics-only rollback
without this operational detail.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3d7bf026-fa6b-4bca-8fd1-b7df3f734228
📒 Files selected for processing (4)
AGENTS.mdREADME.mddocs/architecture.mddocs/deployment.md
|
|
||
| Notes: | ||
| - **HMAC validation** ([`src/plugins/hmac-validation.ts`](../src/plugins/hmac-validation.ts)) is a global `preValidation` hook. It validates the signature and timestamp carried in the URL query parameters and strips them before downstream processing. It is skipped entirely if `HMAC_SECRET` is unset, and it can be run in log-only mode with `HMAC_VALIDATION_LOG_ONLY=true`. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Specify languages for the documentation code fences.
Both fenced blocks omit a language identifier, triggering Markdownlint MD040.
docs/architecture.md#L46-L48: usetextorplaintextfor the service-name pattern block.docs/deployment.md#L46-L48: usetextorplaintextfor the Cloud Run service-name pattern block.
📍 Affects 2 files
docs/architecture.md#L46-L48(this comment)docs/deployment.md#L46-L48
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture.md` around lines 46 - 48, Specify a text/plaintext language
identifier on the service-name pattern code fence in docs/architecture.md lines
46-48 and the Cloud Run service-name pattern code fence in docs/deployment.md
lines 46-48; leave the fenced content unchanged.
Source: Linters/SAST tools
|
|
||
| Triggered on every push to `main` (and via manual `workflow_dispatch`). Jobs: | ||
|
|
||
| 1. **Bump Version** — bumps the patch version with `npm version patch` (e.g. `1.2.3 → 1.2.4`), commits it as `vX.Y.Z [skip ci]`, pushes to `main`, and creates + pushes the `vX.Y.Z` git tag. Sends a Slack "new version released" notification. (Uses a `GH_PAT` so the push can re-trigger downstream workflows.) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the workflow-trigger explanation.
This step commits with [skip ci], which suppresses push-triggered workflows. GH_PAT authorizes the push/tag; Docker Hub is dispatched explicitly by the following job. Reword the parenthetical to avoid implying that this push re-triggers CI or deployment.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/deployment.md` at line 27, Update the “Bump Version” step description in
the deployment documentation to clarify that GH_PAT authorizes the push and tag
only; remove the implication that it allows the push to re-trigger CI or
downstream workflows, since the commit uses [skip ci] and Docker Hub is
dispatched explicitly by the following job.
1 participant
Summary
First PR of the repo-audit run: documentation. The prior audit found the docs mostly good except AGENTS.md was materially stale — it described a synchronous `PROXY_TARGET` flow, but the service runs in batch mode by default (publish to Pub/Sub → separate worker enriches → forwards to Tinybird).
Changes
Docs-only; no source, config, or workflow changes. Every technical claim was verified against source and the workflow files.
Context
This is step 1 of a full repo-audit (docs → CI trust → settings/rulesets → pnpm → oxlint). Later PRs that change tooling (pnpm, oxlint) will sweep these docs to keep commands current.
🤖 Generated with Claude Code