From 00c20556f600f8c713d248da7f5589b08cd364fe Mon Sep 17 00:00:00 2001 From: 6akola <6akarolawale@gmail.com> Date: Thu, 30 Jul 2026 13:35:04 +0100 Subject: [PATCH] docs: add AUTH_FLOWS.md with login/logout/refresh sequence diagrams Add contributor-facing documentation describing the three session-lifecycle flows (connect wallet, disconnect, re-authentication) and the inactivity timeout. Includes Mermaid sequence diagrams, key code paths, and cross-links to related docs. Linked from both README.md and docs/README.md. --- README.md | 1 + docs/AUTH_FLOWS.md | Bin 0 -> 15598 bytes docs/README.md | 11 ++++++++--- 3 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 docs/AUTH_FLOWS.md diff --git a/README.md b/README.md index dc395e9e..79991434 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,7 @@ See the [docs/](docs/) directory for detailed project documentation, including: - [Architecture Overview](docs/ARCHITECTURE.md) — Runtime structure, provider tree, and data flow seams. - [API Client Policies](docs/API_CLIENT_POLICIES.md) — Interceptors, retry policy, and error taxonomy for the API client. - [Cookie-Secret Rotation Runbook](docs/COOKIE_SECRETS.md) — Rotation cadence, blast radius, and step-by-step procedure for backend session/CSRF cookie secrets. +- [Authentication Flows](docs/AUTH_FLOWS.md) — Sequence diagrams for login, logout, and session refresh flows. - [Hooks & Utilities Reference](docs/HOOKS.md) — Catalog of reusable hooks (`src/hooks/`) and helpers (`src/lib/`) with signatures and usage. ## Project layout diff --git a/docs/AUTH_FLOWS.md b/docs/AUTH_FLOWS.md new file mode 100644 index 0000000000000000000000000000000000000000..fe9f3b8baf93e8dd679eb60c6980f5a6192a32f6 GIT binary patch literal 15598 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 token-driven pill showing `Saving…` / `Saved just now` / "Couldn't save" with retry. - In-flight cancellation via `AbortController` so stale PATCHes can't overwrite newer state. -16. **[Widget Cache & Per-Widget Refresh](./widget-cache.md)** ⭐ NEW (closes #561) +17. **[Widget Cache & Per-Widget Refresh](./widget-cache.md)** ⭐ NEW (closes #561) - Shared in-app cache for dashboard widgets so a refresh button on one card only invalidates that card's key — others keep their state. - `useWidgetCache` hook + `` + token-driven styling. - Coverage includes mount, key isolation, error surfacing, and reduced-motion. -17. **[API Client Policies](./API_CLIENT_POLICIES.md)** ⭐ NEW +18. **[API Client Policies](./API_CLIENT_POLICIES.md)** ⭐ NEW - Interceptors, retry policy, and error taxonomy for the API client - `ApiError` structure and usage examples -18. **[Telemetry & Analytics](./telemetry.md)** +19. **[Telemetry & Analytics](./telemetry.md)** - Privacy-first approach (no telemetry collected) - No PII handling or third-party analytics