Merge pull request #52 from bartstc/feat/local-server

feat(server): replace Fake Store API with custom local server

Author: bartstc

.agents/skills/building-blocks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-blocks
-description: Frontend building block catalog — typed patterns for components, hooks, queries, mutations, stores, and models used across the project. Use this skill whenever implementing, reviewing, or planning feature code, API integrations, state management, component patterns, or data modeling within src/features/ or src/lib/. Also triggers for architectural decisions about where code should live or which pattern to apply.
+description: Frontend building block catalog — typed patterns for components, hooks, queries, mutations, stores, and models. ALWAYS read the relevant rule file before creating or modifying any building block in src/features/ or src/lib/. This includes spec implementation (read rule files for every block in the Building Blocks Diff), new feature work, refactoring, and architectural decisions.
 ---
 
 # Frontend Building Blocks

.env

@@ -1,5 +1,5 @@
 VITE_HTTP_LOGGER_DEBUG_MODE=false
-VITE_FAKE_STORE_API_HOST=https://fakestoreapi.com
+VITE_API=http://localhost:3001/api
 STORYBOOK_DISABLE_TELEMETRY=1
 VERSION=v0.0.0
 BASE_URL=http://localhost:5173

CLAUDE.md

@@ -61,6 +61,7 @@ Package manager: PNPM only. Path alias: `@/*` → `src/`.
 **6. Spec-Driven Development**
 
 - For features spanning 5+ files or 5+ unconstrained decisions, write a spec first using writing-spec skill
+- When implementing a spec, read the building-blocks skill rule files for each block listed in the Building Blocks Diff before writing code
 - Skip when the developer opts out
 
 ## Conventions

README.md

@@ -33,12 +33,18 @@ An opinionated, production-ready starter for **Single Page Application** develop
 
 ### Architecture
 
+```
+src/        React SPA (features, pages, lib)
+server/     Local Fastify API server (dev/demo)
+e2e/        Playwright end-to-end tests
+```
+
 - Feature slice architecture with clean architecture principles — each feature has four layers (`components/`, `application/`, `providers/`, `models/`) with strict dependency rules
 - Centralized API layer with endpoint-based organization and type consolidation
 - Spec-driven development for AI-assisted workflows — four-phase gated spec process, typed building block patterns, and a self-improvement loop
 - Formatting utilities for numbers, monetary values, and dates
 - File naming: PascalCase for React components/stories/page objects, kebab-case for everything else
