fix: sync docs with codebase

[ankurs]

Summary

• Fix startup sequence order in architecture page (handlers register before servers start)
• Expand shutdown sequence to match actual code across architecture, production, and signals pages (add admin server step, force-stop step)
• Correct options API names in context propagation section (Set/Get → AddToOptions/FromContext)
• Add admin port to deployment topology diagram
• Add missing options package to Packages page
• Fix Sentry env var RELEASE → RELEASE_NAME in integrations page
• Add link to full interceptor chain from simplified homepage diagram

Test plan

• All 59 Playwright tests pass
• Verified corrected API names against options/options.go
• Verified startup/shutdown sequences against core/core.go

Summary by CodeRabbit

• Documentation
  • Added link to full interceptor chain and highlighted timeout, rate limiting, debug logging, and New Relic.
  • Documented a request-scoped Options package for passing metadata between layers.
  • Updated deployment topology to support an optional admin port for metrics/docs/profiling.
  • Clarified startup and graceful shutdown sequences, including a configurable drain duration and admin-server shutdown when enabled.
  • Switched Sentry config to use RELEASE_NAME for release labeling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3cd51b75-c61a-415e-a1f8-baca775387b8

📥 Commits

Reviewing files that changed from the base of the PR and between 5d8ec02 and f5bfbb3.

📒 Files selected for processing (3)

• Index.md
• architecture.md
• howto/signals.md

✅ Files skipped from review due to trivial changes (2)

• Index.md
• howto/signals.md

🚧 Files skipped from review as they are similar to previous changes (1)

• architecture.md

---

📝 Walkthrough

Walkthrough

Documentation-only updates: added an Options package doc and renamed Options API calls; added a link/enumeration for the server interceptor chain; introduced ADMIN_PORT in deployment topology and updated startup/shutdown sequences (server creation, concurrent listeners, admin handling, drain/wait and shutdown ordering); changed Sentry env var name.

Changes

Cohort / File(s)	Summary
Interceptor chain doc Index.md	Added pointer to full server interceptor chain and explicit note that the chain contains 10 interceptors, naming timeout, rate limiting, debug logging, and New Relic.
Package docs Packages.md	Added Options package entry describing a request-scoped string-key key-value store via context.Context (RWMutex+map) for interceptor metadata; added reference links.
Architecture & lifecycle architecture.md	Replaced options.Set/Get usage with options.AddToOptions / options.FromContext(...).Get; documented ADMIN_PORT as optional third port (moves metrics/swagger/pprof off :9091); updated startup sequence (core.New, interceptor assembly, explicit server creation, concurrent gRPC/HTTP listeners, conditional admin) and revised shutdown sequence (FailCheck, drain wait, admin shutdown if configured, HTTP shutdown, gRPC graceful/force, CBStopper Stop).
Production & signals how-tos howto/production.md, howto/signals.md	Adjusted terminationGracePeriod guidance to match SHUTDOWN_DURATION_IN_SECONDS only; inserted admin-server shutdown step when ADMIN_PORT set and renumbered shutdown steps; updated SHUTDOWN_DURATION_IN_SECONDS coverage.
Integrations integrations.md	Replaced Sentry release env var RELEASE with RELEASE_NAME in configuration docs.

Sequence Diagram(s)

sequenceDiagram
    participant Init as Init (caller)
    participant Core as Core
    participant Interceptors as Interceptor Assembly
    participant GRPC as gRPC Server
    participant HTTP as HTTP Server
    participant Admin as Admin Server
    participant CBG as CBGracefulStopper
    participant CBS as CBStopper

    Init->>Core: core.New(cfg)
    Core->>Interceptors: init() assemble interceptor chain
    Core->>GRPC: create gRPC listener (tcp/unix)
    Core->>HTTP: create HTTP listener
    alt ADMIN_PORT set
        Core->>Admin: create admin listener (metrics/swagger/pprof)
    end
    par start listeners
        GRPC->>GRPC: start serving
        HTTP->>HTTP: start serving
        Admin->>Admin: start serving
    end

    Note right of Init: Signal received (TERM/INT)
    Init->>CBG: FailCheck(true) -> mark readiness false
    Init->>Init: wait drain duration (SHUTDOWN_DURATION_IN_SECONDS)
    alt ADMIN_PORT set
        Init->>Admin: Shutdown admin server
    end
    Init->>HTTP: Shutdown HTTP server
    Init->>GRPC: GracefulStop gRPC (fallback to ForceStop)
    Init->>CBS: Stop() services
    Init->>Init: exit

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• docs: ADMIN_PORT config and security hardening #69: Related docs introducing ADMIN_PORT and moving admin endpoints; overlaps startup/shutdown and topology edits.
• docs: rate limiting in features, interceptor chain, config, security hardening #68: Related interceptor-chain documentation updates that name/adjust interceptor entries.
• docs: update Prometheus interceptor package name after Phase 4 migration #40: Related interceptor-chain clarifications in Index.md and architecture documentation.

Poem

🐰 Hopping through docs with a joyful twitch,

Options nested in context, neat and rich,
Admin ports wander to their own door,
Ten interceptors—timeout, debug, and more,
Graceful drains, soft stops—then carrot snitch.

🚥 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 'fix: sync docs with codebase' accurately summarizes the main objective of the changeset, which involves updating documentation across multiple files to align with code implementation details.
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 fix/docs-sync-audit

---

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

[Copilot]

Pull request overview

Updates the documentation to accurately reflect the current ColdBrew codebase behavior and APIs (startup/shutdown flows, options API naming, deployment topology, and integrations).

Changes:

• Align startup/shutdown sequence docs across architecture, production, and signals pages (including admin server and force-stop steps).
• Correct options context propagation API names and expand deployment topology to include optional ADMIN_PORT.
• Add missing options package docs entry, fix Sentry env var name, and link the homepage diagram to the full interceptor chain.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Packages.md	Adds the missing options package entry and links.
integrations.md	Fixes Sentry release environment variable name to RELEASE_NAME.
Index.md	Adds a link from the simplified diagram to the full interceptor chain section.
howto/signals.md	Updates graceful shutdown steps to match runtime behavior (incl. admin server and force-stop).
howto/production.md	Updates production shutdown sequence to match runtime behavior (incl. admin server and force-stop).
architecture.md	Syncs options API naming, deployment topology (admin port), and startup/shutdown sequences with codebase behavior.

---

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

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

---

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