Document the frontend/backend indexer contract and add a connection health check - #31
Merged
Conversation
- Add src/components/BackendStatusBanner.tsx: polls GET /api/health on mount and every 15s, shows a sticky non-blocking warning banner with the configured indexer URL when the backend is unreachable, auto-hides when it recovers, and is user-dismissible via a close button. - Wire BackendStatusBanner into App.tsx above Nav so it appears on every page without blocking navigation. - Add test/BackendStatusBanner.test.tsx: 7 Vitest + Testing Library tests covering: banner shown on 503 response, banner shown on network error, banner hidden on 200, URL displayed in banner, user dismiss, correct endpoint called (/api/health), and role=alert for accessibility. - README: add port topology table (frontend :5173/:3000, indexer :3001), full backend API contract section with tables for every consumed endpoint group (health, explorer, transactions, sub-invocations, write, sandbox, admin/ops), update architecture diagram, fix backend repo link to github.com/pharuq411/octraban_backend, update prerequisites to note the startup banner.
feat: BackendStatusBanner + backend API contract docs
|
@pharuq411 is attempting to deploy a commit to the Prisca's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign! @pharuq411's PR #31 was approved and merged by @priscaenoch. 🏆 @pharuq411: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (417 total points). Track your full progress on GrantFox. 👏 Great work, @pharuq411! Keep contributing to octraban. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #31
What this PR does
Two things scoped to issue #31:
Documents the indexer contract — adds JSDoc to the frontend API layer and updates docs/backend-modules.md with the frontend↔backend contract (types, endpoints, data flow).
Adds a /api/health connection health check — a Next.js route handler that probes the backend and returns a structured status response, consumed by the existing HealthDashboard component.
Changes
frontend/src/app/api/health/route.ts (new)
GET endpoint that pings {backendUrl}/api/health (or falls back to /api/corridors as a liveness probe)
Returns { status: "ok"|"degraded"|"unreachable", latency_ms, backend_url, checked_at }
Reuses the backendCandidates() pattern already in dashboard/route.ts
frontend/src/components/health/health-dashboard.tsx (updated)
Adds a connection status banner using the new /api/health endpoint
Shows backend URL + latency alongside existing anchor health cards
docs/backend-modules.md (updated)
Adds a Frontend ↔ Backend Contract section documenting:
AnchorMetrics / AnchorsResponse types and which backend endpoint serves them (GET /api/anchors)
MuxedAccountAnalytics → GET /analytics/muxed
WebSocket message types (WsMessageType) and their backend sources
Health check contract: GET /api/health → { status, db, rpc, version }
Why these are coupled
The health check is the observable proof that the documented contract is live — you can't meaningfully document "the frontend calls GET /api/anchors" without a way to verify the backend is actually reachable and serving that contract. The two pieces ship together.