React app shell #546

Open
opened 2026-09-29 19:08:37 +01:00 by Smithy-bot · 2 comments
Member

Epic: #543
Story Points: 5


SO THAT admins have a React SPA shell (layout, auth gate, routing) served from the bot process.

Scaffold the React (TypeScript / Vite) app, wire auth gate + routing, and serve the built assets from the same Express process.

Scope

Delivers the frontend shell for epic #543. Assumes #544 exposes the Management API router split (public vs protected) and #545 provides Discord OAuth + session cookies.

In scope: web/ Vite + React + TypeScript scaffold, production build wired into the bot release, Express static + SPA fallback, client-side router, shared admin layout (nav placeholders), auth gate (redirect unauthenticated users to login), logout affordance calling #545.

Out of scope: Settings / card / ops feature pages (#547–#550); OAuth implementation (#545); management REST handlers (#544 + feature stories); roles/resources UI (#551).

Acceptance criteria

  • GIVEN the repo is built for release
    WHEN CI runs
    THEN the React app under web/ compiles successfully and its production assets are available for Express to serve (copy step or equivalent documented in the bot build).

  • GIVEN the bot process is running with Management API enabled
    WHEN a browser requests a static asset from the SPA build (e.g. hashed JS/CSS)
    THEN Express serves the file with correct content types and caching headers appropriate for hashed assets.

  • GIVEN the SPA is deployed
    WHEN a browser requests a client route (e.g. /settings) via direct navigation or refresh
    THEN Express returns index.html (SPA fallback) so client routing can handle the path.

  • GIVEN an unauthenticated browser (no valid session cookie from #545)
    WHEN they open any management UI route other than public auth paths
    THEN they are redirected to the Discord login entry (GET /auth/discord or documented equivalent) and do not see shell content.

  • GIVEN an authenticated admin session (#545)
    WHEN they open the SPA root
    THEN they see a consistent shell layout (header/nav) with placeholder links for Settings, Cards, and Ops that route client-side (pages may be stubs until #547–#550).

  • GIVEN an authenticated admin
    WHEN they use Log out in the shell
    THEN the client calls POST /auth/logout (#545), clears local UI state, and redirects to login.

  • GIVEN local development
    WHEN a developer runs the documented dev workflow
    THEN they can iterate on the React app with API/auth proxied to the local Express port without manual CORS hacks for same-origin session cookies.

  • GIVEN automated frontend tests
    WHEN CI runs
    THEN tests cover at least: auth gate redirect for unauthenticated shell access (mocked session/API); router renders shell + stub routes for authenticated state.

Subtasks

  • Scaffold Vite + React + TypeScript app under web/ (align with #542)
  • Add npm scripts and CI/build integration to produce SPA artifacts consumed by the bot image/release
  • Mount static file serving + SPA index.html fallback on Express (coordinate mount paths with #544 public vs protected routers)
  • Implement client-side router with shell layout and stub routes for Settings / Cards / Ops
  • Implement auth gate (session probe or equivalent) redirecting unauthenticated users to #545 login
  • Wire shell Log out to POST /auth/logout (#545)
  • Add frontend unit/component tests for auth gate and routing
  • Document local dev (Vite proxy) and production build/serve expectations (pointer to full deploy doc in #553)

Notes

  • Decision: #542 — React SPA; prefer packaging under web/
  • Depends on: #544 Management API foundation; #545 Discord OAuth + session
  • Enables: #547–#550 feature pages inside the shell
Epic: #543 Story Points: **5** --- SO THAT admins have a React SPA shell (layout, auth gate, routing) served from the bot process. Scaffold the React (TypeScript / Vite) app, wire auth gate + routing, and serve the built assets from the same Express process. ## Scope Delivers the **frontend shell** for epic [#543](https://git.vylpes.xyz/External/card-drop/issues/543). Assumes [#544](https://git.vylpes.xyz/External/card-drop/issues/544) exposes the Management API router split (public vs protected) and [#545](https://git.vylpes.xyz/External/card-drop/issues/545) provides Discord OAuth + session cookies. **In scope:** `web/` Vite + React + TypeScript scaffold, production build wired into the bot release, Express static + SPA fallback, client-side router, shared admin layout (nav placeholders), auth gate (redirect unauthenticated users to login), logout affordance calling #545. **Out of scope:** Settings / card / ops feature pages ([#547](https://git.vylpes.xyz/External/card-drop/issues/547)–[#550](https://git.vylpes.xyz/External/card-drop/issues/550)); OAuth implementation ([#545](https://git.vylpes.xyz/External/card-drop/issues/545)); management REST handlers ([#544](https://git.vylpes.xyz/External/card-drop/issues/544) + feature stories); roles/resources UI ([#551](https://git.vylpes.xyz/External/card-drop/issues/551)). ## Acceptance criteria - **GIVEN** the repo is built for release **WHEN** CI runs **THEN** the React app under `web/` compiles successfully and its production assets are available for Express to serve (copy step or equivalent documented in the bot build). - **GIVEN** the bot process is running with Management API enabled **WHEN** a browser requests a static asset from the SPA build (e.g. hashed JS/CSS) **THEN** Express serves the file with correct content types and caching headers appropriate for hashed assets. - **GIVEN** the SPA is deployed **WHEN** a browser requests a client route (e.g. `/settings`) via direct navigation or refresh **THEN** Express returns `index.html` (SPA fallback) so client routing can handle the path. - **GIVEN** an unauthenticated browser (no valid session cookie from #545) **WHEN** they open any management UI route other than public auth paths **THEN** they are redirected to the Discord login entry (`GET /auth/discord` or documented equivalent) and do not see shell content. - **GIVEN** an authenticated admin session (#545) **WHEN** they open the SPA root **THEN** they see a consistent shell layout (header/nav) with placeholder links for Settings, Cards, and Ops that route client-side (pages may be stubs until #547–#550). - **GIVEN** an authenticated admin **WHEN** they use Log out in the shell **THEN** the client calls `POST /auth/logout` (#545), clears local UI state, and redirects to login. - **GIVEN** local development **WHEN** a developer runs the documented dev workflow **THEN** they can iterate on the React app with API/auth proxied to the local Express port without manual CORS hacks for same-origin session cookies. - **GIVEN** automated frontend tests **WHEN** CI runs **THEN** tests cover at least: auth gate redirect for unauthenticated shell access (mocked session/API); router renders shell + stub routes for authenticated state. ## Subtasks - [ ] Scaffold Vite + React + TypeScript app under `web/` (align with [#542](https://git.vylpes.xyz/External/card-drop/issues/542)) - [ ] Add npm scripts and CI/build integration to produce SPA artifacts consumed by the bot image/release - [ ] Mount static file serving + SPA `index.html` fallback on Express (coordinate mount paths with #544 public vs protected routers) - [ ] Implement client-side router with shell layout and stub routes for Settings / Cards / Ops - [ ] Implement auth gate (session probe or equivalent) redirecting unauthenticated users to #545 login - [ ] Wire shell Log out to `POST /auth/logout` (#545) - [ ] Add frontend unit/component tests for auth gate and routing - [ ] Document local dev (Vite proxy) and production build/serve expectations (pointer to full deploy doc in #553) ## Notes - Decision: [#542](https://git.vylpes.xyz/External/card-drop/issues/542) — React SPA; prefer packaging under `web/` - Depends on: [#544](https://git.vylpes.xyz/External/card-drop/issues/544) Management API foundation; [#545](https://git.vylpes.xyz/External/card-drop/issues/545) Discord OAuth + session - Enables: [#547](https://git.vylpes.xyz/External/card-drop/issues/547)–[#550](https://git.vylpes.xyz/External/card-drop/issues/550) feature pages inside the shell
Smithy-bot added this to the 0.14.0 milestone 2026-09-29 19:08:37 +01:00
Smithy-bot stopped working 2026-10-25 11:03:44 +00:00
14 seconds
Author
Member

Planning — needs/estimate → needs/tests

Story points: 5 (Fibonacci).

Rationale: Standard medium story: new web/ Vite+React+TS scaffold, CI/build wiring into the bot, Express static hosting + SPA fallback coordinated with #544 routes, client router + layout + stubs, auth gate + logout wired to #545, frontend tests, and dev/prod documentation. Depends on #544/#545 being in place; issue stays blocked until those land — no change to dependency links.

Next step: QA test scripts under needs/tests.

## Planning — needs/estimate → needs/tests **Story points: 5** (Fibonacci). **Rationale:** Standard medium story: new `web/` Vite+React+TS scaffold, CI/build wiring into the bot, Express static hosting + SPA fallback coordinated with #544 routes, client router + layout + stubs, auth gate + logout wired to #545, frontend tests, and dev/prod documentation. Depends on #544/#545 being in place; issue stays **blocked** until those land — no change to dependency links. Next step: QA test scripts under **needs/tests**.
Smithy-bot stopped working 2026-11-06 11:02:32 +00:00
24 seconds
Author
Member

Planning — needs/tests → needs/approval

QA scripts mapped to the acceptance criteria in the issue description. Run on a branch with this story and #544 + #545 on stage (or local equivalent with built SPA). Automated rows via web/ test suite + CI.

Preconditions

  • Bot process with management HTTP + SPA build deployed (release build or CI artifact copied into image).
  • #544: public vs protected router split; static/SPA mount paths documented.
  • #545: Discord OAuth login, session cookie, POST /auth/logout live.
  • BOT_ADMINS includes a test Discord user; second non-admin account for negative cases.
  • Browser with cookie jar; yarn test / yarn workspace web test (or documented command) for frontend CI.
  • At least one hashed asset filename known post-build (e.g. from web/dist/assets/).

Note: Issue remains blocked until #544 and #545 are merged to the test branch; QA below assumes both are present.


AC1 — Release/CI build produces SPA artifacts

ID Steps Expected
T1.1 Run documented release/CI build (Forgejo Actions or yarn build + bot packaging step) Build completes without error
T1.2 Inspect build output Production assets from web/ exist in path Express will serve (copy step or equivalent)
T1.3 Code review CI workflow includes React/Vite compile step; failure fails the pipeline

AC2 — Express serves static hashed assets

ID Steps Expected
T2.1 With bot running, GET a known hashed JS/CSS asset URL 200; correct Content-Type (e.g. application/javascript, text/css)
T2.2 Inspect response headers for hashed asset Cache headers appropriate for fingerprinted files (e.g. long-lived Cache-Control)
T2.3 Request non-existent asset under static mount 404 (not SPA index.html)

AC3 — SPA fallback for client routes

ID Steps Expected
T3.1 Hard refresh / direct GET to client route (e.g. /settings, /cards) 200; body is index.html (HTML document)
T3.2 Same for deep path with multiple segments SPA fallback, not 404 from API router
T3.3 Confirm API routes (e.g. /api/*, /auth/*) Still handled by Express API/auth routers, not overridden incorrectly by SPA fallback

AC4 — Auth gate redirects unauthenticated users

ID Steps Expected
T4.1 Clear cookies; open SPA shell route (e.g. / or /settings) Redirect to Discord login entry (GET /auth/discord or documented equivalent); no shell chrome visible
T4.2 Unauthenticated GET to stub feature route Same redirect behaviour
T4.3 Public auth paths from #545 (/auth/discord, callback) Reachable without prior session (no erroneous client-side loop)

AC5 — Authenticated admin sees shell + stub routes

ID Steps Expected
T5.1 Complete #545 OAuth as BOT_ADMINS user; open SPA root Shell layout renders (header/nav); consistent styling
T5.2 Click nav placeholders: Settings, Cards, Ops Client-side navigation works; stub page content or placeholder per route (#547–#550 not required)
T5.3 Refresh on each stub route Still authenticated; shell persists (session + SPA fallback)

AC6 — Logout from shell

ID Steps Expected
T6.1 Authenticated; use shell Log out Client calls POST /auth/logout; UI clears local state
T6.2 After logout Redirect to login; protected shell routes trigger auth gate again
T6.3 POST /auth/logout network tab 200/204; session invalidated (#545 AC6)

AC7 — Local dev workflow

ID Steps Expected
T7.1 Follow documented dev steps (Vite dev server + API proxy to Express port) Hot reload works on React changes
T7.2 Exercise login + shell in dev Session cookies work same-origin via proxy (no manual CORS workarounds for normal flows)
T7.3 README / issue notes Documents ports, proxy env, and how to run bot + web/ together

AC8 — Automated frontend tests in CI

ID Steps Expected
U1 Run frontend unit/component tests locally Green
U2 Test: unauthenticated access to shell route (mocked session/API) Auth gate redirect or equivalent assertion
U3 Test: authenticated state Shell + stub routes render in test harness
U4 CI pipeline on PR touching web/ Frontend test job runs and passes
U5 Regression: existing bot yarn test Still green (no breakage from new workspace)

Subtasks / documentation / integration

ID Steps Expected
D1 Build/serve docs Local dev + production build steps documented (pointer to #553 deploy when ready)
D2 Mount path review with #544 Static files and SPA fallback do not shadow protected /api/* incorrectly
R1 Discord bot commands Unchanged; only HTTP surface extended
R2 Dependency gate Do not ship shell to prod without #544 + #545 on same release branch

Sign-off checklist

  • T1–T7, U1–U5, D1–D2, and R1–R2 pass on stage (or documented mocks).
  • E2E: login → shell → stub routes → logout verified with #545 session.

Moving to needs/approval for your review before implementation. @Vylpes

## Planning — needs/tests → needs/approval QA scripts mapped to the acceptance criteria in the issue description. Run on a branch with this story **and** [#544](https://git.vylpes.xyz/External/card-drop/issues/544) + [#545](https://git.vylpes.xyz/External/card-drop/issues/545) on **stage** (or local equivalent with built SPA). Automated rows via `web/` test suite + CI. ### Preconditions - Bot process with management HTTP + SPA build deployed (release build or CI artifact copied into image). - #544: public vs protected router split; static/SPA mount paths documented. - #545: Discord OAuth login, session cookie, `POST /auth/logout` live. - `BOT_ADMINS` includes a test Discord user; second non-admin account for negative cases. - Browser with cookie jar; `yarn test` / `yarn workspace web test` (or documented command) for frontend CI. - At least one hashed asset filename known post-build (e.g. from `web/dist/assets/`). **Note:** Issue remains **blocked** until #544 and #545 are merged to the test branch; QA below assumes both are present. --- ### AC1 — Release/CI build produces SPA artifacts | ID | Steps | Expected | |----|--------|----------| | T1.1 | Run documented release/CI build (Forgejo Actions or `yarn build` + bot packaging step) | Build completes without error | | T1.2 | Inspect build output | Production assets from `web/` exist in path Express will serve (copy step or equivalent) | | T1.3 | Code review | CI workflow includes React/Vite compile step; failure fails the pipeline | --- ### AC2 — Express serves static hashed assets | ID | Steps | Expected | |----|--------|----------| | T2.1 | With bot running, `GET` a known hashed JS/CSS asset URL | **200**; correct `Content-Type` (e.g. `application/javascript`, `text/css`) | | T2.2 | Inspect response headers for hashed asset | Cache headers appropriate for fingerprinted files (e.g. long-lived `Cache-Control`) | | T2.3 | Request non-existent asset under static mount | **404** (not SPA `index.html`) | --- ### AC3 — SPA fallback for client routes | ID | Steps | Expected | |----|--------|----------| | T3.1 | Hard refresh / direct `GET` to client route (e.g. `/settings`, `/cards`) | **200**; body is `index.html` (HTML document) | | T3.2 | Same for deep path with multiple segments | SPA fallback, not **404** from API router | | T3.3 | Confirm API routes (e.g. `/api/*`, `/auth/*`) | Still handled by Express API/auth routers, not overridden incorrectly by SPA fallback | --- ### AC4 — Auth gate redirects unauthenticated users | ID | Steps | Expected | |----|--------|----------| | T4.1 | Clear cookies; open SPA shell route (e.g. `/` or `/settings`) | Redirect to Discord login entry (`GET /auth/discord` or documented equivalent); no shell chrome visible | | T4.2 | Unauthenticated `GET` to stub feature route | Same redirect behaviour | | T4.3 | Public auth paths from #545 (`/auth/discord`, callback) | Reachable without prior session (no erroneous client-side loop) | --- ### AC5 — Authenticated admin sees shell + stub routes | ID | Steps | Expected | |----|--------|----------| | T5.1 | Complete #545 OAuth as `BOT_ADMINS` user; open SPA root | Shell layout renders (header/nav); consistent styling | | T5.2 | Click nav placeholders: Settings, Cards, Ops | Client-side navigation works; stub page content or placeholder per route (#547–#550 not required) | | T5.3 | Refresh on each stub route | Still authenticated; shell persists (session + SPA fallback) | --- ### AC6 — Logout from shell | ID | Steps | Expected | |----|--------|----------| | T6.1 | Authenticated; use shell **Log out** | Client calls `POST /auth/logout`; UI clears local state | | T6.2 | After logout | Redirect to login; protected shell routes trigger auth gate again | | T6.3 | `POST /auth/logout` network tab | **200**/**204**; session invalidated (#545 AC6) | --- ### AC7 — Local dev workflow | ID | Steps | Expected | |----|--------|----------| | T7.1 | Follow documented dev steps (Vite dev server + API proxy to Express port) | Hot reload works on React changes | | T7.2 | Exercise login + shell in dev | Session cookies work same-origin via proxy (no manual CORS workarounds for normal flows) | | T7.3 | README / issue notes | Documents ports, proxy env, and how to run bot + `web/` together | --- ### AC8 — Automated frontend tests in CI | ID | Steps | Expected | |----|--------|----------| | U1 | Run frontend unit/component tests locally | Green | | U2 | Test: unauthenticated access to shell route (mocked session/API) | Auth gate redirect or equivalent assertion | | U3 | Test: authenticated state | Shell + stub routes render in test harness | | U4 | CI pipeline on PR touching `web/` | Frontend test job runs and passes | | U5 | Regression: existing bot `yarn test` | Still green (no breakage from new workspace) | --- ### Subtasks / documentation / integration | ID | Steps | Expected | |----|--------|----------| | D1 | Build/serve docs | Local dev + production build steps documented (pointer to #553 deploy when ready) | | D2 | Mount path review with #544 | Static files and SPA fallback do not shadow protected `/api/*` incorrectly | | R1 | Discord bot commands | Unchanged; only HTTP surface extended | | R2 | Dependency gate | Do not ship shell to prod without #544 + #545 on same release branch | --- ### Sign-off checklist - [ ] T1–T7, U1–U5, D1–D2, and R1–R2 pass on stage (or documented mocks). - [ ] E2E: login → shell → stub routes → logout verified with #545 session. Moving to **needs/approval** for your review before implementation. @Vylpes
Smithy-bot removed their assignment 2026-11-07 11:03:14 +00:00
Smithy-bot stopped working 2026-11-07 11:03:15 +00:00
39 seconds
Vylpes removed their assignment 2026-11-07 18:03:06 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Total time spent: 1 minute 17 seconds
Smithy-bot
1 minute 17 seconds
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
External/card-drop#546
No description provided.