Initial commit: React frontend (SLP Software) + AIDLC workflow docs

Co-authored-by: Junie <junie@jetbrains.com>
2026-07-20 00:19:44 +02:00
commit e299f1c745
73 changed files with 7275 additions and 0 deletions
@@ -0,0 +1,53 @@
+# NFR Requirements — react-frontend-app
+
+## Performance
+- **Target**: No hard numeric target. Keep the production bundle reasonably small; code-splitting is not required for this single-page iteration but the setup should not preclude it later (Vite handles this automatically as routes/queries grow).
+
+## Testing
+- **Test runner**: Vitest (pairs naturally with Vite)
+- **Component testing**: React Testing Library
+- **Scope for this iteration**: Component rendering tests for key components (`Nav`, `ThemeToggle`, `PackagesSection`, `PackageCard`) and a unit test for the theme resolution/persistence logic (BR-1, BR-2, BR-3).
+
+## Linting & Formatting
+- **ESLint** configured with React + TypeScript rules (e.g. `typescript-eslint`, `eslint-plugin-react-hooks`)
+- **Prettier** for consistent formatting
+- Both must pass cleanly on the initial generated codebase.
+
+## Routing Strategy for Static/FTP Hosting (AI Recommendation)
+The user deferred this decision to the AI (Question 4 = "Not sure — let the AI recommend").
+
+**Decision: Use TanStack Router's hash-based history (`createHashHistory`) for this iteration.**
+
+**Rationale**:
+- The confirmed deployment target (requirements.md NFR-4) is a traditional web host via FTP/manual upload, where server-side rewrite rules (`.htaccess` or equivalent) are not guaranteed to be configurable or reliably supported.
+- Hash-based routing (`/#/route`) works correctly on any static file host with zero server configuration, because the part after `#` is never sent to the server — the server only ever needs to serve `index.html`.
+- The trade-off (slightly less clean URLs, e.g. `example.com/#/pakketten` instead of `example.com/pakketten`) is acceptable for a small marketing site and avoids a class of "404 on refresh/direct link" bugs that browser `history` mode would introduce on this hosting target.
+- If hosting later moves to a platform with reliable rewrite support (e.g. Netlify/Vercel per requirements.md's alternative hosting note), this can be revisited and switched to `createBrowserHistory` — this is a router configuration change only, not a structural one, since TanStack Router's history mode is set in one place at the router's creation.
+
+## Accessibility
+- **Target**: Best-effort only, matching whatever the reference HTML already provides (no formal WCAG level mandated for this iteration). Note: the functional design already includes concrete accessibility details (Dutch `aria-label` and `aria-pressed` on the theme toggle) that will still be implemented, since they were explicit functional design decisions — this NFR decision only means no additional formal accessibility audit/target is required beyond that.
+
+## CI/CD
+- **This iteration**: No CI pipeline is set up yet. Deferred to the Operations phase (Deployment Setup), which will define the concrete build/deploy process for the FTP target.
+
+## Security Baseline — Rule-by-Rule Applicability
+
+| Rule | Applicability | Decision / Rationale |
+|---|---|---|
+| SECURITY-01 (encryption at rest/in transit) | N/A | No data store exists in this static frontend. |
+| SECURITY-02 (access logging on intermediaries) | N/A | No load balancer/API gateway/CDN configured by this unit; would apply at hosting level if applicable, out of scope here. |
+| SECURITY-03 (application-level logging) | N/A | No server-side application component; a client-side app has no backend logs to configure. |
+| SECURITY-04 (HTTP security headers) | Deferred | Depends on the final hosting choice and whether the host supports custom headers — deferred to Deployment Setup (Operations phase). |
+| SECURITY-05 (input validation on API params) | N/A | No API endpoints exist in this unit. |
+| SECURITY-06 (least-privilege access policies) | N/A | No IAM/cloud roles involved. |
+| SECURITY-07 (restrictive network configuration) | N/A | No network/firewall resources involved. |
+| SECURITY-08 (application-level access control) | N/A | No authenticated resources or user accounts exist. |
+| SECURITY-09 (hardening/misconfiguration) | Addressed now | Production build via Vite has no sample/demo pages; a top-level React error boundary will show a generic message instead of exposing stack traces. |
+| SECURITY-10 (software supply chain) | Addressed now | `package-lock.json` committed; `npm audit` documented as part of build instructions; no unused dependencies added. |
+| SECURITY-11 (secure design principles) | N/A | No security-critical logic (auth, payments) exists in this unit. |
+| SECURITY-12 (authentication/credential mgmt) | N/A | No authentication exists in this unit. |
+| SECURITY-13 (software/data integrity) | Addressed now (partial) | Subresource Integrity (SRI) hashes will be added to the Google Fonts `<link>` tags where the CDN provides stable, hashable assets; no other external CDN resources are used. |
+| SECURITY-14 (alerting and monitoring) | Deferred | No backend/log service exists yet; revisit if/when Monitoring Setup (Operations phase) introduces any client-side error/analytics reporting. |
+| SECURITY-15 (exception handling / fail-safe defaults) | Addressed now | A top-level React error boundary is added; the `usePackagesQuery` placeholder hook's promise-based `queryFn` will have explicit error handling wired through TanStack Query's error state. |
+
+**Summary**: 10 of 15 Security Baseline rules are N/A for this static, no-backend frontend. 4 rules (SECURITY-09, SECURITY-10, SECURITY-13, SECURITY-15) are addressed during this iteration's Code Generation. 2 rules (SECURITY-04, SECURITY-14) are explicitly deferred to the Operations phase.
@@ -0,0 +1,15 @@
+# Tech Stack Decisions — react-frontend-app
+
+| Concern | Decision | Rationale |
+|---|---|---|
+| Build tool | Vite | Confirmed in requirements.md NFR-1; fast dev server, first-class TypeScript/React support, pairs naturally with Vitest. |
+| Language | TypeScript | Confirmed in requirements.md NFR-1; type safety for the domain entities defined in functional design. |
+| UI library | React 18+ | Confirmed in requirements.md NFR-1. |
+| Styling | Tailwind CSS | Confirmed in requirements.md NFR-2. Theme variants implemented as Tailwind theme classes (`theme-red` / `theme-purple`) per Functional Design Question 2 answer. |
+| Routing | TanStack Router, hash-based history (`createHashHistory`) | Confirmed in requirements.md FR-5; hash history chosen per this stage's routing-strategy decision (NFR Requirements Question 4) to be safe on a plain FTP static host without server rewrite rules. |
+| Data fetching (forward-looking) | TanStack Query (`@tanstack/react-query`) | Confirmed in requirements.md FR-5; a `QueryClientProvider` is set up now, with one placeholder query hook (`usePackagesQuery`) as defined in Functional Design. |
+| Testing | Vitest + React Testing Library | NFR Requirements Question 2 answer A. |
+| Linting | ESLint (`typescript-eslint`, `eslint-plugin-react-hooks`) + Prettier | NFR Requirements Question 3 answer A. |
+| Package manager | npm (with committed `package-lock.json`) | Default choice for a Vite-scaffolded project; supports SECURITY-10 (lock file requirement). |
+| CI | None for this iteration | NFR Requirements Question 6 answer B — deferred to Operations phase. |
+| Accessibility | Best-effort (no formal WCAG target this iteration) | NFR Requirements Question 5 answer B; explicit a11y attributes from Functional Design are still implemented. |