Files
sor/Client/client-plan.md
T

3.0 KiB

SOR Client Plan (Draft)

1) Goal

Build a production-ready SOR client app with a fast MVP path, clear API boundaries, and room for iteration.


2) Product Scope (MVP)

Must-have

  • Authentication flow (login/logout/session handling)
  • Core dashboard/home view
  • Primary domain workflow (create/read/update critical records)
  • Basic search/filter
  • Error handling and loading states
  • Responsive layout (desktop first, mobile usable)

Nice-to-have (post-MVP)

  • Real-time updates (websocket/polling)
  • Offline support / optimistic updates
  • Role-based UI gates
  • Advanced reporting/analytics screens

3) Architecture Decisions

Client Stack (proposed)

  • Framework: React + TypeScript
  • Build: Vite
  • Routing: React Router
  • State: TanStack Query (server state) + small local state store
  • UI: component library + design tokens
  • Forms: React Hook Form + schema validation (Zod)
  • Testing: Vitest + React Testing Library + Playwright (smoke e2e)

Integration Contract

  • Base API client with typed endpoints
  • Shared error envelope handling
  • Auth token refresh strategy
  • Environment config: dev/stage/prod

4) Delivery Phases

Phase 0 — Discovery (1-2 days)

  • Confirm user journeys
  • Confirm API endpoints and data shapes
  • Lock MVP acceptance criteria

Phase 1 — Foundation (2-3 days)

  • Project scaffolding + linting + formatting + CI checks
  • App shell, routing, auth guard pattern
  • API client + error boundary + notification pattern

Phase 2 — Core Screens (4-6 days)

  • Implement key workflow screens
  • Connect live API calls
  • Add loading/empty/error states

Phase 3 — Hardening (2-3 days)

  • Tests (unit + smoke e2e)
  • Perf pass (bundle and render hotspots)
  • Accessibility pass (keyboard, labels, contrast)

Phase 4 — Release Prep (1-2 days)

  • QA checklist + bugfix sweep
  • Deployment docs
  • Feature flag cleanup

5) Work Breakdown (Backlog Seed)

  • Define MVP user stories (top 5)
  • Define API contract doc (request/response examples)
  • Set up client repo structure
  • Implement auth/session lifecycle
  • Build dashboard shell
  • Implement primary CRUD workflow
  • Add search/filter on primary list
  • Add validation + error handling patterns
  • Add telemetry/logging hooks
  • Add test harness + CI checks

6) Risks & Mitigations

  • API instability → introduce typed client + mock fallback
  • Scope creep → strict MVP gate + weekly re-prioritization
  • UX churn → rapid wireframes before full implementation
  • Auth edge cases → early test matrix (expired token, revoked session)

7) Questions to Resolve Next

  1. Who are the primary client users (roles/personas)?
  2. What is the single most important workflow to ship first?
  3. Any hard deadline for MVP?
  4. Any required platform constraints (desktop-only, mobile-first, PWA)?
  5. Any compliance/security requirements beyond standard auth?

8) Immediate Next Step

Run a 30-minute planning pass to lock:

  • MVP scope (must-have list)
  • API endpoints needed for MVP
  • first sprint task list with estimates