Docs: Diagram of AuthBridge plugin decision sequence

[esnible]

Summary

I had difficulty understanding how AuthBridge is configured to make decisions about network traffic. This PR documents my understanding how the conceptual model of AuthBridge. My intention is that a diagram at this level of abstraction will be useful to both developers in this repo and developers writing AuthBridge configuration for specialized authorization tasks.

Summary by CodeRabbit

• Documentation
  • Added new user-facing documentation explaining AuthBridge’s plugin-based configuration and request/response flow.
  • Described supported deployment setup, session handling, and ordered inbound/outbound processing.
  • Listed the included plugins and the differences between the standard and lightweight images.
  • Added examples showing how data can be carried across multiple requests and used for authorization decisions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 60e50245-4366-43d9-9ec6-4cac12c1c7c9

📥 Commits

Reviewing files that changed from the base of the PR and between c083779 and 1edac32.

⛔ Files ignored due to path filters (1)

• docs/plugin-sequence.svg is excluded by !**/*.svg

📒 Files selected for processing (1)

• docs/README.md

---

📝 Walkthrough

Walkthrough

This PR adds a new documentation file (docs/README.md) describing AuthBridge's plugin-based architecture, including its configuration model, ordered inbound/outbound plugin pipelines, the pipeline.Context data structure, and two example multi-message authorization flows using Shared and Session state.

Changes

AuthBridge Documentation

Layer / File(s)	Summary
Architecture overview and plugin list docs/README.md	Describes AuthBridge as a sidecar, its YAML configuration model, ordered plugin pipeline concept, nine shipped plugins, and the authbridge vs authbridge-lite image distinction.
Example pipeline configuration docs/README.md	Adds a sample configuration combining auth plugins, parsers, guardrails, and token exchange, with request/response phase ordering explained.
pipeline.Context data shape docs/README.md	Documents the Plugin interface (OnRequest/OnResponse), pctx fields set/read by components, and the Shared/Session persistence mechanisms.
Multi-message decision examples docs/README.md	Walks through credential indirection via pctx.Shared (401 fail-closed) and intent-based authorization via pctx.Session (403 on mismatch, plus sparc grounding).

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AuthBridge
  participant JWTValidation
  participant Shared
  participant TokenExchange

  Client->>AuthBridge: Inbound HTTP request
  AuthBridge->>JWTValidation: OnRequest(pctx)
  JWTValidation->>Shared: write token handle (TTL)
  AuthBridge->>Client: forward to backend

  Client->>AuthBridge: Outbound request
  AuthBridge->>TokenExchange: OnRequest(pctx)
  TokenExchange->>Shared: read token handle
  alt token missing or expired
    TokenExchange-->>Client: 401
  else token valid
    TokenExchange->>Client: forward authorized request
  end

Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

ready-for-ai-review

Suggested reviewers

• cwiklik

A rabbit hops through docs anew,
Pipelines and plugins, fields in view,
Tokens hidden, sessions tracked,
Intent and access, neatly stacked,
🐇📜 Hop, read, and review with you!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the docs-focused update about AuthBridge’s plugin decision sequence.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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