-- A demo app with authentication showcasing the project structure and tooling in action (powered by [Fake Store API](https://fakestoreapi.com/docs))
+- A demo app with authentication showcasing the project structure and tooling in action (powered by a local Fastify server in `server/`)
 - Read more: [`docs/architecture.md`](docs/architecture.md)
 
 ### AI-assisted development
@@ -70,6 +76,8 @@ It's recommended to run the dev server inside a container for consistent Node/PN
 | Command                | Description                                |
 | ---------------------- | ------------------------------------------ |
 | `pnpm dev`             | Dev server with HMR on port `5173`         |
+| `pnpm dev:server`      | Local API server only on port `3001`       |
+| `pnpm dev:all`         | Frontend + API server together             |
 | `pnpm lint`            | Check for lint errors                      |
 | `pnpm build`           | Production build                           |
 | `pnpm test`            | Run all tests (unit + storybook)           |

docs/architecture.md

@@ -55,6 +55,7 @@ Each feature follows feature slice architecture patterns with four layers:
 - **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, domain errors, and DTOs sourced from `src/lib/api/`. Library-specific code (React Query, etc.) must not leak beyond this layer.
   - files are named after their primary export or reexport: `useCartProductsQuery` → `use-cart-products-query.ts`, `useAddToCartMutation` → `use-add-to-cart-mutation.ts`
 - **models/** - Domain type definitions, utilities, and type mapping functions.
+  - exposes frontend models for the feature. Components, application, and pages import types from `models/`, never directly from `src/lib/api/`. When the DTO shape is identical, a simple re-export with a domain name suffices (`export type { ProductDto as Product }`). When it diverges, map to a dedicated frontend model.
 
 **Dependency rule:** `components/` and `application/` import from `models/` and `providers/`. `providers/` and `models/` have no internal feature dependencies.
 
@@ -95,6 +96,14 @@ Never use `-command.ts`, `-service.ts`, or other suffixes.
 
 XState is preferred for business processes where states must be explicit and transitions constrained.
 
+## Internationalization
+
+- Translation files live in `public/locales/{lang}/translation.json`
+- Keys mirror the feature path e.g. `features.products.<key>`
+- All user-facing text goes through i18next — no hardcoded strings in components
+- When adding any value that renders as a user-facing label, add the corresponding translation key in the same task
+- When removing a value, remove its stale translation key
+
 ## Routing
 
 - **File-based routing** - Pages in `src/pages/` with corresponding loaders

e2e/fixtures/credentials-fixture.ts

@@ -1,15 +1,14 @@
 import type { User } from "@/features/auth/models/user";
 import { UserFixture } from "@/test-lib/fixtures/user-fixture";
 
-// AIDEV-NOTE: Reuses UserFixture from @/test-lib for domain data, adds E2E-specific password field
 export interface TestCredentials {
   user: User;
   password: string;
 }
 
 export const ValidUserCredentials: TestCredentials = {
-  user: UserFixture.createPermutation({ username: "mor_2314" }),
-  password: "83r5^_",
+  user: UserFixture.createPermutation({ username: "bob" }),
+  password: "Pa$$w0rd",
 };
 
 export const InvalidUserCredentials: TestCredentials = {

e2e/pages/components/ProductCardComponent.ts

@@ -7,14 +7,11 @@ export class ProductCardComponent {
     _page: Page,
     private root: Locator
   ) {
-    // AIDEV-NOTE: Using semantic locators - no test IDs needed
     this.addToCartButton = root.getByRole("button", { name: /add to cart/i });
   }
 
   async click(): Promise<void> {
-    // AIDEV-NOTE: Click the product card image area to navigate to product details
-    // The Box with background image has onClick handler for navigation
-    await this.root.locator("div").first().click();
+    await this.root.getByRole("img").click();
   }
 
   async addToCart(): Promise<void> {

e2e/pages/index.ts

@@ -7,13 +7,24 @@ import { ProductDetailsPage } from "@e2e/pages/products/ProductDetailsPage";
 import { ProductListPage } from "@e2e/pages/products/ProductListPage";
 
 interface PageFixtures {
+  resetDb: void;
   signInPage: SignInPage;
   productListPage: ProductListPage;
   productDetailsPage: ProductDetailsPage;
   cartPage: CartPage;
 }
 
+const API_BASE = process.env.VITE_API ?? "http://localhost:3001/api";
+
 export const test = base.extend<PageFixtures>({
+  // AIDEV-NOTE: Auto fixture — resets DB to seed state before every test for isolation
+  resetDb: [
+    async ({ request }, use) => {
+      await request.post(`${API_BASE}/test/reset`);
+      await use();
+    },
+    { auto: true },
+  ],
   signInPage: async ({ page }, use) => {
     await use(new SignInPage(page));
   },

e2e/pages/products/ProductDetailsPage.ts

@@ -26,16 +26,12 @@ export class ProductDetailsPage extends BasePage {
     });
   }
 
-  private async goto(productId: string): Promise<this> {
-    await this.page.goto(`/products/${productId}`, {
-      waitUntil: "networkidle",
-    });
-    return this;
-  }
-
   async gotoFirstProduct(): Promise<this> {
-    // AIDEV-NOTE: Navigate to first product (ID = 1) as E2E uses real API data
-    return this.goto("1");
+    // AIDEV-NOTE: Navigate via products list to avoid hardcoding ID format
+    await this.page.goto("/products", { waitUntil: "networkidle" });
+    await this.page.getByRole("article").first().getByRole("img").click();
+    await this.page.waitForURL(/\/products\/.+/, { waitUntil: "networkidle" });
+    return this;
   }
 
   async addToCart(): Promise<this> {

e2e/pages/products/ProductListPage.ts

@@ -21,24 +21,20 @@ export class ProductListPage extends BasePage {
 
   async waitForProductsToLoad(): Promise<void> {
     // AIDEV-NOTE: Wait for at least one "Add to cart" button to appear
-    // This indicates products have loaded, without needing a test ID on the grid
+    // This indicates products have loaded
     await this.page
       .getByRole("button", { name: /add to cart/i })
       .first()
       .waitFor({ state: "visible" });
   }
 
   async getProductCount(): Promise<number> {
-    // AIDEV-NOTE: Count product cards by counting <article> elements
-    // Each ProductCard renders as a semantic <article> element
-    const cards = await this.page.locator("article").all();
+    const cards = await this.page.getByRole("article").all();
     return cards.length;
   }
 
   private getProductCard(index = 0): ProductCardComponent {
-    // AIDEV-NOTE: Get product card by index (default: first product)
-    // E2E tests use real API data, so we can't rely on specific product names
-    const cardRoot = this.page.locator("article").nth(index);
+    const cardRoot = this.page.getByRole("article").nth(index);
 
     return new ProductCardComponent(this.page, cardRoot);
   }