Phase,Prompt
F0: Sync/Prereqs,Run `npm -v && node -v` and ensure Node ≥20; install npm deps globally only if required.
F0: Sync/Prereqs,From repo root run `pnpm codegen` (or `npm run codegen`); confirm contracts/openapi.json & ui/*.jsonc compiled; fail with actionable error if missing.
F0: Sync/Prereqs,”List compiled artifacts under app/generated and contracts/*; summarize UI JSONC modules present; flag missing (pages, routes, forms, content.strings).”
F0: Sync/Prereqs,Decide package manager for /client (`npm` default). Note: server uses pnpm; keep front-end isolated with npm unless instructed otherwise.
F0: Sync/Prereqs,”Create `/client/README.md` explaining JSONC-driven UI, codegen sync, and how to run dev/build/test.”
F1: Init Vite,”Create app: `npm create vite@latest client — –template react-ts`; if /client exists, ensure template files present, else scaffold.”
F1: Init Vite,”Write /client/package.json with scripts: dev, build, preview, test, lint, typecheck, codegen:pull.”
F1: Init Vite,Run `cd client && npm i` to install base deps.
F1: Init Vite,Install routing & data deps: `npm i react-router-dom @tanstack/react-query zod react-hook-form @hookform/resolvers socket.io-client`.
F1: Init Vite,Install tooling deps: `npm i -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier vitest jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom @types/node`.
F1: Init Vite,Optionally install styling: `npm i -D tailwindcss postcss autoprefixer` and init `npx tailwindcss init -p`; skip if design system differs.
F1: Init Vite,Install utilities: `npm i -D vite-tsconfig-paths vite-plugin-svgr cross-env` and wire path alias `@/*` to src.
F2: Structure,”Under /client/src create folders: `app/` (providers), `routes/`, `pages/` (home, store, profile, order), `components/`, `features/`, `lib/`, `contracts/` (generated), `styles/`, `tests/`.”
F2: Structure,Create `/client/src/app/App.tsx` with Router + Providers shell; keep file < 200 LOC; split providers into subfiles if needed. F2: Structure,Add `/client/src/app/providers/QueryProvider.tsx` with React Query setup; `/client/src/app/providers/AuthProvider.tsx` reading token from storage. F2: Structure,Add `/client/src/lib/fetcher.ts` that injects baseURL and Authorization header from AuthProvider context. F2: Structure,Add `/client/src/contracts/README.md` noting these files are generated from server specs; do not edit by hand. F3: Codegen Sync,"Create root script `npm run client:pull-contracts` that copies/links generated types, zod, UI JSON into /client/src/contracts (e.g., using a small Node script)." F3: Codegen Sync,Pull `server/types.generated.d.ts` and `server/responses.zod.generated.ts` into `/client/src/contracts/` with named exports. F3: Codegen Sync,Emit `ui/pages.jsonc` compiled aggregate (or index.jsonc) to `/client/src/contracts/ui.pages.generated.json`; ensure under 300 lines per module by chunking. F3: Codegen Sync,Emit `ui/forms.jsonc` + `data.providers.jsonc` to `/client/src/contracts/ui.forms.generated.json` to drive dynamic selects. F3: Codegen Sync,Emit `ui/content.strings.jsonc` to `/client/src/contracts/content.generated.json` for all copy. F3: Codegen Sync,Add `npm run codegen:client` to call root codegen then client:pull; run and verify imports compile. F4: Lint/Test,Write `/client/.eslintrc.cjs` with TS + React + Prettier config; enforce 300-line max per component via `max-lines-per-function` and a custom rule if needed. F4: Lint/Test,Update `/client/tsconfig.json` with `paths` alias @/* and strict flags on; enable `jsx: react-jsx` and `noUncheckedIndexedAccess` if feasible. F4: Lint/Test,"Configure Vitest: `/client/vite.config.ts` includes `test: { environment: 'jsdom', setupFiles: './src/tests/setup.ts' }`." F4: Lint/Test,Create `/client/src/tests/setup.ts` to import `@testing-library/jest-dom` and set request mocks if needed. F4: Lint/Test,"Add CI-friendly scripts: `npm run lint`, `npm run typecheck`, `npm test` and ensure they pass." F5: AppShell,"Implement `/client/src/components/layout/AppShell.tsx` reading layout tokens from contracts; render TopBar, Outlet, Footer." F5: AppShell,"Implement `/client/src/components/layout/TopBar.tsx` with Search input, Nav links, User avatar menu; strings from content.generated.json." F5: AppShell,Wire keyboard shortcut `/` to focus search; ensure aria-labels and roles are present as per UI JSONC a11y notes. F5: AppShell,Add `/client/src/components/layout/RouteBreadcrumbs.tsx` fed by routes.jsonc metadata; keep under 200 LOC. F5: AppShell,"Unit-test TopBar interactions (open menu, navigate, search focus)." F6: Routing,Create `/client/src/routes/index.tsx` using React Router; dynamically build route tree from `/client/src/contracts/ui.pages.generated.json`. F6: Routing,Implement guard components for auth roles (public/auth/vendor/customer) per routes JSONC; redirect unauthenticated to /login. F6: Routing,Add `ScrollToTop` and error boundary routes; render `EmptyState` and `Retry` from component registry on errors. F6: Routing,Write tests for routing guards and 404 handling. F7: Registry,"Create `/client/src/components/registry/index.ts` mapping JSONC component keys to React components (Button, Input, Avatar, Card, Table, Tabs, Modal, Toast, DataTable, List, Grid, MediaCard, Form, Select, NumberStepper, Pagination, EmptyState)." F7: Registry,Ensure each component accepts a `spec` prop from JSONC and `data` binding; keep each component < 300 LOC by factoring helpers. F7: Registry,Add design tokens via CSS variables (or Tailwind config) from contracts; document how tokens map to classNames. F7: Registry,Add skeleton/shimmer loaders for Data-aware widgets; copy from UI JSONC `loading` slot if provided. F8: Data,Create `/client/src/lib/api-client.ts` using `fetch` or axios; include baseURL env var and token injector; use `makeFetch` from server client hooks if available. F8: Data,Create React Query hooks for each operationId or import generated hooks; prefer generated client if orval config is present. F8: Data,Attach `retry` policy and `staleTime` from `contracts/client/cache.rules.jsonc`; unit-test cache keys match spec. F8: Data,"Implement optimistic updates and invalidation as indicated in cache.rules.jsonc (Product_create, Order_create)." F9: Forms,Implement generic `JsoncForm` that reads `/client/src/contracts/ui.forms.generated.json` and builds a `react-hook-form` + zodResolver instance. F9: Forms,"Support field types: text, textarea, number, select, autocomplete; read `data.source` for dynamic options and cache results." F9: Forms,Implement field visibility via `visibility` expressions; rerender on watched values. F9: Forms,"Write tests for form validation, dynamic loads, and optimistic submission handlers." F10: Home,"Create `/client/src/pages/home/HomePage.tsx` driven by feed.blocks JSONC; render FeaturedStores, TrendingItems, NearbyStores as per spec." F10: Home,Implement `FeaturedStores` block using Store_list op; ensure placeholder/skeleton states defined. F10: Home,Implement `NearbyStores` that uses geolocation (permission) then Store_list with params; fallback gracefully if denied. F10: Home,Test HomePage rendering with mocked API; snapshot for feed layout. F11: Vendor,"Create `/client/src/pages/store/VendorPage.tsx` with banner image, title, description, open hours, location map (placeholder), contact CTA, View Menu button." F11: Vendor,Bind to `Store_get` by route param {storeId}; compute `is_open_now` on client if server did not provide; display range and ETA estimate using Order_estimate. F11: Vendor,Ensure analytics events for CTA clicks are dispatched (stub). F11: Vendor,Test VendorPage data fetching & rendering; ensure under 300 LOC by splitting subcomponents. F12: Menu,"Create `/client/src/pages/store/MenuPage.tsx`; left categories (collapsible on mobile), right items grid with MediaCard." F12: Menu,Implement item customize flow: opens Drawer with option groups and deltas; compute price preview; add to cart. F12: Menu,Persist cart in local storage with versioning; include storeId to avoid cross-store mix-ups. F12: Menu,Test add-to-cart flow and price deltas via unit/integration tests. F13: Cart,"Create `/client/src/pages/order/CartPage.tsx` with line items, qty steppers, totals breakdown; display ETA + delivery fee using Order_estimate." F13: Cart,Implement `Checkout` button calling server to create Stripe session; redirect to hosted checkout; handle errors with toast. F13: Cart,Create `/client/src/pages/order/OrderPage.tsx` for post-checkout summary; call `Order_get` and show live status with polling (WS later). F13: Cart,Write tests for totals calculation UI using zod-inferred types; mock network with MSW. F14: Auth,"Create `/client/src/pages/auth/LoginPage.tsx` with JSONC-driven form; on success, save token, warm queries, redirect back." F14: Auth,Create `/client/src/pages/auth/SignupPage.tsx` (stub if not in MVP); wire copy and validation from DTOs. F14: Auth,Add `ProtectedRoute` wrapper enforcing roles; integrate with routes.jsonc guards; test redirects and flashes. F15: VendorDash,"Create `/client/src/pages/vendor/DashboardPage.tsx` with tabs (Pending Orders, Menu, Store, History, Notifications)." F15: VendorDash,Pending Orders: table with Accept/Reject; mutations call Order_updateStatus; reflect optimistic UI and error recovery. F15: VendorDash,Add Item: modal form from JSONC (Product_create); optimistic add to list; toast success/error. F15: VendorDash,Edit Item and Edit Store: prefill from data; save; invalidate caches; obey validation and size limits. F15: VendorDash,"History: paginated orders with filters; export CSV (client-only, later server)." F15: VendorDash,Notifications: form to manage NotificationChannel; stub until backend implemented. F16: CustomerDash,"Create `/client/src/pages/customer/DashboardPage.tsx` with tiles: Recent Orders, Favorites, Settings." F16: CustomerDash,Recent Orders: list with statuses and `Reorder` button (rebuild cart from last order). F16: CustomerDash,Favorites: list of saved items; add/remove; stub server if not implemented. F16: CustomerDash,"Settings: addresses, notification prefs; leverage Address form and content strings; validations via zod." F17: Realtime,Add `/client/src/lib/ws.ts` to connect socket.io-client with auth token; auto-reconnect; exponential backoff. F17: Realtime,Subscribe vendor dashboard to `{storeId}` room and order-specific rooms; dedupe events using sequence ids if present. F17: Realtime,Display toast on order status changes; update cached queries via React Query `queryClient.setQueryData`. F17: Realtime,Test WS client with mocked server (or local dev); ensure resilience to disconnects. F18: A11y/Theme,Ensure focus outlines are visible and skip link works; test keyboard nav across top bar and modals. F18: A11y/Theme,Implement light/dark theme switch stored in local storage; tokens from contracts. F18: A11y/Theme,Run axe-core in tests for key pages and fix critical violations. F19: Errors/Polish,Implement a central `ToastProvider` and use consistent messages from content.generated.json. F19: Errors/Polish,Add `ErrorBoundary` and `Suspense` around route elements; render EmptyState and Retry from registry. F19: Errors/Polish,Ensure copy uses content strings exclusively; search for hard-coded text and replace. F20: Perf,Enable React.lazy for heavy routes (dashboards); prefetch data for above-the-fold content only. F20: Perf,Audit bundle size with `vite-bundle-visualizer`; identify top 3 deps to trim; consider dynamic imports. F20: Perf,Memoize lists and forms; avoid re-renders via keying and stable callbacks; measure with React Profiler. F21: Tests,"Write unit tests for utilities (fetcher, format currency, price delta calc)." F21: Tests,Integration tests: HomePage feed renders blocks with mocked API; VendorPage loads and shows menu CTA. F21: Tests,Form tests: Product_create and Order_create workflows via RHF + zod; assert error messages and disabled buttons. F21: Tests,Routing tests: guards redirect correctly; 404 shows EmptyState; breadcrumbs render from routes JSONC. F21: Tests,E2E (Playwright optional): smoke test top paths; document how to run locally and in CI (headless). F22: DevServer,Configure Vite dev proxy `/api` → backend port; ensure cookies/headers forwarded; test CORS and auth flows. F22: DevServer,"Add `.env` files: `.env.development`, `.env.production` for baseURL and Stripe publishable key." F22: DevServer,Run `npm run dev` and verify HMR; fix any TS/ESLint errors. F23: Deploy,Add `npm run build` and ensure Vite builds without type errors; output goes to `/client/dist`. F23: Deploy,"If server serves static files, add express static middleware for `/client/dist`; else document separate static hosting." F23: Deploy,Create Dockerfile.frontend multi-stage build; serve via nginx; add caching headers for assets; test locally. F23: Deploy,"Add GitHub Action CI for frontend: install, codegen:client, lint, test, build, upload artifact." F24: Sync,Add a script that hashes `/client/src/contracts/*` and fails build if server codegen hash changed without re-pulling. F24: Sync,Write a test ensuring every page/component uses content strings (no hard-coded UI copy). F24: Sync,"Add generator that produces type-safe route helpers from routes JSONC (e.g., buildPath('store', {storeId}))." F25: Guard,Add ESLint rule and custom check to fail if any component >300 LOC; split oversized components into subcomponents.
F25: Guard,Periodic refactor prompt: identify largest components and propose decomposition plans (stateless UI vs data containers).
F25: Guard,Add script to print component sizes and dependency graph to spot over-coupling.
F26: RN Ready,”Abstract primitives (Button, Text, Input) to be RN-compatible later; avoid web-only APIs; align props with RN where possible.”
F26: RN Ready,Evaluate React Native Web feasibility for shared components; document trade-offs; do not block web delivery.
F27: Security UX,Ensure tokens stored in memory + local storage with refresh on page load; provide logout that clears caches securely.
F27: Security UX,Mask PII in UI where appropriate; ensure address display respects privacy settings.
F27: Security UX,Add CSRF considerations doc (not needed for pure token auth) and explain why.
F28: Analytics,Add event hook utility `useAnalytics()` that logs key user actions; wire CTA click ids from JSONC; keep as console.log for MVP.
F28: Analytics,Provide route change tracking; ensure no PII logged.
F29: Final,Run `npm run lint && npm run typecheck && npm test && npm run build`; fix failures; attach a concise report.
F29: Final,”Write `/client/CONTRIBUTING.md` with commands, folder structure, and JSONC-driven development workflow.”
F29: Final,”Propose top 5 UI improvements based on current JSONC specs (reduce clicks, clarify copy, improve empty states).”
F-Refine: UI Polish,Review content strings for consistency batch #1; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #2; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #3; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #4; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #5; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #6; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #7; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #8; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #9; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #10; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #11; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #12; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #13; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #14; replace vague copy; ensure length limits for buttons and headings.
F-Refine: UI Polish,Review content strings for consistency batch #15; replace vague copy; ensure length limits for buttons and headings.