From 75437272dd1c4c2da5621d0b1081b2e27a73b116 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:04:07 +0000
Subject: [PATCH 1/3] Initial plan


From 94301a2988a97154577d982532ee720bde8b8f3c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:15:18 +0000
Subject: [PATCH 2/3] Add comprehensive frontend documentation

Co-authored-by: webmaxru <1560278+webmaxru@users.noreply.github.com>
---
 docs/frontend/README.md            |  68 +++
 docs/frontend/api-integration.md   | 787 +++++++++++++++++++++++++++++
 docs/frontend/architecture.md      | 386 ++++++++++++++
 docs/frontend/code-organization.md | 777 ++++++++++++++++++++++++++++
 docs/frontend/components.md        | 614 ++++++++++++++++++++++
 docs/frontend/setup.md             | 493 ++++++++++++++++++
 docs/frontend/styling.md           | 719 ++++++++++++++++++++++++++
 docs/frontend/testing.md           | 719 ++++++++++++++++++++++++++
 frontend/README.md                 | 183 +++++--
 9 files changed, 4695 insertions(+), 51 deletions(-)
 create mode 100644 docs/frontend/README.md
 create mode 100644 docs/frontend/api-integration.md
 create mode 100644 docs/frontend/architecture.md
 create mode 100644 docs/frontend/code-organization.md
 create mode 100644 docs/frontend/components.md
 create mode 100644 docs/frontend/setup.md
 create mode 100644 docs/frontend/styling.md
 create mode 100644 docs/frontend/testing.md

diff --git a/docs/frontend/README.md b/docs/frontend/README.md
new file mode 100644
index 0000000..31befa3
--- /dev/null
+++ b/docs/frontend/README.md
@@ -0,0 +1,68 @@
+# Frontend Documentation
+
+Welcome to the OctoCAT Supply Chain Management frontend documentation. This guide provides comprehensive information about the React-based frontend application.
+
+## Table of Contents
+
+1. [Architecture Overview](./architecture.md) - Component structure, state management, routing, and API integration patterns
+2. [Setup and Development](./setup.md) - Prerequisites, environment configuration, and development workflow
+3. [Component Documentation](./components.md) - Detailed documentation of key components, props, and usage examples
+4. [Styling Guidelines](./styling.md) - Tailwind CSS conventions, theme system, and responsive design approach
+5. [API Integration](./api-integration.md) - API client configuration, error handling, and authentication flow
+6. [Testing](./testing.md) - Testing strategy, tools, and example patterns
+7. [Code Organization](./code-organization.md) - Folder structure, naming conventions, and best practices
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run linter
+npm run lint
+```
+
+## Technology Stack
+
+- **React 18+** - UI library
+- **TypeScript** - Type-safe JavaScript
+- **Vite** - Build tool and dev server
+- **Tailwind CSS** - Utility-first CSS framework
+- **React Router v7** - Client-side routing
+- **React Query** - Server state management
+- **Axios** - HTTP client
+
+## Key Features
+
+- 🎨 Dark/Light theme support with Context API
+- 🔐 Authentication system with role-based access
+- 📱 Fully responsive design
+- 🚀 Fast development with Vite HMR
+- 🎯 Type-safe with TypeScript
+- ♿ Accessibility-focused components
+
+## Project Overview
+
+The frontend is a single-page application (SPA) that provides a modern user interface for the OctoCAT Supply Chain Management System. It communicates with the backend REST API to manage products, orders, suppliers, and other supply chain entities.
+
+For overall system architecture, refer to the [main architecture documentation](../architecture.md).
+
+## Getting Help
+
+- Check the detailed documentation pages for specific topics
+- Review component examples in the codebase
+- See [troubleshooting section in setup.md](./setup.md#troubleshooting)
+
+## Contributing
+
+When adding new features or components:
+1. Follow the established [code organization](./code-organization.md) patterns
+2. Adhere to the [styling guidelines](./styling.md)
+3. Update relevant documentation
+4. Add appropriate tests (see [testing guide](./testing.md))
diff --git a/docs/frontend/api-integration.md b/docs/frontend/api-integration.md
new file mode 100644
index 0000000..5c5de02
--- /dev/null
+++ b/docs/frontend/api-integration.md
@@ -0,0 +1,787 @@
+# API Integration
+
+This guide covers how the frontend integrates with the backend REST API, including configuration, error handling, and authentication patterns.
+
+## Table of Contents
+
+- [API Configuration](#api-configuration)
+- [Making API Requests](#making-api-requests)
+- [React Query Integration](#react-query-integration)
+- [Error Handling](#error-handling)
+- [Authentication Flow](#authentication-flow)
+- [API Endpoints](#api-endpoints)
+- [Request/Response Patterns](#requestresponse-patterns)
+- [Best Practices](#best-practices)
+
+---
+
+## API Configuration
+
+### Configuration File
+
+**Location:** `src/api/config.ts`
+
+This file handles API base URL detection and provides centralized endpoint definitions.
+
+### Base URL Detection Logic
+
+The API URL is determined in the following order:
+
+1. **Runtime Configuration** (highest priority)
+   - Checks `window.RUNTIME_CONFIG.API_URL`
+   - Useful for Docker/production deployments
+
+2. **GitHub Codespaces Detection**
+   - Auto-detects Codespace hostname patterns
+   - Maps to port 3000 on the same codespace
+
+3. **Local Development** (fallback)
+   - Uses `http://localhost:3000`
+   - Protocol matches frontend (http/https)
+
+### Configuration Code
+
+```typescript
+const getBaseUrl = () => {
+  // Check runtime configuration
+  if (typeof window !== 'undefined' && window.RUNTIME_CONFIG?.API_URL) {
+    return window.RUNTIME_CONFIG.API_URL;
+  }
+
+  // Detect protocol
+  const protocol = typeof window !== 'undefined' ? window.location.protocol : 'https:';
+  const protocolToUse = protocol.includes('https') ? 'https' : 'http';
+
+  // Detect GitHub Codespaces
+  if (typeof window !== 'undefined') {
+    const host = window.location.hostname;
+    const codespacesMatch =
+      host.match(/^(.*)-(\d+)\.app\.github\.dev$/) ||
+      host.match(/^(.*)-(\d+)\.githubpreview\.dev$/);
+    if (codespacesMatch) {
+      return `${protocolToUse}://${codespacesMatch[1]}-3000.app.github.dev`;
+    }
+  }
+
+  // Default to localhost
+  return `${protocolToUse}://localhost:3000`;
+};
+
+export const API_BASE_URL = getBaseUrl();
+```
+
+### Endpoint Definitions
+
+```typescript
+export const api = {
+  baseURL: API_BASE_URL,
+  endpoints: {
+    products: '/api/products',
+    suppliers: '/api/suppliers',
+    orders: '/api/orders',
+    branches: '/api/branches',
+    headquarters: '/api/headquarters',
+    deliveries: '/api/deliveries',
+    orderDetails: '/api/order-details',
+    orderDetailDeliveries: '/api/order-detail-deliveries',
+  },
+};
+```
+
+### Environment-Specific Configuration
+
+**Production (Docker):**
+
+Create `public/runtime-config.js`:
+
+```javascript
+window.RUNTIME_CONFIG = {
+  API_URL: 'https://api.your-domain.com'
+};
+```
+
+Include in `index.html`:
+
+```html
+<script src="/runtime-config.js"></script>
+```
+
+**Local Development:**
+
+No configuration needed. Defaults to `http://localhost:3000`.
+
+**Codespaces:**
+
+Automatically detected and configured.
+
+---
+
+## Making API Requests
+
+### Using Axios
+
+The application uses Axios for HTTP requests.
+
+**Installation:**
+```bash
+npm install axios
+```
+
+**Basic GET Request:**
+
+```typescript
+import axios from 'axios';
+import { api } from '../api/config';
+
+const fetchProducts = async () => {
+  const response = await axios.get(`${api.baseURL}${api.endpoints.products}`);
+  return response.data;
+};
+```
+
+**GET Request with ID:**
+
+```typescript
+const fetchProduct = async (id: number) => {
+  const response = await axios.get(`${api.baseURL}${api.endpoints.products}/${id}`);
+  return response.data;
+};
+```
+
+**POST Request:**
+
+```typescript
+const createProduct = async (productData: Partial<Product>) => {
+  const response = await axios.post(
+    `${api.baseURL}${api.endpoints.products}`,
+    productData
+  );
+  return response.data;
+};
+```
+
+**PUT Request:**
+
+```typescript
+const updateProduct = async (id: number, productData: Partial<Product>) => {
+  const response = await axios.put(
+    `${api.baseURL}${api.endpoints.products}/${id}`,
+    productData
+  );
+  return response.data;
+};
+```
+
+**DELETE Request:**
+
+```typescript
+const deleteProduct = async (id: number) => {
+  await axios.delete(`${api.baseURL}${api.endpoints.products}/${id}`);
+};
+```
+
+---
+
+## React Query Integration
+
+### Overview
+
+React Query manages server state (fetching, caching, synchronization) with minimal boilerplate.
+
+**Installation:**
+```bash
+npm install react-query
+```
+
+### Setup
+
+**No setup required** - React Query is used directly in components without a provider in the current implementation.
+
+### Basic Query
+
+```typescript
+import { useQuery } from 'react-query';
+import axios from 'axios';
+import { api } from '../api/config';
+
+function Products() {
+  const { data, isLoading, error } = useQuery('products', async () => {
+    const response = await axios.get(`${api.baseURL}${api.endpoints.products}`);
+    return response.data;
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error loading products</div>;
+
+  return <div>{/* Render products */}</div>;
+}
+```
+
+### Query with Parameters
+
+```typescript
+const fetchProduct = async (id: number) => {
+  const { data } = await axios.get(`${api.baseURL}${api.endpoints.products}/${id}`);
+  return data;
+};
+
+function ProductDetail({ productId }: { productId: number }) {
+  const { data: product, isLoading } = useQuery(
+    ['product', productId],  // Query key includes parameter
+    () => fetchProduct(productId)
+  );
+
+  // Component logic
+}
+```
+
+### Mutations
+
+For create, update, delete operations:
+
+```typescript
+import { useMutation, useQueryClient } from 'react-query';
+
+function ProductForm() {
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation(
+    (newProduct: Product) => axios.post(`${api.baseURL}${api.endpoints.products}`, newProduct),
+    {
+      onSuccess: () => {
+        // Invalidate and refetch products query
+        queryClient.invalidateQueries('products');
+      },
+    }
+  );
+
+  const handleSubmit = (productData: Product) => {
+    mutation.mutate(productData);
+  };
+
+  return <form onSubmit={handleSubmit}>{/* Form fields */}</form>;
+}
+```
+
+### React Query Benefits
+
+- **Automatic Caching** - Avoids redundant network requests
+- **Background Refetching** - Keeps data fresh
+- **Loading & Error States** - Built-in state management
+- **Request Deduplication** - Multiple components requesting same data = one request
+- **Optimistic Updates** - Update UI before server response
+
+---
+
+## Error Handling
+
+### Component-Level Error Handling
+
+**Display Error State:**
+
+```typescript
+const { data, isLoading, error } = useQuery('products', fetchProducts);
+
+if (error) {
+  return (
+    <div className="text-red-500 text-center">
+      Failed to fetch products. Please try again later.
+    </div>
+  );
+}
+```
+
+### Try-Catch Error Handling
+
+For manual API calls (outside React Query):
+
+```typescript
+const handleDelete = async (productId: number) => {
+  try {
+    await axios.delete(`${api.baseURL}${api.endpoints.products}/${productId}`);
+    alert('Product deleted successfully');
+    fetchProducts(); // Refresh list
+  } catch (error) {
+    console.error('Error deleting product:', error);
+    alert('Failed to delete product');
+  }
+};
+```
+
+### Axios Error Structure
+
+```typescript
+try {
+  await axios.get('/api/endpoint');
+} catch (error) {
+  if (axios.isAxiosError(error)) {
+    console.error('Status:', error.response?.status);
+    console.error('Data:', error.response?.data);
+    console.error('Message:', error.message);
+  }
+}
+```
+
+### HTTP Status Code Handling
+
+```typescript
+try {
+  await axios.get(`${api.baseURL}${api.endpoints.products}/${id}`);
+} catch (error) {
+  if (axios.isAxiosError(error)) {
+    if (error.response?.status === 404) {
+      alert('Product not found');
+    } else if (error.response?.status === 500) {
+      alert('Server error. Please try again later.');
+    } else {
+      alert('An error occurred');
+    }
+  }
+}
+```
+
+### Global Error Handling (Future Enhancement)
+
+Consider adding an Axios interceptor:
+
+```typescript
+axios.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    // Global error handling logic
+    if (error.response?.status === 401) {
+      // Redirect to login
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## Authentication Flow
+
+### Current Implementation
+
+The current authentication is **mock/client-side only** and suitable for demos.
+
+**How It Works:**
+
+1. User enters email and password
+2. `AuthContext.login()` checks if email and password exist
+3. Sets `isLoggedIn = true`
+4. Sets `isAdmin = true` if email ends with `@github.com`
+5. No server validation or session persistence
+
+**Code:**
+
+```typescript
+// src/context/AuthContext.tsx
+
+const login = async (email: string, password: string) => {
+  if (email && password) {
+    setIsLoggedIn(true);
+    setIsAdmin(email.endsWith('@github.com'));
+  }
+};
+
+const logout = () => {
+  setIsLoggedIn(false);
+  setIsAdmin(false);
+};
+```
+
+### Real Authentication (Future Implementation)
+
+For production, implement proper authentication:
+
+**1. Login Endpoint:**
+
+```typescript
+const login = async (email: string, password: string) => {
+  try {
+    const response = await axios.post(`${api.baseURL}/api/auth/login`, {
+      email,
+      password,
+    });
+    
+    const { token, user } = response.data;
+    
+    // Store token in localStorage or httpOnly cookie
+    localStorage.setItem('authToken', token);
+    
+    setIsLoggedIn(true);
+    setIsAdmin(user.role === 'admin');
+  } catch (error) {
+    console.error('Login failed:', error);
+    throw error;
+  }
+};
+```
+
+**2. Axios Interceptor for Token:**
+
+```typescript
+axios.interceptors.request.use((config) => {
+  const token = localStorage.getItem('authToken');
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+```
+
+**3. Logout Endpoint:**
+
+```typescript
+const logout = async () => {
+  try {
+    await axios.post(`${api.baseURL}/api/auth/logout`);
+  } finally {
+    localStorage.removeItem('authToken');
+    setIsLoggedIn(false);
+    setIsAdmin(false);
+  }
+};
+```
+
+**4. Protected Route Check:**
+
+```typescript
+useEffect(() => {
+  const token = localStorage.getItem('authToken');
+  if (token) {
+    // Validate token with API
+    axios.get(`${api.baseURL}/api/auth/me`)
+      .then(response => {
+        setIsLoggedIn(true);
+        setIsAdmin(response.data.role === 'admin');
+      })
+      .catch(() => {
+        localStorage.removeItem('authToken');
+      });
+  }
+}, []);
+```
+
+---
+
+## API Endpoints
+
+### Available Endpoints
+
+All endpoints are prefixed with `/api/`:
+
+| Entity | Endpoint | Methods |
+|--------|----------|---------|
+| Products | `/api/products` | GET, POST |
+| Products (single) | `/api/products/:id` | GET, PUT, DELETE |
+| Suppliers | `/api/suppliers` | GET, POST |
+| Suppliers (single) | `/api/suppliers/:id` | GET, PUT, DELETE |
+| Orders | `/api/orders` | GET, POST |
+| Orders (single) | `/api/orders/:id` | GET, PUT, DELETE |
+| Branches | `/api/branches` | GET, POST |
+| Branches (single) | `/api/branches/:id` | GET, PUT, DELETE |
+| Headquarters | `/api/headquarters` | GET, POST |
+| Headquarters (single) | `/api/headquarters/:id` | GET, PUT, DELETE |
+| Deliveries | `/api/deliveries` | GET, POST |
+| Deliveries (single) | `/api/deliveries/:id` | GET, PUT, DELETE |
+| Order Details | `/api/order-details` | GET, POST |
+| Order Details (single) | `/api/order-details/:id` | GET, PUT, DELETE |
+| Order Detail Deliveries | `/api/order-detail-deliveries` | GET, POST |
+| Order Detail Deliveries (single) | `/api/order-detail-deliveries/:id` | GET, PUT, DELETE |
+
+### Endpoint Usage Examples
+
+**Fetch all products:**
+```typescript
+GET ${api.baseURL}/api/products
+```
+
+**Fetch single product:**
+```typescript
+GET ${api.baseURL}/api/products/123
+```
+
+**Create product:**
+```typescript
+POST ${api.baseURL}/api/products
+Body: { name: "Product", price: 10.99, ... }
+```
+
+**Update product:**
+```typescript
+PUT ${api.baseURL}/api/products/123
+Body: { name: "Updated Product", ... }
+```
+
+**Delete product:**
+```typescript
+DELETE ${api.baseURL}/api/products/123
+```
+
+---
+
+## Request/Response Patterns
+
+### TypeScript Interfaces
+
+Define interfaces matching API responses:
+
+```typescript
+interface Product {
+  productId: number;
+  name: string;
+  description: string;
+  price: number;
+  imgName: string;
+  sku: string;
+  unit: string;
+  supplierId: number;
+  discount?: number;
+}
+
+interface Supplier {
+  supplierId: number;
+  name: string;
+  description: string;
+  contactPerson: string;
+  email: string;
+  phone: string;
+}
+```
+
+### Response Handling
+
+**List Response:**
+
+```typescript
+const fetchProducts = async (): Promise<Product[]> => {
+  const { data } = await axios.get(`${api.baseURL}${api.endpoints.products}`);
+  return data; // Assumes API returns array directly
+};
+```
+
+**Single Item Response:**
+
+```typescript
+const fetchProduct = async (id: number): Promise<Product> => {
+  const { data } = await axios.get(`${api.baseURL}${api.endpoints.products}/${id}`);
+  return data;
+};
+```
+
+### Request Payload
+
+**Create/Update:**
+
+```typescript
+const productData: Partial<Product> = {
+  name: 'New Product',
+  description: 'Description',
+  price: 29.99,
+  sku: 'SKU123',
+  unit: 'unit',
+  supplierId: 1,
+  imgName: 'product.png',
+};
+
+await axios.post(`${api.baseURL}${api.endpoints.products}`, productData);
+```
+
+---
+
+## Best Practices
+
+### 1. Centralize API Calls
+
+Create dedicated functions for API calls:
+
+```typescript
+// src/api/products.ts
+export const productApi = {
+  getAll: () => axios.get(`${api.baseURL}${api.endpoints.products}`),
+  getById: (id: number) => axios.get(`${api.baseURL}${api.endpoints.products}/${id}`),
+  create: (data: Partial<Product>) => axios.post(`${api.baseURL}${api.endpoints.products}`, data),
+  update: (id: number, data: Partial<Product>) => axios.put(`${api.baseURL}${api.endpoints.products}/${id}`, data),
+  delete: (id: number) => axios.delete(`${api.baseURL}${api.endpoints.products}/${id}`),
+};
+```
+
+### 2. Use React Query for All Data Fetching
+
+Prefer React Query over manual `useEffect` + `useState`:
+
+❌ **Not Recommended:**
+```typescript
+const [products, setProducts] = useState([]);
+const [loading, setLoading] = useState(false);
+
+useEffect(() => {
+  setLoading(true);
+  axios.get(url)
+    .then(res => setProducts(res.data))
+    .finally(() => setLoading(false));
+}, []);
+```
+
+✅ **Recommended:**
+```typescript
+const { data: products, isLoading } = useQuery('products', fetchProducts);
+```
+
+### 3. Handle Loading and Error States
+
+Always handle loading and error states:
+
+```typescript
+if (isLoading) return <LoadingSpinner />;
+if (error) return <ErrorMessage />;
+return <DataDisplay data={data} />;
+```
+
+### 4. Type Safety
+
+Use TypeScript interfaces for all API data:
+
+```typescript
+const { data } = useQuery<Product[]>('products', fetchProducts);
+```
+
+### 5. Consistent Error Messages
+
+Provide user-friendly error messages:
+
+```typescript
+if (error) {
+  return <div>Unable to load products. Please try again later.</div>;
+}
+```
+
+### 6. Optimistic Updates
+
+For better UX, update UI before API confirmation:
+
+```typescript
+const mutation = useMutation(updateProduct, {
+  onMutate: async (newProduct) => {
+    // Cancel outgoing refetches
+    await queryClient.cancelQueries('products');
+
+    // Snapshot previous value
+    const previousProducts = queryClient.getQueryData('products');
+
+    // Optimistically update
+    queryClient.setQueryData('products', (old: Product[]) => 
+      old.map(p => p.id === newProduct.id ? newProduct : p)
+    );
+
+    // Return context with snapshot
+    return { previousProducts };
+  },
+  onError: (err, newProduct, context) => {
+    // Rollback on error
+    queryClient.setQueryData('products', context.previousProducts);
+  },
+});
+```
+
+### 7. Request Deduplication
+
+React Query automatically deduplicates requests, but for manual calls, track inflight requests:
+
+```typescript
+let inflightRequest: Promise<any> | null = null;
+
+const fetchProducts = async () => {
+  if (inflightRequest) return inflightRequest;
+  
+  inflightRequest = axios.get(url);
+  const result = await inflightRequest;
+  inflightRequest = null;
+  
+  return result;
+};
+```
+
+### 8. API Call Logging (Development)
+
+Log API calls during development:
+
+```typescript
+const fetchProducts = async () => {
+  console.log('Fetching products from:', `${api.baseURL}${api.endpoints.products}`);
+  const response = await axios.get(`${api.baseURL}${api.endpoints.products}`);
+  console.log('Products received:', response.data);
+  return response.data;
+};
+```
+
+### 9. CORS Handling
+
+If encountering CORS issues:
+- Ensure backend has CORS enabled
+- Check API URL is correct
+- For development, proxy can be configured in `vite.config.ts`:
+
+```typescript
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': 'http://localhost:3000'
+    }
+  }
+});
+```
+
+### 10. Timeout Configuration
+
+Set reasonable timeouts for API calls:
+
+```typescript
+axios.create({
+  baseURL: api.baseURL,
+  timeout: 10000, // 10 seconds
+});
+```
+
+---
+
+## Debugging Tips
+
+### Check API URL
+
+```typescript
+console.log('API Base URL:', API_BASE_URL);
+```
+
+### Network Tab
+
+- Open browser DevTools → Network tab
+- Filter by "Fetch/XHR"
+- Inspect request/response details
+
+### React Query DevTools (Future Enhancement)
+
+Install and use React Query DevTools:
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+```typescript
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+<QueryClientProvider client={queryClient}>
+  <App />
+  <ReactQueryDevtools initialIsOpen={false} />
+</QueryClientProvider>
+```
+
+---
+
+## Related Documentation
+
+- [Setup Guide](./setup.md) - Environment configuration
+- [Architecture](./architecture.md) - Overall system design
+- [Backend API Documentation](../../api/api-swagger.json) - Full API specification
diff --git a/docs/frontend/architecture.md b/docs/frontend/architecture.md
new file mode 100644
index 0000000..3b15541
--- /dev/null
+++ b/docs/frontend/architecture.md
@@ -0,0 +1,386 @@
+# Frontend Architecture
+
+## Overview
+
+The frontend is built as a modern React single-page application (SPA) using TypeScript, Vite, and Tailwind CSS. The architecture follows a component-based approach with centralized state management for cross-cutting concerns.
+
+## Component Structure
+
+### High-Level Organization
+
+```
+src/
+├── components/         # Reusable UI components
+│   ├── admin/         # Admin-specific components
+│   ├── entity/        # Domain entity components
+│   │   └── product/   # Product-related components
+│   ├── About.tsx
+│   ├── Footer.tsx
+│   ├── Login.tsx
+│   ├── Navigation.tsx
+│   └── Welcome.tsx
+├── context/           # React Context providers
+│   ├── AuthContext.tsx
+│   ├── ThemeContext.tsx
+│   ├── themeContextUtils.tsx
+│   └── useTheme.tsx
+├── api/              # API configuration
+│   └── config.ts
+├── assets/           # Static assets (images, etc.)
+├── App.tsx           # Root application component
+├── main.tsx          # Application entry point
+└── index.css         # Global styles
+```
+
+### Component Patterns
+
+#### Page Components
+Top-level components that represent entire pages/routes:
+- `Welcome.tsx` - Landing page
+- `About.tsx` - About page
+- `Login.tsx` - Login page
+- `Products.tsx` - Product listing page
+- `AdminProducts.tsx` - Admin product management
+
+#### Layout Components
+Structural components used across multiple pages:
+- `Navigation.tsx` - Top navigation bar with theme toggle and auth controls
+- `Footer.tsx` - Footer displayed on all pages
+
+#### Entity Components
+Domain-specific components organized by entity type:
+- `entity/product/Products.tsx` - Product list view
+- `entity/product/ProductForm.tsx` - Product creation/editing form
+
+#### Admin Components
+Protected components for administrative functions:
+- `admin/AdminProducts.tsx` - Admin product management interface
+
+## State Management
+
+### Context API
+
+The application uses React Context API for managing global application state. Two primary contexts are implemented:
+
+#### 1. AuthContext
+
+**Purpose:** Manages authentication state and user authorization.
+
+**State:**
+- `isLoggedIn: boolean` - Whether a user is authenticated
+- `isAdmin: boolean` - Whether the logged-in user has admin privileges
+
+**Methods:**
+- `login(email: string, password: string): Promise<void>` - Authenticates user
+- `logout(): void` - Clears authentication state
+
+**Usage:**
+```typescript
+import { useAuth } from '../context/AuthContext';
+
+function MyComponent() {
+  const { isLoggedIn, isAdmin, login, logout } = useAuth();
+  
+  // Use authentication state and methods
+}
+```
+
+**Implementation Notes:**
+- Currently uses client-side mock authentication (checks email domain)
+- Admin access granted to `@github.com` email addresses
+- State is not persisted across page refreshes (no session storage/cookies)
+
+#### 2. ThemeContext
+
+**Purpose:** Manages dark/light theme preferences.
+
+**State:**
+- `darkMode: boolean` - Current theme mode
+
+**Methods:**
+- `toggleTheme(): void` - Switches between dark and light themes
+
+**Usage:**
+```typescript
+import { useTheme } from '../context/ThemeContext';
+
+function MyComponent() {
+  const { darkMode, toggleTheme } = useTheme();
+  
+  return (
+    <div className={darkMode ? 'bg-dark' : 'bg-light'}>
+      <button onClick={toggleTheme}>Toggle Theme</button>
+    </div>
+  );
+}
+```
+
+**Implementation Notes:**
+- Theme preference persisted in `localStorage`
+- Adds `dark` or `light` class to `document.documentElement` for Tailwind
+- Theme changes trigger smooth CSS transitions (300ms)
+
+### Local Component State
+
+For component-specific state (form inputs, UI toggles, local data), standard React `useState` and `useEffect` hooks are used:
+
+```typescript
+const [adminMenuOpen, setAdminMenuOpen] = useState(false);
+```
+
+### Server State (React Query)
+
+React Query is used for managing server state (data fetching, caching, synchronization):
+
+```typescript
+import { useQuery } from 'react-query';
+
+const { data, isLoading, error } = useQuery('products', fetchProducts);
+```
+
+Benefits:
+- Automatic caching and background refetching
+- Built-in loading and error states
+- Optimistic updates support
+- Request deduplication
+
+## Routing Structure
+
+React Router v7 is used for client-side routing with the `BrowserRouter` strategy.
+
+### Route Configuration
+
+```typescript
+<Router>
+  <Routes>
+    <Route path="/" element={<Welcome />} />
+    <Route path="/about" element={<About />} />
+    <Route path="/products" element={<Products />} />
+    <Route path="/login" element={<Login />} />
+    <Route path="/admin/products" element={<AdminProducts />} />
+  </Routes>
+</Router>
+```
+
+### Route Hierarchy
+
+- `/` - Welcome/home page
+- `/about` - About page
+- `/products` - Public product listing
+- `/login` - User login
+- `/admin/products` - Admin product management (protected)
+
+### Navigation
+
+Navigation between routes uses the `Link` component:
+
+```typescript
+import { Link } from 'react-router-dom';
+
+<Link to="/products">View Products</Link>
+```
+
+### Protected Routes
+
+Admin routes check authentication state via `useAuth()`:
+
+```typescript
+const { isAdmin } = useAuth();
+
+if (!isAdmin) {
+  return <Navigate to="/login" />;
+}
+```
+
+## API Integration Patterns
+
+### API Configuration
+
+The API client is configured in `src/api/config.ts` with intelligent URL detection:
+
+1. **Runtime Configuration** - Checks `window.RUNTIME_CONFIG.API_URL`
+2. **Codespace Detection** - Auto-detects GitHub Codespaces environment
+3. **Fallback** - Uses `http://localhost:3000` for local development
+
+### API Structure
+
+```typescript
+export const api = {
+  baseURL: API_BASE_URL,
+  endpoints: {
+    products: '/api/products',
+    suppliers: '/api/suppliers',
+    orders: '/api/orders',
+    branches: '/api/branches',
+    headquarters: '/api/headquarters',
+    deliveries: '/api/deliveries',
+    orderDetails: '/api/order-details',
+    orderDetailDeliveries: '/api/order-detail-deliveries',
+  },
+};
+```
+
+### Making API Calls
+
+Components use React Query with Axios for API calls:
+
+```typescript
+import axios from 'axios';
+import { useQuery } from 'react-query';
+import { api } from '../api/config';
+
+const fetchProducts = async () => {
+  const response = await axios.get(`${api.baseURL}${api.endpoints.products}`);
+  return response.data;
+};
+
+function Products() {
+  const { data, isLoading, error } = useQuery('products', fetchProducts);
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error loading products</div>;
+  
+  return <ProductList products={data} />;
+}
+```
+
+### Error Handling
+
+API errors are handled at multiple levels:
+
+1. **React Query Error State** - Captured in query result
+2. **Component-Level** - Display user-friendly error messages
+3. **Global Error Boundary** - Catch unhandled errors (future enhancement)
+
+## Component Communication
+
+### Parent-Child Communication
+
+**Props Down:**
+```typescript
+<ProductCard 
+  product={product}
+  onEdit={handleEdit}
+  darkMode={darkMode}
+/>
+```
+
+**Events Up:**
+```typescript
+<button onClick={() => onEdit(product.id)}>Edit</button>
+```
+
+### Sibling Communication
+
+For sibling components, lift state to common parent or use Context:
+
+```typescript
+function Parent() {
+  const [selectedProduct, setSelectedProduct] = useState(null);
+  
+  return (
+    <>
+      <ProductList onSelect={setSelectedProduct} />
+      <ProductDetail product={selectedProduct} />
+    </>
+  );
+}
+```
+
+### Cross-Component Communication
+
+Use Context API for truly global state:
+- Authentication status → AuthContext
+- Theme preferences → ThemeContext
+
+## Data Flow
+
+```
+User Interaction
+      ↓
+Component Event Handler
+      ↓
+State Update (useState/Context)
+      ↓
+Re-render with New State
+      ↓
+Optional: API Call via React Query
+      ↓
+Cache Update & Component Re-render
+```
+
+## Performance Considerations
+
+### Code Splitting
+
+Currently using single bundle. Future optimization: lazy load routes.
+
+```typescript
+// Future enhancement
+const AdminProducts = lazy(() => import('./components/admin/AdminProducts'));
+```
+
+### Memoization
+
+Use React.memo for expensive component renders:
+
+```typescript
+export default React.memo(ProductCard);
+```
+
+### React Query Caching
+
+React Query automatically caches API responses:
+- Reduces unnecessary network requests
+- Provides instant data for repeated queries
+- Background refetching keeps data fresh
+
+## TypeScript Integration
+
+### Type Safety
+
+All components use TypeScript for type safety:
+
+```typescript
+interface Product {
+  id: number;
+  name: string;
+  description: string;
+  price: number;
+}
+
+interface ProductCardProps {
+  product: Product;
+  onEdit?: (id: number) => void;
+}
+
+function ProductCard({ product, onEdit }: ProductCardProps) {
+  // Component implementation
+}
+```
+
+### Context Types
+
+Context providers have strongly typed values:
+
+```typescript
+interface AuthContextType {
+  isLoggedIn: boolean;
+  isAdmin: boolean;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+}
+```
+
+## Future Architecture Enhancements
+
+Potential improvements for the architecture:
+
+1. **Lazy Loading** - Code split routes for faster initial load
+2. **Error Boundaries** - Global error handling for better UX
+3. **Service Layer** - Abstract API calls into dedicated services
+4. **Form Management** - Integrate React Hook Form or Formik
+5. **State Management** - Consider Zustand or Redux for complex state
+6. **Testing** - Add comprehensive component and integration tests
+7. **Accessibility** - Enhanced ARIA support and keyboard navigation
+8. **i18n** - Internationalization support for multiple languages
diff --git a/docs/frontend/code-organization.md b/docs/frontend/code-organization.md
new file mode 100644
index 0000000..d956094
--- /dev/null
+++ b/docs/frontend/code-organization.md
@@ -0,0 +1,777 @@
+# Code Organization
+
+This guide explains the folder structure, naming conventions, and best practices for organizing code in the OctoCAT Supply frontend.
+
+## Table of Contents
+
+- [Directory Structure](#directory-structure)
+- [File Naming Conventions](#file-naming-conventions)
+- [Component Organization](#component-organization)
+- [State Management](#state-management)
+- [Utilities and Helpers](#utilities-and-helpers)
+- [Assets Management](#assets-management)
+- [Type Definitions](#type-definitions)
+- [Best Practices for New Features](#best-practices-for-new-features)
+
+---
+
+## Directory Structure
+
+### Overview
+
+```
+frontend/
+├── public/              # Static assets served directly
+│   ├── copilot.png      # Brand logos
+│   ├── hero-cat.png     # Hero images
+│   └── *.png            # Product images
+├── src/                 # Source code
+│   ├── api/             # API configuration
+│   │   └── config.ts    # Base URL and endpoint definitions
+│   ├── assets/          # Imported assets (images, fonts)
+│   ├── components/      # React components
+│   │   ├── admin/       # Admin-specific components
+│   │   ├── entity/      # Domain entity components
+│   │   │   └── product/ # Product-related components
+│   │   ├── About.tsx
+│   │   ├── Footer.tsx
+│   │   ├── Login.tsx
+│   │   ├── Navigation.tsx
+│   │   └── Welcome.tsx
+│   ├── context/         # React Context providers
+│   │   ├── AuthContext.tsx
+│   │   ├── ThemeContext.tsx
+│   │   ├── themeContextUtils.tsx
+│   │   └── useTheme.tsx
+│   ├── App.tsx          # Root component with routing
+│   ├── main.tsx         # Application entry point
+│   ├── index.css        # Global styles
+│   └── vite-env.d.ts    # TypeScript type declarations
+├── .gitignore
+├── Dockerfile
+├── eslint.config.js
+├── index.html           # HTML entry point
+├── package.json
+├── postcss.config.js
+├── tailwind.config.js   # Tailwind CSS configuration
+├── tsconfig.json        # TypeScript configuration
+├── tsconfig.app.json
+├── tsconfig.node.json
+└── vite.config.ts       # Vite configuration
+```
+
+### Key Directories Explained
+
+**`public/`**
+- Static assets served at root URL
+- Not processed by Vite
+- Use for: logos, favicons, product images
+- Access: `/filename.png` (no `/public` prefix)
+
+**`src/`**
+- All TypeScript/TSX source code
+- Processed and bundled by Vite
+
+**`src/api/`**
+- API client configuration
+- Endpoint definitions
+- Base URL detection logic
+
+**`src/assets/`**
+- Assets imported in code (currently unused, but available)
+- Use for: fonts, icons, images that need processing
+- Access: `import logo from './assets/logo.svg'`
+
+**`src/components/`**
+- React components
+- Organized by feature/entity
+- Includes layout and page components
+
+**`src/context/`**
+- React Context providers
+- Global state management
+- Theme and authentication
+
+---
+
+## File Naming Conventions
+
+### Components
+
+**Format:** `PascalCase.tsx`
+
+```
+Welcome.tsx          ✅ Correct
+Navigation.tsx       ✅ Correct
+ProductCard.tsx      ✅ Correct
+product-card.tsx     ❌ Incorrect
+productCard.tsx      ❌ Incorrect
+```
+
+### Utilities and Helpers
+
+**Format:** `camelCase.ts`
+
+```
+formatting.ts        ✅ Correct
+apiHelpers.ts        ✅ Correct
+dateUtils.ts         ✅ Correct
+Formatting.ts        ❌ Incorrect (use PascalCase only for components)
+```
+
+### Types
+
+**Format:** `PascalCase.ts` or `camelCase.types.ts`
+
+```
+types.ts             ✅ Correct (if exporting multiple types)
+Product.ts           ✅ Correct (if single type/interface)
+product.types.ts     ✅ Correct
+```
+
+### Tests
+
+**Format:** `ComponentName.test.tsx` or `utilName.test.ts`
+
+```
+Welcome.test.tsx     ✅ Correct
+formatting.test.ts   ✅ Correct
+Welcome.spec.tsx     ✅ Alternative
+```
+
+### Configuration Files
+
+**Format:** Lowercase with dots/dashes
+
+```
+vite.config.ts       ✅ Correct
+tailwind.config.js   ✅ Correct
+.eslintrc            ✅ Correct
+```
+
+---
+
+## Component Organization
+
+### Organizing by Feature/Entity
+
+Group related components together:
+
+```
+components/
+├── entity/
+│   ├── product/
+│   │   ├── Products.tsx         # List view
+│   │   ├── ProductCard.tsx      # Individual card
+│   │   ├── ProductForm.tsx      # Create/edit form
+│   │   └── ProductDetail.tsx    # Detail view
+│   ├── order/
+│   │   ├── Orders.tsx
+│   │   └── OrderForm.tsx
+│   └── supplier/
+│       ├── Suppliers.tsx
+│       └── SupplierForm.tsx
+├── admin/
+│   ├── AdminProducts.tsx
+│   ├── AdminOrders.tsx
+│   └── AdminDashboard.tsx
+├── About.tsx                     # Top-level pages
+├── Welcome.tsx
+└── Login.tsx
+```
+
+### Component Structure
+
+**Basic Component Template:**
+
+```typescript
+import { useState } from 'react';
+import { useTheme } from '../context/ThemeContext';
+
+// 1. Type definitions
+interface MyComponentProps {
+  title: string;
+  onAction: () => void;
+}
+
+// 2. Component definition
+export default function MyComponent({ title, onAction }: MyComponentProps) {
+  // 3. Hooks (context, state, effects)
+  const { darkMode } = useTheme();
+  const [count, setCount] = useState(0);
+
+  // 4. Event handlers
+  const handleClick = () => {
+    setCount(count + 1);
+    onAction();
+  };
+
+  // 5. Render logic
+  return (
+    <div className={darkMode ? 'bg-dark' : 'bg-white'}>
+      <h2>{title}</h2>
+      <button onClick={handleClick}>Count: {count}</button>
+    </div>
+  );
+}
+```
+
+### Component File Organization
+
+**Order within file:**
+
+1. Imports (React, third-party, local)
+2. Type/Interface definitions
+3. Constants
+4. Component definition
+5. Export default
+
+**Example:**
+
+```typescript
+// 1. Imports
+import { useState, useEffect } from 'react';
+import axios from 'axios';
+import { useQuery } from 'react-query';
+import { api } from '../../api/config';
+import { useTheme } from '../../context/ThemeContext';
+
+// 2. Types
+interface Product {
+  productId: number;
+  name: string;
+  price: number;
+}
+
+// 3. Constants
+const DEFAULT_SORT = 'name';
+
+// 4. Component
+export default function Products() {
+  // Component implementation
+}
+```
+
+---
+
+## State Management
+
+### Local State
+
+Use `useState` for component-specific state:
+
+```typescript
+const [isOpen, setIsOpen] = useState(false);
+const [formData, setFormData] = useState({ name: '', email: '' });
+```
+
+**When to use:**
+- UI state (modals, dropdowns, toggles)
+- Form inputs
+- Temporary data
+
+### Context State
+
+Use Context for state shared across multiple components:
+
+```typescript
+// AuthContext for authentication state
+const { isLoggedIn, isAdmin } = useAuth();
+
+// ThemeContext for theme preferences
+const { darkMode, toggleTheme } = useTheme();
+```
+
+**When to use:**
+- Authentication state
+- Theme preferences
+- User settings
+- Language/locale
+
+### Server State (React Query)
+
+Use React Query for server data:
+
+```typescript
+const { data, isLoading, error } = useQuery('products', fetchProducts);
+```
+
+**When to use:**
+- Fetching from API
+- Cached server data
+- Background synchronization
+
+### Creating New Context
+
+**Template:**
+
+```typescript
+// src/context/MyContext.tsx
+import { createContext, useContext, useState, ReactNode } from 'react';
+
+interface MyContextType {
+  value: string;
+  updateValue: (newValue: string) => void;
+}
+
+const MyContext = createContext<MyContextType | null>(null);
+
+export function MyProvider({ children }: { children: ReactNode }) {
+  const [value, setValue] = useState('');
+
+  const updateValue = (newValue: string) => {
+    setValue(newValue);
+  };
+
+  return (
+    <MyContext.Provider value={{ value, updateValue }}>
+      {children}
+    </MyContext.Provider>
+  );
+}
+
+export function useMyContext() {
+  const context = useContext(MyContext);
+  if (!context) {
+    throw new Error('useMyContext must be used within MyProvider');
+  }
+  return context;
+}
+```
+
+---
+
+## Utilities and Helpers
+
+### Creating Utility Functions
+
+Place in `src/utils/` (create directory if needed):
+
+```
+src/
+└── utils/
+    ├── formatting.ts       # Currency, date formatting
+    ├── validation.ts       # Form validation
+    ├── api.ts             # API helpers
+    └── storage.ts         # localStorage helpers
+```
+
+**Example: Formatting Utilities**
+
+```typescript
+// src/utils/formatting.ts
+
+export const formatCurrency = (amount: number): string => {
+  return `$${amount.toFixed(2)}`;
+};
+
+export const formatDate = (date: Date): string => {
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+};
+
+export const truncateText = (text: string, maxLength: number): string => {
+  if (text.length <= maxLength) return text;
+  return `${text.substring(0, maxLength)}...`;
+};
+```
+
+**Usage:**
+
+```typescript
+import { formatCurrency, formatDate } from '../utils/formatting';
+
+<div>
+  <p>{formatCurrency(product.price)}</p>
+  <p>{formatDate(order.createdAt)}</p>
+</div>
+```
+
+---
+
+## Assets Management
+
+### Public Assets
+
+Place in `public/` directory:
+
+```
+public/
+├── copilot.png          # Brand logo
+├── hero-cat.png         # Hero image
+├── product-1.png        # Product images
+├── product-2.png
+└── favicon.ico
+```
+
+**Access in code:**
+
+```typescript
+<img src="/copilot.png" alt="Logo" />
+<img src={`/${product.imgName}`} alt={product.name} />
+```
+
+### Imported Assets
+
+Place in `src/assets/` (if need processing):
+
+```
+src/
+└── assets/
+    ├── logo.svg
+    └── icon-cart.svg
+```
+
+**Access in code:**
+
+```typescript
+import logo from './assets/logo.svg';
+
+<img src={logo} alt="Logo" />
+```
+
+### When to Use Each
+
+**Use `public/`:**
+- Assets referenced by name in data (e.g., product images)
+- Favicons, manifests
+- Large images that don't need optimization
+
+**Use `src/assets/`:**
+- Icons imported in code
+- Assets needing optimization
+- SVGs used as React components
+
+---
+
+## Type Definitions
+
+### Component Props
+
+Define interfaces inline or in separate file:
+
+```typescript
+// Inline (for single component)
+interface ProductCardProps {
+  product: Product;
+  onEdit?: (id: number) => void;
+  darkMode: boolean;
+}
+
+export default function ProductCard({ product, onEdit, darkMode }: ProductCardProps) {
+  // Component
+}
+```
+
+### Shared Types
+
+Create `src/types/` directory for shared types:
+
+```typescript
+// src/types/product.ts
+export interface Product {
+  productId: number;
+  name: string;
+  description: string;
+  price: number;
+  imgName: string;
+  sku: string;
+  unit: string;
+  supplierId: number;
+  discount?: number;
+}
+
+// src/types/supplier.ts
+export interface Supplier {
+  supplierId: number;
+  name: string;
+  contactPerson: string;
+  email: string;
+  phone: string;
+}
+
+// src/types/index.ts
+export * from './product';
+export * from './supplier';
+```
+
+**Usage:**
+
+```typescript
+import { Product, Supplier } from '../types';
+```
+
+### API Response Types
+
+Match backend API responses:
+
+```typescript
+// src/types/api.ts
+export interface ApiResponse<T> {
+  data: T;
+  message?: string;
+  error?: string;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+```
+
+---
+
+## Best Practices for New Features
+
+### 1. Plan Component Structure
+
+Before coding, plan:
+- What components are needed?
+- How will they be organized?
+- What state is local vs. shared?
+
+### 2. Start with Types
+
+Define TypeScript interfaces first:
+
+```typescript
+// 1. Define data types
+interface Order {
+  orderId: number;
+  branchId: number;
+  orderDate: Date;
+  totalAmount: number;
+}
+
+// 2. Define component props
+interface OrderListProps {
+  orders: Order[];
+  onOrderClick: (id: number) => void;
+}
+
+// 3. Build component
+export default function OrderList({ orders, onOrderClick }: OrderListProps) {
+  // Component implementation
+}
+```
+
+### 3. Create Reusable Components
+
+Extract repeated UI into components:
+
+```typescript
+// Instead of repeating button styles:
+<button className="px-4 py-2 bg-primary text-white rounded">Action</button>
+
+// Create Button component:
+<Button variant="primary">Action</Button>
+```
+
+### 4. Organize by Feature
+
+Group related files:
+
+```
+components/
+└── entity/
+    └── order/
+        ├── Orders.tsx          # List view
+        ├── OrderCard.tsx       # Card component
+        ├── OrderForm.tsx       # Create/edit form
+        ├── OrderDetail.tsx     # Detail view
+        └── orderHelpers.ts     # Order-specific utilities
+```
+
+### 5. Follow Existing Patterns
+
+Study existing components for:
+- How theme context is used
+- How API calls are made
+- How errors are handled
+- How loading states are shown
+
+### 6. Add Documentation
+
+Document complex components:
+
+```typescript
+/**
+ * ProductCard displays a product with image, details, and quantity selector.
+ * 
+ * @param product - Product data to display
+ * @param onAddToCart - Callback when user adds to cart
+ * @param darkMode - Whether dark mode is enabled
+ * 
+ * @example
+ * <ProductCard
+ *   product={product}
+ *   onAddToCart={(id, qty) => console.log(id, qty)}
+ *   darkMode={true}
+ * />
+ */
+export default function ProductCard({ ... }: ProductCardProps) {
+  // Component
+}
+```
+
+### 7. Keep Components Small
+
+**Guidelines:**
+- Single responsibility
+- < 200 lines of code (ideal: < 150)
+- Extract large JSX blocks into sub-components
+- Extract complex logic into hooks or utilities
+
+### 8. Write Tests
+
+Add tests alongside components:
+
+```
+components/
+└── entity/
+    └── order/
+        ├── Orders.tsx
+        ├── Orders.test.tsx      # Tests
+        ├── OrderForm.tsx
+        └── OrderForm.test.tsx
+```
+
+---
+
+## Example: Adding a New Feature
+
+### Scenario: Add Supplier Management
+
+**1. Plan Structure:**
+
+```
+components/
+└── entity/
+    └── supplier/
+        ├── Suppliers.tsx        # List page
+        ├── SupplierCard.tsx     # Display card
+        ├── SupplierForm.tsx     # Create/edit form
+        └── SupplierDetail.tsx   # Detail view
+```
+
+**2. Define Types:**
+
+```typescript
+// src/types/supplier.ts
+export interface Supplier {
+  supplierId: number;
+  name: string;
+  description: string;
+  contactPerson: string;
+  email: string;
+  phone: string;
+}
+```
+
+**3. Create API Functions:**
+
+```typescript
+// src/api/suppliers.ts
+import axios from 'axios';
+import { api } from './config';
+import { Supplier } from '../types';
+
+export const supplierApi = {
+  getAll: () => axios.get<Supplier[]>(`${api.baseURL}${api.endpoints.suppliers}`),
+  getById: (id: number) => axios.get<Supplier>(`${api.baseURL}${api.endpoints.suppliers}/${id}`),
+  create: (data: Omit<Supplier, 'supplierId'>) => 
+    axios.post(`${api.baseURL}${api.endpoints.suppliers}`, data),
+  update: (id: number, data: Partial<Supplier>) => 
+    axios.put(`${api.baseURL}${api.endpoints.suppliers}/${id}`, data),
+  delete: (id: number) => 
+    axios.delete(`${api.baseURL}${api.endpoints.suppliers}/${id}`),
+};
+```
+
+**4. Build Components:**
+
+```typescript
+// src/components/entity/supplier/Suppliers.tsx
+import { useQuery } from 'react-query';
+import { supplierApi } from '../../../api/suppliers';
+import SupplierCard from './SupplierCard';
+
+export default function Suppliers() {
+  const { data: suppliers, isLoading, error } = useQuery(
+    'suppliers',
+    () => supplierApi.getAll().then(res => res.data)
+  );
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error loading suppliers</div>;
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+      {suppliers?.map(supplier => (
+        <SupplierCard key={supplier.supplierId} supplier={supplier} />
+      ))}
+    </div>
+  );
+}
+```
+
+**5. Add Route:**
+
+```typescript
+// src/App.tsx
+<Route path="/suppliers" element={<Suppliers />} />
+```
+
+**6. Add Navigation Link:**
+
+```typescript
+// src/components/Navigation.tsx
+<Link to="/suppliers">Suppliers</Link>
+```
+
+**7. Write Tests:**
+
+```typescript
+// src/components/entity/supplier/Suppliers.test.tsx
+import { render, screen } from '@testing-library/react';
+import Suppliers from './Suppliers';
+
+describe('Suppliers', () => {
+  it('renders supplier list', async () => {
+    render(<Suppliers />);
+    // Test implementation
+  });
+});
+```
+
+---
+
+## Code Quality Checklist
+
+Before submitting code:
+
+- [ ] TypeScript types defined
+- [ ] Component follows naming conventions
+- [ ] Theme context integrated (darkMode support)
+- [ ] Responsive design implemented
+- [ ] Error handling in place
+- [ ] Loading states handled
+- [ ] Accessibility attributes added
+- [ ] No console errors or warnings
+- [ ] Linter passes (`npm run lint`)
+- [ ] Tests written and passing
+- [ ] Documentation updated (if needed)
+
+---
+
+## Resources
+
+- [React Best Practices](https://react.dev/learn)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [Project README](../../README.md)
+- [Architecture Documentation](./architecture.md)
diff --git a/docs/frontend/components.md b/docs/frontend/components.md
new file mode 100644
index 0000000..98b489a
--- /dev/null
+++ b/docs/frontend/components.md
@@ -0,0 +1,614 @@
+# Component Documentation
+
+This guide documents the key components in the OctoCAT Supply frontend application.
+
+## Table of Contents
+
+- [Context Providers](#context-providers)
+  - [AuthContext](#authcontext)
+  - [ThemeContext](#themecontext)
+- [Layout Components](#layout-components)
+  - [Navigation](#navigation)
+  - [Footer](#footer)
+- [Page Components](#page-components)
+  - [Welcome](#welcome)
+  - [About](#about)
+  - [Login](#login)
+- [Entity Components](#entity-components)
+  - [Products](#products)
+  - [ProductForm](#productform)
+- [Admin Components](#admin-components)
+  - [AdminProducts](#adminproducts)
+
+---
+
+## Context Providers
+
+### AuthContext
+
+**Location:** `src/context/AuthContext.tsx`
+
+**Purpose:** Manages authentication state and provides authentication methods across the application.
+
+**Context Value:**
+
+```typescript
+interface AuthContextType {
+  isLoggedIn: boolean;    // Whether user is authenticated
+  isAdmin: boolean;       // Whether user has admin privileges
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+}
+```
+
+**Usage:**
+
+```typescript
+import { useAuth } from '../context/AuthContext';
+
+function MyComponent() {
+  const { isLoggedIn, isAdmin, login, logout } = useAuth();
+  
+  if (!isLoggedIn) {
+    return <div>Please log in</div>;
+  }
+  
+  return (
+    <div>
+      {isAdmin && <AdminPanel />}
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+**Implementation Notes:**
+- Currently uses mock authentication (client-side only)
+- Admin access granted to `@github.com` email addresses
+- State not persisted across page refreshes
+- Should be wrapped at the app root level
+
+**Provider Usage:**
+
+```typescript
+<AuthProvider>
+  <App />
+</AuthProvider>
+```
+
+---
+
+### ThemeContext
+
+**Location:** `src/context/ThemeContext.tsx`
+
+**Purpose:** Manages dark/light theme preference with localStorage persistence.
+
+**Context Value:**
+
+```typescript
+interface ThemeContextType {
+  darkMode: boolean;      // Current theme mode (true = dark, false = light)
+  toggleTheme: () => void; // Function to switch themes
+}
+```
+
+**Usage:**
+
+```typescript
+import { useTheme } from '../context/ThemeContext';
+
+function MyComponent() {
+  const { darkMode, toggleTheme } = useTheme();
+  
+  return (
+    <div className={darkMode ? 'bg-dark text-light' : 'bg-white text-gray-800'}>
+      <button onClick={toggleTheme}>
+        {darkMode ? '☀️ Light' : '🌙 Dark'}
+      </button>
+    </div>
+  );
+}
+```
+
+**Features:**
+- Persists preference in `localStorage` (key: `'theme'`)
+- Adds `'dark'` or `'light'` class to `document.documentElement`
+- Smooth transitions between themes (300ms)
+- Initializes from localStorage on mount
+
+**Provider Usage:**
+
+```typescript
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+```
+
+---
+
+## Layout Components
+
+### Navigation
+
+**Location:** `src/components/Navigation.tsx`
+
+**Purpose:** Top navigation bar with branding, links, theme toggle, and auth controls.
+
+**Props:** None (uses contexts)
+
+**Features:**
+- Responsive design (mobile hamburger menu)
+- Theme toggle button
+- Conditional rendering based on auth state
+- Admin menu for authenticated admins
+- Sticky positioning with backdrop blur
+
+**Key Elements:**
+- Logo and branding
+- Main navigation links (Home, Products, About)
+- Theme toggle
+- Login/Logout button
+- Admin dropdown (when authenticated as admin)
+
+**Usage:**
+
+```typescript
+<Navigation />
+```
+
+**Responsive Behavior:**
+- Desktop (≥768px): Full horizontal navigation
+- Mobile (<768px): Hamburger menu (if implemented)
+
+---
+
+### Footer
+
+**Location:** `src/components/Footer.tsx`
+
+**Purpose:** Site-wide footer with links and copyright information.
+
+**Props:** None (uses ThemeContext)
+
+**Features:**
+- Adapts to current theme
+- Contains company information
+- Social/contact links
+
+**Usage:**
+
+```typescript
+<Footer />
+```
+
+---
+
+## Page Components
+
+### Welcome
+
+**Location:** `src/components/Welcome.tsx`
+
+**Purpose:** Landing page showcasing the application.
+
+**Props:** None
+
+**Features:**
+- Hero section
+- Feature highlights
+- Call-to-action buttons
+- Theme-aware styling
+
+**Usage:**
+
+```typescript
+<Route path="/" element={<Welcome />} />
+```
+
+---
+
+### About
+
+**Location:** `src/components/About.tsx`
+
+**Purpose:** About page with company/project information.
+
+**Props:** None
+
+**Features:**
+- Company description
+- Mission statement
+- Team information (if applicable)
+- Theme-aware styling
+
+**Usage:**
+
+```typescript
+<Route path="/about" element={<About />} />
+```
+
+---
+
+### Login
+
+**Location:** `src/components/Login.tsx`
+
+**Purpose:** User authentication page.
+
+**Props:** None (uses AuthContext)
+
+**Features:**
+- Email and password inputs
+- Form validation
+- Calls `login()` from AuthContext
+- Redirects after successful login
+
+**State:**
+- `email: string`
+- `password: string`
+
+**Form Handling:**
+
+```typescript
+const handleSubmit = async (e: React.FormEvent) => {
+  e.preventDefault();
+  await login(email, password);
+  // Handle redirect
+};
+```
+
+**Usage:**
+
+```typescript
+<Route path="/login" element={<Login />} />
+```
+
+---
+
+## Entity Components
+
+### Products
+
+**Location:** `src/components/entity/product/Products.tsx`
+
+**Purpose:** Public product listing page with search and cart functionality.
+
+**Props:** None (fetches data internally)
+
+**Features:**
+- Product grid with responsive layout
+- Search/filter functionality
+- Quantity selector for each product
+- "Add to Cart" functionality (currently placeholder)
+- Product detail modal
+- Loading and error states
+- Theme-aware styling
+
+**State:**
+
+```typescript
+interface Product {
+  productId: number;
+  name: string;
+  description: string;
+  price: number;
+  imgName: string;
+  sku: string;
+  unit: string;
+  supplierId: number;
+  discount?: number;
+}
+
+const [quantities, setQuantities] = useState<Record<number, number>>({});
+const [searchTerm, setSearchTerm] = useState('');
+const [selectedProduct, setSelectedProduct] = useState<Product | null>(null);
+const [showModal, setShowModal] = useState(false);
+```
+
+**Data Fetching:**
+
+Uses React Query for data fetching:
+
+```typescript
+const { data: products, isLoading, error } = useQuery('products', fetchProducts);
+```
+
+**Key Functions:**
+
+- `handleQuantityChange(productId, change)` - Adjust product quantity
+- `handleAddToCart(productId)` - Add product to cart (placeholder)
+- `handleProductClick(product)` - Open product detail modal
+
+**Usage:**
+
+```typescript
+<Route path="/products" element={<Products />} />
+```
+
+**Responsive Grid:**
+- 1 column on mobile (sm: <640px)
+- 2 columns on tablet (sm: ≥640px)
+- 3 columns on medium screens (md: ≥768px)
+- 4 columns on large screens (lg: ≥1024px)
+
+---
+
+### ProductForm
+
+**Location:** `src/components/entity/product/ProductForm.tsx`
+
+**Purpose:** Modal form for creating/editing products.
+
+**Props:**
+
+```typescript
+interface ProductFormProps {
+  product?: Product;           // If provided, form is in edit mode
+  suppliers: Supplier[];       // List of suppliers for dropdown
+  onClose: () => void;         // Callback to close the form
+  onSave: () => void;          // Callback after successful save
+}
+```
+
+**Features:**
+- Create or update product
+- All product fields editable
+- Supplier selection dropdown
+- Discount percentage input
+- Form validation
+- Modal overlay
+- Theme-aware styling
+
+**Form Fields:**
+- Name (text, required)
+- Description (textarea, required)
+- Price (number, required, min: 0, step: 0.01)
+- SKU (text, required)
+- Unit (text, required)
+- Image Name (text, required)
+- Supplier (select, required)
+- Discount % (number, optional, 0-100)
+
+**Form Submission:**
+
+```typescript
+const handleSubmit = async (e: React.FormEvent) => {
+  e.preventDefault();
+  if (product) {
+    // Update existing product
+    await axios.put(`${api.baseURL}${api.endpoints.products}/${product.productId}`, formData);
+  } else {
+    // Create new product
+    await axios.post(`${api.baseURL}${api.endpoints.products}`, formData);
+  }
+  onSave();
+  onClose();
+};
+```
+
+**Usage:**
+
+```typescript
+<ProductForm
+  product={editingProduct}
+  suppliers={suppliers}
+  onClose={() => setShowForm(false)}
+  onSave={fetchProducts}
+/>
+```
+
+---
+
+## Admin Components
+
+### AdminProducts
+
+**Location:** `src/components/admin/AdminProducts.tsx`
+
+**Purpose:** Admin interface for managing products (CRUD operations).
+
+**Props:** None (uses AuthContext, checks `isAdmin`)
+
+**Features:**
+- **Protected Route** - Redirects if not admin
+- Product list in table format
+- Sortable columns (name, supplier, price, SKU, unit)
+- Create, update, delete operations
+- Integrates ProductForm for creation/editing
+- Fetches supplier details for display
+- Theme-aware styling
+
+**State:**
+
+```typescript
+const [products, setProducts] = useState<Product[]>([]);
+const [suppliers, setSuppliers] = useState<Supplier[]>([]);
+const [editingProduct, setEditingProduct] = useState<Product | undefined>();
+const [showForm, setShowForm] = useState(false);
+const [sortField, setSortField] = useState<SortField>('name');
+const [sortOrder, setSortOrder] = useState<SortOrder>('asc');
+```
+
+**Key Functions:**
+
+- `fetchProducts()` - Retrieves all products with supplier details
+- `fetchSuppliers()` - Retrieves all suppliers
+- `handleSort(field)` - Toggles column sorting
+- Delete handler - Inline with confirmation
+
+**Sorting:**
+
+Click column headers to sort:
+- First click: ascending
+- Second click: descending
+- Visual indicator: `↑` (asc), `↓` (desc), `↕` (unsorted)
+
+**Protection:**
+
+```typescript
+if (!isAdmin) {
+  return <Navigate to="/" replace />;
+}
+```
+
+**Usage:**
+
+```typescript
+<Route path="/admin/products" element={<AdminProducts />} />
+```
+
+**Table Columns:**
+- Name (sortable)
+- Supplier (sortable)
+- Price (sortable)
+- SKU (sortable)
+- Unit (sortable)
+- Discount (display only)
+- Description (truncated)
+- Actions (Edit/Delete buttons)
+
+**CRUD Operations:**
+
+**Create:**
+```typescript
+<button onClick={() => {
+  setEditingProduct(undefined);
+  setShowForm(true);
+}}>
+  Add New Product
+</button>
+```
+
+**Update:**
+```typescript
+<button onClick={() => {
+  setEditingProduct(product);
+  setShowForm(true);
+}}>
+  Edit
+</button>
+```
+
+**Delete:**
+```typescript
+<button onClick={async () => {
+  if (window.confirm('Are you sure?')) {
+    await axios.delete(`${api.baseURL}${api.endpoints.products}/${product.productId}`);
+    await fetchProducts();
+  }
+}}>
+  Delete
+</button>
+```
+
+---
+
+## Component Best Practices
+
+### General Guidelines
+
+1. **Use TypeScript Interfaces**: Define props and state types explicitly
+2. **Theme Awareness**: Use `useTheme()` for consistent theming
+3. **Accessibility**: Include ARIA labels where appropriate
+4. **Responsive Design**: Use Tailwind's responsive classes
+5. **Error Handling**: Display user-friendly error messages
+6. **Loading States**: Show loading indicators during async operations
+
+### Example Component Template
+
+```typescript
+import { useTheme } from '../context/ThemeContext';
+
+interface MyComponentProps {
+  title: string;
+  onAction: () => void;
+}
+
+export default function MyComponent({ title, onAction }: MyComponentProps) {
+  const { darkMode } = useTheme();
+  
+  return (
+    <div className={`p-4 ${darkMode ? 'bg-dark text-light' : 'bg-white text-gray-800'}`}>
+      <h2 className="text-2xl font-bold">{title}</h2>
+      <button 
+        onClick={onAction}
+        className="mt-4 px-4 py-2 bg-primary text-white rounded hover:bg-accent"
+      >
+        Action
+      </button>
+    </div>
+  );
+}
+```
+
+### Common Patterns
+
+**Loading State:**
+```typescript
+if (isLoading) {
+  return (
+    <div className="flex justify-center items-center h-64">
+      <div className="animate-spin rounded-full h-32 w-32 border-t-2 border-b-2 border-primary"></div>
+    </div>
+  );
+}
+```
+
+**Error State:**
+```typescript
+if (error) {
+  return (
+    <div className="text-red-500 text-center">
+      Failed to load data. Please try again.
+    </div>
+  );
+}
+```
+
+**Empty State:**
+```typescript
+if (!data || data.length === 0) {
+  return (
+    <div className="text-center py-20">
+      <p className="text-gray-500">No items found</p>
+    </div>
+  );
+}
+```
+
+---
+
+## Adding New Components
+
+When creating a new component:
+
+1. **Create the file** in the appropriate directory:
+   - Layout components → `src/components/`
+   - Entity components → `src/components/entity/[entity-name]/`
+   - Admin components → `src/components/admin/`
+
+2. **Define TypeScript interfaces** for props and local types
+
+3. **Use hooks for state and context**:
+   ```typescript
+   const { darkMode } = useTheme();
+   const [localState, setLocalState] = useState(initialValue);
+   ```
+
+4. **Follow naming conventions**:
+   - Component file: `PascalCase.tsx`
+   - Variables/functions: `camelCase`
+   - Constants: `UPPER_SNAKE_CASE`
+
+5. **Include accessibility attributes**:
+   - `aria-label` for buttons/inputs without visible labels
+   - `role` for semantic regions
+   - Proper heading hierarchy
+
+6. **Add to routing** (if it's a page component):
+   ```typescript
+   <Route path="/my-route" element={<MyComponent />} />
+   ```
+
+7. **Update documentation** - Add entry to this file!
diff --git a/docs/frontend/setup.md b/docs/frontend/setup.md
new file mode 100644
index 0000000..a928d30
--- /dev/null
+++ b/docs/frontend/setup.md
@@ -0,0 +1,493 @@
+# Setup and Development
+
+This guide covers everything you need to get the frontend application up and running.
+
+## Prerequisites
+
+### Required Software
+
+- **Node.js**: Version 18.x or higher
+  ```bash
+  node --version  # Should be >= 18.0.0
+  ```
+- **npm**: Version 9.x or higher (comes with Node.js)
+  ```bash
+  npm --version
+  ```
+
+### Optional Tools
+
+- **Git**: For version control
+- **VS Code**: Recommended editor with these extensions:
+  - ESLint
+  - Prettier
+  - Tailwind CSS IntelliSense
+  - TypeScript Vue Plugin (Volar)
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/webmaxru/copilot_agent_mode.git
+cd copilot_agent_mode
+```
+
+### Install Dependencies
+
+From the project root:
+
+```bash
+# Install all workspace dependencies (recommended)
+npm install
+
+# Or install only frontend dependencies
+cd frontend
+npm install
+```
+
+This installs:
+- React and React DOM
+- React Router
+- React Query
+- Axios
+- Tailwind CSS
+- Vite
+- TypeScript
+- ESLint
+- Testing libraries (Vitest, React Testing Library)
+
+## Environment Configuration
+
+### API URL Configuration
+
+The frontend automatically detects the API URL based on the environment:
+
+1. **Runtime Configuration** (Docker/Production):
+   - Set `window.RUNTIME_CONFIG.API_URL` in `public/runtime-config.js`
+
+2. **GitHub Codespaces**:
+   - Automatically detected and configured
+   - Maps to port 3000 on your codespace
+
+3. **Local Development**:
+   - Defaults to `http://localhost:3000`
+   - Matches protocol of frontend (http/https)
+
+### Custom API URL
+
+To override the API URL for local development:
+
+1. Create `public/runtime-config.js`:
+   ```javascript
+   window.RUNTIME_CONFIG = {
+     API_URL: 'http://your-custom-api:3000'
+   };
+   ```
+
+2. Include in `index.html`:
+   ```html
+   <script src="/runtime-config.js"></script>
+   ```
+
+### Environment Variables
+
+Vite environment variables can be defined in `.env` files:
+
+```bash
+# .env.local (not committed to git)
+VITE_API_URL=http://localhost:3000
+```
+
+Access in code:
+```typescript
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+## Development Server
+
+### Start the Development Server
+
+```bash
+cd frontend
+npm run dev
+```
+
+The server starts on `http://localhost:5137` by default.
+
+**Output:**
+```
+  VITE v6.2.0  ready in 234 ms
+
+  ➜  Local:   http://localhost:5137/
+  ➜  Network: http://192.168.1.100:5137/
+  ➜  press h + enter to show help
+```
+
+### Development Server Features
+
+- **Hot Module Replacement (HMR)**: Changes reflected instantly
+- **Fast Refresh**: Preserves component state during edits
+- **Source Maps**: Original TypeScript code in browser devtools
+- **Error Overlay**: Build errors displayed in browser
+
+### Running with Backend
+
+To run the full stack locally:
+
+```bash
+# Terminal 1: Start the API
+cd api
+npm run dev
+
+# Terminal 2: Start the frontend
+cd frontend
+npm run dev
+```
+
+Or use the convenience script from project root:
+
+```bash
+npm run dev  # Starts both frontend and backend
+```
+
+## Build Process
+
+### Development Build
+
+For development with optimizations disabled:
+
+```bash
+npm run dev
+```
+
+### Production Build
+
+```bash
+npm run build
+```
+
+This process:
+1. **Type checks** with TypeScript compiler (`tsc -b`)
+2. **Bundles** code with Vite
+3. **Minifies** JavaScript and CSS
+4. **Optimizes** assets
+5. **Outputs** to `dist/` directory
+
+**Build Output:**
+```
+dist/
+├── assets/
+│   ├── index-[hash].js
+│   ├── index-[hash].css
+│   └── [images]
+├── index.html
+└── vite.svg
+```
+
+### Preview Production Build
+
+Test the production build locally:
+
+```bash
+npm run preview
+```
+
+Serves the `dist/` folder on `http://localhost:4173`
+
+## Linting
+
+### Run ESLint
+
+```bash
+npm run lint
+```
+
+Checks TypeScript and TSX files for:
+- Code quality issues
+- TypeScript errors
+- React best practices
+- Accessibility issues
+
+### ESLint Configuration
+
+Located in `eslint.config.js`:
+- TypeScript ESLint rules
+- React Hooks rules
+- React Refresh rules
+
+### Auto-fix Issues
+
+```bash
+npm run lint -- --fix
+```
+
+## Code Formatting
+
+### Prettier (Recommended)
+
+While not included by default, Prettier is recommended:
+
+```bash
+# Install Prettier
+npm install -D prettier
+
+# Create .prettierrc
+echo '{ "semi": true, "singleQuote": true }' > .prettierrc
+
+# Format code
+npx prettier --write "src/**/*.{ts,tsx,css}"
+```
+
+## Testing
+
+### Test Configuration
+
+Testing setup uses:
+- **Vitest**: Fast unit test runner (Vite-native)
+- **React Testing Library**: Component testing utilities
+- **jsdom**: DOM implementation for Node.js
+- **@testing-library/jest-dom**: Additional matchers
+
+### Run Tests
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Test File Location
+
+Place tests next to the components they test:
+
+```
+components/
+├── ProductCard.tsx
+└── ProductCard.test.tsx
+```
+
+Or in a `__tests__` directory:
+
+```
+components/
+├── ProductCard.tsx
+└── __tests__/
+    └── ProductCard.test.tsx
+```
+
+### Example Test
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import ProductCard from './ProductCard';
+
+test('renders product name', () => {
+  const product = { id: 1, name: 'Test Product', price: 10 };
+  render(<ProductCard product={product} />);
+  expect(screen.getByText('Test Product')).toBeInTheDocument();
+});
+```
+
+## Docker Development
+
+### Build Docker Image
+
+```bash
+cd frontend
+docker build -t octocat-frontend .
+```
+
+### Run in Container
+
+```bash
+docker run -p 5137:80 octocat-frontend
+```
+
+Access at `http://localhost:5137`
+
+### Docker Compose
+
+From project root:
+
+```bash
+docker-compose up
+```
+
+Starts both frontend and backend services.
+
+## IDE Setup
+
+### VS Code Configuration
+
+Recommended `.vscode/settings.json`:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "tailwindCSS.experimental.classRegex": [
+    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
+  ]
+}
+```
+
+### Recommended Extensions
+
+- **ESLint** (dbaeumer.vscode-eslint)
+- **Prettier** (esbenp.prettier-vscode)
+- **Tailwind CSS IntelliSense** (bradlc.vscode-tailwindcss)
+- **TypeScript Vue Plugin** (Vue.volar)
+- **Path Intellisense** (christian-kohler.path-intellisense)
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 5137 is in use:
+
+```bash
+# Change port in vite.config.ts
+server: {
+  port: 3001,  // Use different port
+}
+```
+
+### API Connection Issues
+
+1. Verify backend is running on port 3000
+2. Check browser console for CORS errors
+3. Verify API URL in `src/api/config.ts`
+
+```typescript
+console.log('API Base URL:', API_BASE_URL);
+```
+
+### Module Not Found Errors
+
+Clear node_modules and reinstall:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### TypeScript Errors
+
+Restart TypeScript server in VS Code:
+- Press `Cmd/Ctrl + Shift + P`
+- Type "TypeScript: Restart TS Server"
+- Press Enter
+
+### Vite Cache Issues
+
+Clear Vite cache:
+
+```bash
+rm -rf node_modules/.vite
+npm run dev
+```
+
+### Build Failures
+
+Check TypeScript errors:
+
+```bash
+npx tsc --noEmit
+```
+
+### Hot Reload Not Working
+
+1. Check file watchers limit (Linux):
+   ```bash
+   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+   sudo sysctl -p
+   ```
+
+2. Ensure files are in `src/` directory
+3. Restart dev server
+
+## Development Workflow
+
+### Typical Development Flow
+
+1. **Start dev server**: `npm run dev`
+2. **Make changes**: Edit files in `src/`
+3. **View changes**: Browser updates automatically
+4. **Check console**: Look for errors/warnings
+5. **Run linter**: `npm run lint` before committing
+6. **Test changes**: `npm run test`
+7. **Commit code**: Git commit with meaningful message
+
+### Before Committing
+
+```bash
+# Run linter
+npm run lint
+
+# Fix auto-fixable issues
+npm run lint -- --fix
+
+# Run tests
+npm run test
+
+# Build to verify production works
+npm run build
+```
+
+### Branch Strategy
+
+- `main` - Production-ready code
+- `develop` - Integration branch
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+
+## Performance Tips
+
+### Development Performance
+
+- Use Vite's fast HMR instead of full page reload
+- Keep dev tools open for better debugging
+- Use React DevTools for component inspection
+
+### Build Performance
+
+- Vite automatically code-splits routes
+- Images are optimized during build
+- CSS is minified and tree-shaken
+
+## Deployment
+
+See [deployment.md](../../deployment.md) for production deployment instructions.
+
+### Quick Deploy to Vercel
+
+```bash
+npm install -g vercel
+cd frontend
+vercel
+```
+
+### Quick Deploy to Netlify
+
+```bash
+npm install -g netlify-cli
+cd frontend
+netlify deploy --prod --dir=dist
+```
+
+## Next Steps
+
+- Review [Architecture](./architecture.md) to understand app structure
+- Check [Component Documentation](./components.md) for component details
+- Read [Styling Guidelines](./styling.md) for Tailwind conventions
+- Learn about [API Integration](./api-integration.md) patterns
diff --git a/docs/frontend/styling.md b/docs/frontend/styling.md
new file mode 100644
index 0000000..326166d
--- /dev/null
+++ b/docs/frontend/styling.md
@@ -0,0 +1,719 @@
+# Styling Guidelines
+
+This guide covers the styling conventions, Tailwind CSS usage, theme system, and responsive design approach in the OctoCAT Supply frontend.
+
+## Table of Contents
+
+- [Tailwind CSS Overview](#tailwind-css-overview)
+- [Theme System](#theme-system)
+- [Color Palette](#color-palette)
+- [Typography](#typography)
+- [Spacing and Layout](#spacing-and-layout)
+- [Responsive Design](#responsive-design)
+- [Component Styling Patterns](#component-styling-patterns)
+- [Transitions and Animations](#transitions-and-animations)
+- [Best Practices](#best-practices)
+
+---
+
+## Tailwind CSS Overview
+
+The application uses Tailwind CSS, a utility-first CSS framework. Styles are applied using utility classes directly in JSX/TSX.
+
+### Configuration
+
+**Location:** `tailwind.config.js`
+
+**Content Sources:**
+```javascript
+content: [
+  "./index.html",
+  "./src/**/*.{js,ts,jsx,tsx}",
+]
+```
+
+### Key Benefits
+
+- **No CSS file bloat** - Only used utilities are included in production
+- **Consistent design** - Predefined scale for spacing, colors, etc.
+- **Responsive by default** - Easy breakpoint-based styling
+- **Dark mode support** - Built-in with class strategy
+
+---
+
+## Theme System
+
+### Dark Mode Implementation
+
+The app uses Tailwind's class-based dark mode strategy:
+
+**Configuration:**
+```javascript
+// tailwind.config.js
+darkMode: 'class'
+```
+
+**How It Works:**
+
+1. ThemeContext manages `darkMode` state (boolean)
+2. Theme preference saved to `localStorage`
+3. `'dark'` or `'light'` class applied to `<html>` element
+4. Components use conditional classes based on theme
+
+**Example:**
+
+```typescript
+const { darkMode } = useTheme();
+
+<div className={darkMode ? 'bg-dark text-light' : 'bg-white text-gray-800'}>
+  Content
+</div>
+```
+
+**Alternative Syntax:**
+
+Use Tailwind's `dark:` variant for inline conditional styling:
+
+```typescript
+<div className="bg-white dark:bg-dark text-gray-800 dark:text-light">
+  Content
+</div>
+```
+
+### When to Use Each Approach
+
+**Conditional Classes** (Recommended for this project):
+```typescript
+className={darkMode ? 'bg-dark' : 'bg-white'}
+```
+- More explicit control
+- Easier to read complex conditions
+- Consistent with existing codebase
+
+**Dark Variant** (Alternative):
+```typescript
+className="bg-white dark:bg-dark"
+```
+- More concise
+- Leverages Tailwind's built-in dark mode
+- Good for simple color swaps
+
+---
+
+## Color Palette
+
+### Custom Colors
+
+**Location:** `tailwind.config.js` → `theme.extend.colors`
+
+```javascript
+colors: {
+  'primary': '#76B852',     // Green - Primary brand color
+  'dark': '#0A0A0A',        // Very dark gray - Dark mode background
+  'light': '#F5F5F5',       // Off-white - Light mode background/text
+  'accent': '#8BC34A',      // Light green - Accent/hover states
+  'gray': {                 // Extended gray scale
+    100: '#f5f5f5',
+    200: '#e5e5e5',
+    300: '#d4d4d4',
+    400: '#a3a3a3',
+    500: '#737373',
+    600: '#525252',
+    700: '#404040',
+    800: '#262626',
+    900: '#171717',
+  },
+}
+```
+
+### Color Usage Guidelines
+
+**Primary (`primary`):**
+- Buttons, CTAs
+- Links hover states
+- Brand elements
+- Active navigation items
+
+**Accent (`accent`):**
+- Hover states for primary buttons
+- Secondary CTAs
+- Highlights
+
+**Dark (`dark`):**
+- Dark mode backgrounds
+- Dark mode containers
+
+**Light (`light`):**
+- Dark mode text
+- Light mode backgrounds (as alternative to white)
+
+**Gray Scale:**
+- Borders: `gray-200` (light), `gray-700` (dark)
+- Text: `gray-600` to `gray-800` (light mode), `gray-300` to `gray-400` (dark mode)
+- Backgrounds: `gray-100` (light mode), `gray-800` (dark mode)
+
+### Color Accessibility
+
+- Ensure sufficient contrast ratios (WCAG AA: 4.5:1 for text)
+- Primary green on white: ✅ Passes
+- Light text on dark: ✅ Passes
+- Test combinations with tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+
+---
+
+## Typography
+
+### Font Family
+
+Uses system font stack (default Tailwind):
+- San Francisco (macOS)
+- Segoe UI (Windows)
+- Roboto (Android)
+- Fallback to sans-serif
+
+### Font Sizes
+
+Use Tailwind's text size utilities:
+
+```typescript
+<h1 className="text-3xl">       {/* 30px */}
+<h2 className="text-2xl">       {/* 24px */}
+<h3 className="text-xl">        {/* 20px */}
+<p className="text-base">       {/* 16px - default */}
+<small className="text-sm">     {/* 14px */}
+<span className="text-xs">      {/* 12px */}
+```
+
+### Font Weights
+
+```typescript
+<span className="font-normal">    {/* 400 */}
+<span className="font-medium">    {/* 500 */}
+<span className="font-semibold">  {/* 600 */}
+<span className="font-bold">      {/* 700 */}
+```
+
+### Typography Patterns
+
+**Page Headings:**
+```typescript
+<h1 className={`text-3xl font-bold ${darkMode ? 'text-light' : 'text-gray-800'}`}>
+  Page Title
+</h1>
+```
+
+**Section Headings:**
+```typescript
+<h2 className={`text-2xl font-semibold ${darkMode ? 'text-light' : 'text-gray-800'}`}>
+  Section Title
+</h2>
+```
+
+**Body Text:**
+```typescript
+<p className={`text-base ${darkMode ? 'text-gray-300' : 'text-gray-600'}`}>
+  Body content goes here.
+</p>
+```
+
+**Labels:**
+```typescript
+<label className={`block ${darkMode ? 'text-light' : 'text-gray-700'} mb-1`}>
+  Field Label
+</label>
+```
+
+---
+
+## Spacing and Layout
+
+### Spacing Scale
+
+Tailwind uses a consistent spacing scale (0.25rem = 4px increments):
+
+```typescript
+p-1   // padding: 0.25rem (4px)
+p-2   // padding: 0.5rem (8px)
+p-4   // padding: 1rem (16px)
+p-6   // padding: 1.5rem (24px)
+p-8   // padding: 2rem (32px)
+p-12  // padding: 3rem (48px)
+```
+
+### Common Layout Patterns
+
+**Page Container:**
+```typescript
+<div className="max-w-7xl mx-auto px-4">
+  {/* Content */}
+</div>
+```
+
+**Card/Container:**
+```typescript
+<div className={`${darkMode ? 'bg-gray-800' : 'bg-white'} rounded-lg shadow-lg p-6`}>
+  {/* Card content */}
+</div>
+```
+
+**Full Height Page:**
+```typescript
+<div className="min-h-screen pt-20 pb-16">
+  {/* Account for fixed nav (pt-20) and footer */}
+</div>
+```
+
+**Flex Container:**
+```typescript
+<div className="flex items-center justify-between">
+  <div>Left content</div>
+  <div>Right content</div>
+</div>
+```
+
+**Grid Layout:**
+```typescript
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
+  {/* Grid items */}
+</div>
+```
+
+---
+
+## Responsive Design
+
+### Breakpoints
+
+Tailwind default breakpoints used in this project:
+
+| Prefix | Min Width | Description |
+|--------|-----------|-------------|
+| `sm:` | 640px | Small devices (landscape phones) |
+| `md:` | 768px | Medium devices (tablets) |
+| `lg:` | 1024px | Large devices (laptops) |
+| `xl:` | 1280px | Extra large devices (desktops) |
+| `2xl:` | 1536px | 2X large devices (large desktops) |
+
+### Mobile-First Approach
+
+Base styles apply to mobile, then override for larger screens:
+
+```typescript
+<div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
+  {/* 1 col on mobile, 2 on sm, 3 on md, 4 on lg+ */}
+</div>
+```
+
+### Responsive Patterns
+
+**Show/Hide Elements:**
+```typescript
+<div className="hidden md:block">
+  Desktop only
+</div>
+
+<div className="block md:hidden">
+  Mobile only
+</div>
+```
+
+**Responsive Text Size:**
+```typescript
+<h1 className="text-2xl md:text-3xl lg:text-4xl">
+  Responsive Heading
+</h1>
+```
+
+**Responsive Spacing:**
+```typescript
+<div className="p-4 md:p-6 lg:p-8">
+  Content with responsive padding
+</div>
+```
+
+**Responsive Flex Direction:**
+```typescript
+<div className="flex flex-col md:flex-row">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+### Product Grid Example
+
+```typescript
+<div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
+  {products.map(product => (
+    <ProductCard key={product.id} product={product} />
+  ))}
+</div>
+```
+
+Results in:
+- Mobile: 1 column
+- Small (≥640px): 2 columns
+- Medium (≥768px): 3 columns
+- Large (≥1024px): 4 columns
+
+---
+
+## Component Styling Patterns
+
+### Button Styles
+
+**Primary Button:**
+```typescript
+<button className="px-4 py-2 bg-primary text-white rounded hover:bg-accent transition-colors duration-300">
+  Primary Action
+</button>
+```
+
+**Secondary Button:**
+```typescript
+<button className={`px-4 py-2 ${darkMode ? 'bg-gray-600' : 'bg-gray-300'} ${darkMode ? 'text-white' : 'text-gray-800'} rounded hover:${darkMode ? 'bg-gray-500' : 'bg-gray-400'} transition-colors duration-300`}>
+  Secondary Action
+</button>
+```
+
+**Danger Button:**
+```typescript
+<button className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700 transition-colors">
+  Delete
+</button>
+```
+
+**Disabled Button:**
+```typescript
+<button 
+  className={`px-4 py-2 rounded ${
+    disabled 
+      ? `${darkMode ? 'bg-gray-700 text-gray-400' : 'bg-gray-200 text-gray-500'} cursor-not-allowed`
+      : 'bg-primary hover:bg-accent text-white'
+  }`}
+  disabled={disabled}
+>
+  Action
+</button>
+```
+
+### Input Styles
+
+**Text Input:**
+```typescript
+<input
+  type="text"
+  className={`w-full px-4 py-2 ${darkMode ? 'bg-gray-700 text-light border-gray-600' : 'bg-white text-gray-800 border-gray-300'} rounded-lg border focus:border-primary focus:ring-1 focus:ring-primary focus:outline-none transition-colors duration-300`}
+  placeholder="Enter text..."
+/>
+```
+
+**Textarea:**
+```typescript
+<textarea
+  className={`w-full px-3 py-2 ${darkMode ? 'bg-gray-700 text-light' : 'bg-gray-100 text-gray-800'} rounded transition-colors duration-300`}
+  rows={4}
+/>
+```
+
+**Select:**
+```typescript
+<select
+  className={`w-full px-3 py-2 ${darkMode ? 'bg-gray-700 text-light' : 'bg-gray-100 text-gray-800'} rounded transition-colors duration-300`}
+>
+  <option value="">Select...</option>
+</select>
+```
+
+### Card Styles
+
+**Basic Card:**
+```typescript
+<div className={`${darkMode ? 'bg-gray-800' : 'bg-white'} rounded-lg shadow-lg p-6`}>
+  <h3 className={`text-xl font-semibold ${darkMode ? 'text-light' : 'text-gray-800'} mb-4`}>
+    Card Title
+  </h3>
+  <p className={`${darkMode ? 'text-gray-300' : 'text-gray-600'}`}>
+    Card content
+  </p>
+</div>
+```
+
+**Hover Card:**
+```typescript
+<div className={`${darkMode ? 'bg-gray-800' : 'bg-white'} rounded-lg shadow-lg transform transition-all duration-300 hover:scale-105 hover:shadow-[0_0_25px_rgba(118,184,82,0.3)]`}>
+  {/* Card content */}
+</div>
+```
+
+### Modal Styles
+
+```typescript
+{/* Overlay */}
+<div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center p-4 z-50">
+  {/* Modal */}
+  <div className={`${darkMode ? 'bg-gray-800' : 'bg-white'} rounded-lg p-6 max-w-2xl w-full max-h-[90vh] overflow-y-auto shadow-xl`}>
+    {/* Modal content */}
+  </div>
+</div>
+```
+
+### Table Styles
+
+```typescript
+<table className={`min-w-full ${darkMode ? 'bg-dark' : 'bg-white'} rounded-lg overflow-hidden`}>
+  <thead className={`${darkMode ? 'bg-gray-800' : 'bg-gray-200'}`}>
+    <tr>
+      <th className={`px-6 py-3 text-left text-xs font-medium ${darkMode ? 'text-light' : 'text-gray-700'} uppercase tracking-wider`}>
+        Column
+      </th>
+    </tr>
+  </thead>
+  <tbody className={`divide-y ${darkMode ? 'divide-gray-700' : 'divide-gray-200'}`}>
+    <tr className={`hover:${darkMode ? 'bg-gray-800' : 'bg-gray-100'}`}>
+      <td className={`px-6 py-4 ${darkMode ? 'text-light' : 'text-gray-800'}`}>
+        Data
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+---
+
+## Transitions and Animations
+
+### Transition Duration
+
+Standard transition: **300ms**
+
+```typescript
+className="transition-colors duration-300"
+```
+
+### Common Transitions
+
+**Color Transitions:**
+```typescript
+className="transition-colors duration-300"
+```
+
+**All Properties:**
+```typescript
+className="transition-all duration-300"
+```
+
+**Transform + Shadow:**
+```typescript
+className="transform transition-all duration-300 hover:scale-105"
+```
+
+### Loading Spinner
+
+```typescript
+<div className="animate-spin rounded-full h-32 w-32 border-t-2 border-b-2 border-primary"></div>
+```
+
+### Hover Effects
+
+**Scale:**
+```typescript
+className="transform hover:scale-105 transition-transform duration-300"
+```
+
+**Glow:**
+```typescript
+className="hover:shadow-[0_0_25px_rgba(118,184,82,0.3)] transition-shadow duration-300"
+```
+
+**Color Change:**
+```typescript
+className="text-gray-700 hover:text-primary transition-colors duration-300"
+```
+
+---
+
+## Best Practices
+
+### 1. Consistency
+
+- Use the defined color palette consistently
+- Stick to standard spacing scale (4, 8, 12, 16, 24, 32, 48px)
+- Maintain consistent border radius (usually `rounded` or `rounded-lg`)
+- Use consistent shadow levels
+
+### 2. Theme Awareness
+
+Always make components theme-aware:
+
+```typescript
+const { darkMode } = useTheme();
+
+<div className={darkMode ? 'bg-dark text-light' : 'bg-white text-gray-800'}>
+```
+
+### 3. Transitions
+
+Add smooth transitions for better UX:
+
+```typescript
+className="transition-colors duration-300"
+```
+
+### 4. Responsive Design
+
+Test at common breakpoints:
+- Mobile: 375px, 414px
+- Tablet: 768px, 1024px
+- Desktop: 1280px, 1920px
+
+### 5. Accessibility
+
+- Maintain color contrast ratios
+- Don't rely solely on color to convey information
+- Use semantic HTML with Tailwind classes
+- Test keyboard navigation
+
+### 6. Performance
+
+- Tailwind purges unused CSS in production
+- Avoid inline styles; use Tailwind utilities
+- Use `@apply` directive sparingly (prefer utilities in JSX)
+
+### 7. Avoid Magic Numbers
+
+Use Tailwind's scale, not arbitrary values:
+
+❌ Bad:
+```typescript
+className="p-[23px] text-[17px]"
+```
+
+✅ Good:
+```typescript
+className="p-6 text-lg"
+```
+
+### 8. Group Related Classes
+
+Order classes logically:
+
+```typescript
+className="
+  flex items-center justify-between   // Layout
+  px-4 py-2 mb-4                      // Spacing
+  bg-primary text-white               // Colors
+  rounded-lg shadow-md                // Appearance
+  hover:bg-accent                     // Interactions
+  transition-colors duration-300      // Animations
+"
+```
+
+### 9. Component Class Reusability
+
+For frequently repeated class combinations, consider extracting:
+
+```typescript
+const cardClasses = `
+  ${darkMode ? 'bg-gray-800' : 'bg-white'}
+  rounded-lg shadow-lg p-6
+  transition-colors duration-300
+`;
+
+<div className={cardClasses}>
+  {/* Content */}
+</div>
+```
+
+### 10. Custom Tailwind Extensions
+
+Only add to `tailwind.config.js` when truly needed:
+- New colors that are project-wide
+- Custom spacing values (e.g., `width: 7/8` for specific layout needs)
+- Custom breakpoints (avoid; use defaults)
+
+---
+
+## Common Pitfalls
+
+### ❌ Hardcoded Colors
+
+Don't use arbitrary color values:
+```typescript
+className="bg-[#76B852]"  // Bad
+```
+
+Use named colors:
+```typescript
+className="bg-primary"     // Good
+```
+
+### ❌ Forgetting Dark Mode
+
+```typescript
+<div className="bg-white text-gray-800">  // Missing dark mode
+```
+
+Always consider theme:
+```typescript
+<div className={darkMode ? 'bg-dark text-light' : 'bg-white text-gray-800'}>
+```
+
+### ❌ Inconsistent Spacing
+
+```typescript
+<div className="mt-5 mb-7 ml-3">  // Inconsistent
+```
+
+Use standard scale:
+```typescript
+<div className="m-4">              // Consistent
+```
+
+### ❌ Responsive Class Order
+
+```typescript
+className="lg:flex-row md:flex-col flex-col-reverse"  // Wrong order
+```
+
+Correct order (mobile-first):
+```typescript
+className="flex-col-reverse md:flex-col lg:flex-row"
+```
+
+---
+
+## Resources
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Tailwind Color Palette](https://tailwindcss.com/docs/customizing-colors)
+- [Tailwind Play (Interactive)](https://play.tailwindcss.com/)
+- [Tailwind UI Components](https://tailwindui.com/)
+
+---
+
+## Quick Reference
+
+### Most Common Classes
+
+```typescript
+// Layout
+flex flex-col items-center justify-between
+grid grid-cols-4 gap-6
+
+// Spacing
+p-4 px-6 py-2 m-4 space-y-4
+
+// Typography
+text-xl font-bold text-gray-800 dark:text-light
+
+// Colors
+bg-primary text-white border-gray-300
+
+// Effects
+rounded-lg shadow-lg hover:shadow-xl
+transition-colors duration-300
+
+// Responsive
+hidden md:block
+grid-cols-1 md:grid-cols-2 lg:grid-cols-4
+```
diff --git a/docs/frontend/testing.md b/docs/frontend/testing.md
new file mode 100644
index 0000000..154b819
--- /dev/null
+++ b/docs/frontend/testing.md
@@ -0,0 +1,719 @@
+# Testing
+
+This guide covers the testing strategy, tools, and patterns for the OctoCAT Supply frontend application.
+
+## Table of Contents
+
+- [Testing Stack](#testing-stack)
+- [Test Structure](#test-structure)
+- [Running Tests](#running-tests)
+- [Unit Testing](#unit-testing)
+- [Component Testing](#component-testing)
+- [Integration Testing](#integration-testing)
+- [Testing Best Practices](#testing-best-practices)
+- [Common Testing Patterns](#common-testing-patterns)
+
+---
+
+## Testing Stack
+
+### Tools and Libraries
+
+The frontend uses the following testing tools:
+
+- **Vitest** - Fast unit test runner (Vite-native, Jest-compatible API)
+- **React Testing Library** - Component testing utilities
+- **jsdom** - DOM implementation for Node.js environment
+- **@testing-library/jest-dom** - Custom matchers for DOM assertions
+- **@testing-library/user-event** - User interaction simulation
+
+### Installation
+
+Already included in `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "jsdom": "^26.0.0",
+    "vitest": "^3.1.1"
+  }
+}
+```
+
+### Configuration
+
+**Vitest Configuration:**
+
+Would typically be in `vite.config.ts` or `vitest.config.ts`:
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/test/setup.ts',
+  },
+});
+```
+
+**Setup File (`src/test/setup.ts`):**
+
+```typescript
+import '@testing-library/jest-dom';
+```
+
+---
+
+## Test Structure
+
+### File Organization
+
+Place test files next to the components they test:
+
+```
+src/
+├── components/
+│   ├── ProductCard.tsx
+│   └── ProductCard.test.tsx
+├── context/
+│   ├── AuthContext.tsx
+│   └── AuthContext.test.tsx
+└── utils/
+    ├── formatting.ts
+    └── formatting.test.ts
+```
+
+**Alternative:** Use `__tests__` directory:
+
+```
+src/
+├── components/
+│   ├── ProductCard.tsx
+│   └── __tests__/
+│       └── ProductCard.test.tsx
+```
+
+### Test File Naming
+
+- `ComponentName.test.tsx` - Component tests
+- `ComponentName.spec.tsx` - Alternative (spec)
+- `utils.test.ts` - Utility function tests
+
+---
+
+## Running Tests
+
+### Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode (re-run on file changes)
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run specific test file
+npm test -- ProductCard.test.tsx
+
+# Run tests matching pattern
+npm test -- --grep "ProductCard"
+```
+
+### Watch Mode
+
+In watch mode, Vitest provides an interactive menu:
+
+- Press `a` to run all tests
+- Press `f` to run only failed tests
+- Press `p` to filter by filename pattern
+- Press `t` to filter by test name pattern
+- Press `q` to quit
+
+---
+
+## Unit Testing
+
+### Testing Utility Functions
+
+**Example: Currency Formatting**
+
+```typescript
+// src/utils/formatting.ts
+export const formatCurrency = (amount: number): string => {
+  return `$${amount.toFixed(2)}`;
+};
+
+// src/utils/formatting.test.ts
+import { describe, it, expect } from 'vitest';
+import { formatCurrency } from './formatting';
+
+describe('formatCurrency', () => {
+  it('formats whole numbers correctly', () => {
+    expect(formatCurrency(10)).toBe('$10.00');
+  });
+
+  it('formats decimal numbers correctly', () => {
+    expect(formatCurrency(10.5)).toBe('$10.50');
+  });
+
+  it('rounds to two decimal places', () => {
+    expect(formatCurrency(10.999)).toBe('$11.00');
+  });
+
+  it('handles zero correctly', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+});
+```
+
+### Testing Context
+
+**Example: AuthContext**
+
+```typescript
+// src/context/AuthContext.test.tsx
+import { renderHook, act } from '@testing-library/react';
+import { AuthProvider, useAuth } from './AuthContext';
+import { describe, it, expect } from 'vitest';
+
+describe('AuthContext', () => {
+  it('initial state is logged out', () => {
+    const { result } = renderHook(() => useAuth(), {
+      wrapper: AuthProvider,
+    });
+
+    expect(result.current.isLoggedIn).toBe(false);
+    expect(result.current.isAdmin).toBe(false);
+  });
+
+  it('logs in user with github.com email as admin', async () => {
+    const { result } = renderHook(() => useAuth(), {
+      wrapper: AuthProvider,
+    });
+
+    await act(async () => {
+      await result.current.login('user@github.com', 'password');
+    });
+
+    expect(result.current.isLoggedIn).toBe(true);
+    expect(result.current.isAdmin).toBe(true);
+  });
+
+  it('logs in non-github user as regular user', async () => {
+    const { result } = renderHook(() => useAuth(), {
+      wrapper: AuthProvider,
+    });
+
+    await act(async () => {
+      await result.current.login('user@example.com', 'password');
+    });
+
+    expect(result.current.isLoggedIn).toBe(true);
+    expect(result.current.isAdmin).toBe(false);
+  });
+
+  it('logs out user', async () => {
+    const { result } = renderHook(() => useAuth(), {
+      wrapper: AuthProvider,
+    });
+
+    await act(async () => {
+      await result.current.login('user@github.com', 'password');
+    });
+
+    act(() => {
+      result.current.logout();
+    });
+
+    expect(result.current.isLoggedIn).toBe(false);
+    expect(result.current.isAdmin).toBe(false);
+  });
+});
+```
+
+---
+
+## Component Testing
+
+### Basic Component Test
+
+```typescript
+// src/components/Welcome.test.tsx
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import Welcome from './Welcome';
+
+describe('Welcome', () => {
+  it('renders welcome heading', () => {
+    render(<Welcome />);
+    expect(screen.getByRole('heading', { name: /welcome/i })).toBeInTheDocument();
+  });
+
+  it('displays call-to-action button', () => {
+    render(<Welcome />);
+    expect(screen.getByRole('button', { name: /get started/i })).toBeInTheDocument();
+  });
+});
+```
+
+### Testing with Context
+
+```typescript
+// src/components/Navigation.test.tsx
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../context/AuthContext';
+import { ThemeProvider } from '../context/ThemeContext';
+import Navigation from './Navigation';
+
+const renderWithProviders = (component: React.ReactElement) => {
+  return render(
+    <BrowserRouter>
+      <AuthProvider>
+        <ThemeProvider>
+          {component}
+        </ThemeProvider>
+      </AuthProvider>
+    </BrowserRouter>
+  );
+};
+
+describe('Navigation', () => {
+  it('renders logo and brand name', () => {
+    renderWithProviders(<Navigation />);
+    expect(screen.getByAltText('Copilot icon')).toBeInTheDocument();
+    expect(screen.getByText('OctoCAT Supply')).toBeInTheDocument();
+  });
+
+  it('shows login button when not authenticated', () => {
+    renderWithProviders(<Navigation />);
+    expect(screen.getByText(/login/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Testing User Interactions
+
+```typescript
+// src/components/ProductCard.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import ProductCard from './ProductCard';
+
+describe('ProductCard', () => {
+  const mockProduct = {
+    productId: 1,
+    name: 'Test Product',
+    description: 'Test description',
+    price: 29.99,
+    imgName: 'test.png',
+    sku: 'TEST-001',
+    unit: 'unit',
+    supplierId: 1,
+  };
+
+  it('renders product information', () => {
+    render(<ProductCard product={mockProduct} />);
+    
+    expect(screen.getByText('Test Product')).toBeInTheDocument();
+    expect(screen.getByText('Test description')).toBeInTheDocument();
+    expect(screen.getByText('$29.99')).toBeInTheDocument();
+  });
+
+  it('increments quantity when plus button clicked', async () => {
+    const user = userEvent.setup();
+    render(<ProductCard product={mockProduct} />);
+    
+    const plusButton = screen.getByLabelText(`Increase quantity of ${mockProduct.name}`);
+    await user.click(plusButton);
+    
+    expect(screen.getByLabelText(`Quantity of ${mockProduct.name}`)).toHaveTextContent('1');
+  });
+
+  it('decrements quantity when minus button clicked', async () => {
+    const user = userEvent.setup();
+    render(<ProductCard product={mockProduct} />);
+    
+    // First increment to 1
+    const plusButton = screen.getByLabelText(`Increase quantity of ${mockProduct.name}`);
+    await user.click(plusButton);
+    
+    // Then decrement
+    const minusButton = screen.getByLabelText(`Decrease quantity of ${mockProduct.name}`);
+    await user.click(minusButton);
+    
+    expect(screen.getByLabelText(`Quantity of ${mockProduct.name}`)).toHaveTextContent('0');
+  });
+
+  it('calls onAddToCart when add to cart button clicked', async () => {
+    const user = userEvent.setup();
+    const onAddToCart = vi.fn();
+    render(<ProductCard product={mockProduct} onAddToCart={onAddToCart} />);
+    
+    // Increment quantity
+    const plusButton = screen.getByLabelText(`Increase quantity of ${mockProduct.name}`);
+    await user.click(plusButton);
+    
+    // Click add to cart
+    const addButton = screen.getByRole('button', { name: /add to cart/i });
+    await user.click(addButton);
+    
+    expect(onAddToCart).toHaveBeenCalledWith(mockProduct.productId, 1);
+  });
+});
+```
+
+### Testing Forms
+
+```typescript
+// src/components/Login.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import Login from './Login';
+
+describe('Login', () => {
+  it('submits form with email and password', async () => {
+    const user = userEvent.setup();
+    const onLogin = vi.fn();
+    render(<Login onLogin={onLogin} />);
+    
+    // Fill in form
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    
+    // Submit
+    await user.click(screen.getByRole('button', { name: /login/i }));
+    
+    expect(onLogin).toHaveBeenCalledWith('test@example.com', 'password123');
+  });
+
+  it('shows validation error for empty email', async () => {
+    const user = userEvent.setup();
+    render(<Login />);
+    
+    await user.click(screen.getByRole('button', { name: /login/i }));
+    
+    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Integration Testing
+
+### Testing with API Mocking
+
+```typescript
+// src/components/Products.test.tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from 'react-query';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import axios from 'axios';
+import Products from './Products';
+
+// Mock axios
+vi.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('Products', () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+
+  beforeEach(() => {
+    queryClient.clear();
+  });
+
+  it('displays loading state initially', () => {
+    mockedAxios.get.mockImplementation(() => new Promise(() => {}));
+    render(<Products />, { wrapper });
+    
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+
+  it('displays products after loading', async () => {
+    const mockProducts = [
+      { productId: 1, name: 'Product 1', price: 10.99 },
+      { productId: 2, name: 'Product 2', price: 20.99 },
+    ];
+
+    mockedAxios.get.mockResolvedValueOnce({ data: mockProducts });
+
+    render(<Products />, { wrapper });
+
+    await waitFor(() => {
+      expect(screen.getByText('Product 1')).toBeInTheDocument();
+      expect(screen.getByText('Product 2')).toBeInTheDocument();
+    });
+  });
+
+  it('displays error message on fetch failure', async () => {
+    mockedAxios.get.mockRejectedValueOnce(new Error('Network error'));
+
+    render(<Products />, { wrapper });
+
+    await waitFor(() => {
+      expect(screen.getByText(/failed to fetch products/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+---
+
+## Testing Best Practices
+
+### 1. Test Behavior, Not Implementation
+
+❌ **Bad:**
+```typescript
+it('updates state when button clicked', () => {
+  // Testing internal state
+  expect(component.state.count).toBe(1);
+});
+```
+
+✅ **Good:**
+```typescript
+it('displays incremented count when button clicked', () => {
+  // Testing visible output
+  expect(screen.getByText('Count: 1')).toBeInTheDocument();
+});
+```
+
+### 2. Use Accessible Queries
+
+Prefer queries in this order:
+1. `getByRole` - Most accessible
+2. `getByLabelText` - For form elements
+3. `getByPlaceholderText` - For inputs
+4. `getByText` - For content
+5. `getByTestId` - Last resort
+
+❌ **Avoid:**
+```typescript
+const button = container.querySelector('.submit-button');
+```
+
+✅ **Prefer:**
+```typescript
+const button = screen.getByRole('button', { name: /submit/i });
+```
+
+### 3. Don't Test External Libraries
+
+Don't test that React Router or Axios work—they're already tested.
+
+❌ **Bad:**
+```typescript
+it('React Router navigates correctly', () => {
+  // Testing React Router, not your code
+});
+```
+
+✅ **Good:**
+```typescript
+it('redirects to login when not authenticated', () => {
+  // Testing your auth logic
+});
+```
+
+### 4. Keep Tests Independent
+
+Each test should be able to run in isolation.
+
+✅ **Good:**
+```typescript
+describe('Counter', () => {
+  beforeEach(() => {
+    // Reset state before each test
+  });
+
+  it('test 1', () => { /* ... */ });
+  it('test 2', () => { /* ... */ });
+});
+```
+
+### 5. Mock External Dependencies
+
+Mock API calls, timers, and external services:
+
+```typescript
+vi.mock('axios');
+vi.mock('../api/config', () => ({
+  api: { baseURL: 'http://test.com', endpoints: {} },
+}));
+```
+
+### 6. Use Descriptive Test Names
+
+✅ **Good:**
+```typescript
+it('displays error message when login fails', () => { });
+it('enables submit button when form is valid', () => { });
+```
+
+❌ **Bad:**
+```typescript
+it('works', () => { });
+it('test 1', () => { });
+```
+
+---
+
+## Common Testing Patterns
+
+### Testing Theme Context
+
+```typescript
+it('applies dark mode styles when dark mode enabled', () => {
+  const { rerender } = render(
+    <ThemeProvider>
+      <MyComponent />
+    </ThemeProvider>
+  );
+  
+  // Component starts in light mode
+  expect(screen.getByTestId('container')).toHaveClass('bg-white');
+  
+  // Enable dark mode
+  act(() => {
+    // trigger dark mode
+  });
+  
+  expect(screen.getByTestId('container')).toHaveClass('bg-dark');
+});
+```
+
+### Testing Loading States
+
+```typescript
+it('shows loading spinner while fetching', () => {
+  mockedAxios.get.mockImplementation(() => new Promise(() => {})); // Never resolves
+  
+  render(<Products />);
+  
+  expect(screen.getByRole('status')).toBeInTheDocument();
+  expect(screen.getByLabelText('loading')).toBeInTheDocument();
+});
+```
+
+### Testing Error States
+
+```typescript
+it('displays error message when API call fails', async () => {
+  mockedAxios.get.mockRejectedValueOnce(new Error('API Error'));
+  
+  render(<Products />);
+  
+  await waitFor(() => {
+    expect(screen.getByText(/error/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Testing Conditional Rendering
+
+```typescript
+it('shows admin menu only when user is admin', () => {
+  const { rerender } = render(<Navigation />);
+  
+  // Not logged in
+  expect(screen.queryByText('Admin Panel')).not.toBeInTheDocument();
+  
+  // Log in as admin
+  rerender(<Navigation isAdmin={true} />);
+  expect(screen.getByText('Admin Panel')).toBeInTheDocument();
+});
+```
+
+### Testing Async Operations
+
+```typescript
+it('updates product list after deletion', async () => {
+  const user = userEvent.setup();
+  mockedAxios.delete.mockResolvedValueOnce({});
+  
+  render(<AdminProducts />);
+  
+  const deleteButton = screen.getByRole('button', { name: /delete/i });
+  await user.click(deleteButton);
+  
+  await waitFor(() => {
+    expect(screen.queryByText('Product 1')).not.toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Coverage Goals
+
+### Target Coverage
+
+- **Statements:** > 80%
+- **Branches:** > 75%
+- **Functions:** > 80%
+- **Lines:** > 80%
+
+### Check Coverage
+
+```bash
+npm run test:coverage
+```
+
+Generates report in `coverage/` directory.
+
+### Focus Coverage On
+
+1. **Critical paths:** Authentication, data submission
+2. **Business logic:** Calculations, validations
+3. **Error handling:** Error states, edge cases
+
+### Don't Stress Coverage For
+
+- UI-only components without logic
+- Simple presentational components
+- Third-party library wrappers
+
+---
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [React Testing Library](https://testing-library.com/react)
+- [Testing Library Queries](https://testing-library.com/docs/queries/about)
+- [Common Mistakes](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
+
+---
+
+## Next Steps
+
+To implement testing in this project:
+
+1. Add test setup file: `src/test/setup.ts`
+2. Configure Vitest in `vite.config.ts`
+3. Write tests for critical components (AuthContext, Products, Navigation)
+4. Set up CI/CD to run tests on every PR
+5. Add coverage thresholds to fail build if coverage drops
diff --git a/frontend/README.md b/frontend/README.md
index 40ede56..230e4dd 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,54 +1,135 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default tseslint.config({
-  extends: [
-    // Remove ...tseslint.configs.recommended and replace with this
-    ...tseslint.configs.recommendedTypeChecked,
-    // Alternatively, use this for stricter rules
-    ...tseslint.configs.strictTypeChecked,
-    // Optionally, add this for stylistic rules
-    ...tseslint.configs.stylisticTypeChecked,
-  ],
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
+# OctoCAT Supply Chain Management - Frontend
+
+Modern React-based frontend for the OctoCAT Supply Chain Management System.
+
+## Overview
+
+A single-page application (SPA) built with React, TypeScript, Vite, and Tailwind CSS that provides an intuitive interface for managing supply chain operations including products, orders, suppliers, and more.
+
+## Key Features
+
+- 🎨 **Dark/Light Theme** - User-switchable theme with localStorage persistence
+- 🔐 **Authentication** - Role-based access control (admin/regular users)
+- 📱 **Responsive Design** - Mobile-first approach with Tailwind CSS
+- ⚡ **Fast Development** - Vite HMR for instant feedback
+- 🎯 **Type-Safe** - Full TypeScript coverage
+- 🌐 **API Integration** - RESTful API communication with React Query
+- ♿ **Accessible** - ARIA labels and keyboard navigation support
+
+## Tech Stack
+
+- **React 18+** - UI library
+- **TypeScript** - Type-safe JavaScript
+- **Vite** - Build tool and dev server
+- **Tailwind CSS** - Utility-first CSS framework
+- **React Router v7** - Client-side routing
+- **React Query** - Server state management
+- **Axios** - HTTP client
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+ and npm 9+
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Access at http://localhost:5137
+```
+
+### Build for Production
+
+```bash
+npm run build
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default tseslint.config({
-  plugins: {
-    // Add the react-x and react-dom plugins
-    'react-x': reactX,
-    'react-dom': reactDom,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended typescript rules
-    ...reactX.configs['recommended-typescript'].rules,
-    ...reactDom.configs.recommended.rules,
-  },
-})
+### Linting
+
+```bash
+npm run lint
+```
+
+## Project Structure
+
+```
+src/
+├── api/              # API configuration and endpoints
+├── components/       # React components
+│   ├── admin/       # Admin-specific components
+│   ├── entity/      # Domain entity components
+│   └── ...          # Layout and page components
+├── context/         # React Context providers (Auth, Theme)
+├── assets/          # Images and static assets
+├── App.tsx          # Root component with routing
+└── main.tsx         # Application entry point
 ```
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/frontend/` directory:
+
+- **[Overview & Getting Started](../docs/frontend/README.md)** - Introduction and quick start
+- **[Architecture](../docs/frontend/architecture.md)** - Component structure, state management, routing patterns
+- **[Setup & Development](../docs/frontend/setup.md)** - Prerequisites, environment setup, development workflow
+- **[Component Documentation](../docs/frontend/components.md)** - Detailed component API and usage examples
+- **[Styling Guidelines](../docs/frontend/styling.md)** - Tailwind CSS conventions and theme system
+- **[API Integration](../docs/frontend/api-integration.md)** - API client, error handling, authentication
+- **[Testing](../docs/frontend/testing.md)** - Testing strategy, tools, and examples
+- **[Code Organization](../docs/frontend/code-organization.md)** - Folder structure and best practices
+
+## Available Routes
+
+- `/` - Welcome/landing page
+- `/about` - About page
+- `/products` - Product catalog
+- `/login` - User login
+- `/admin/products` - Admin product management (requires admin access)
+
+## Environment Configuration
+
+The application automatically detects the API URL:
+
+1. **Runtime Config** - `window.RUNTIME_CONFIG.API_URL` (Docker/production)
+2. **GitHub Codespaces** - Auto-detected and configured
+3. **Local Development** - Defaults to `http://localhost:3000`
+
+See [Setup Documentation](../docs/frontend/setup.md#environment-configuration) for details.
+
+## Development Scripts
+
+```bash
+npm run dev      # Start dev server (http://localhost:5137)
+npm run build    # Build for production
+npm run lint     # Run ESLint
+npm run preview  # Preview production build
+```
+
+## Contributing
+
+When adding new features:
+
+1. Follow [Code Organization](../docs/frontend/code-organization.md) patterns
+2. Adhere to [Styling Guidelines](../docs/frontend/styling.md)
+3. Add tests (see [Testing Guide](../docs/frontend/testing.md))
+4. Update relevant documentation
+
+## Architecture
+
+This frontend communicates with a REST API backend. See the [main architecture documentation](../docs/architecture.md) for system-wide design and [frontend architecture](../docs/frontend/architecture.md) for detailed frontend patterns.
+
+## Support
+
+- Check the [documentation](../docs/frontend/README.md)
+- Review [setup troubleshooting](../docs/frontend/setup.md#troubleshooting)
+- See component examples in the codebase
+
+## License
+
+Part of the OctoCAT Supply Chain Management System.

From fca577f3aa223f039174ee5612e2fe3a9e3369a0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:18:51 +0000
Subject: [PATCH 3/3] Address code review feedback - fix Vitest mocking, React
 Query version notes, and error handling

Co-authored-by: webmaxru <1560278+webmaxru@users.noreply.github.com>
---
 docs/frontend/api-integration.md | 16 +++++++++++++---
 docs/frontend/components.md      |  7 +++++++
 docs/frontend/testing.md         |  2 +-
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/frontend/api-integration.md b/docs/frontend/api-integration.md
index 5c5de02..bdf6a03 100644
--- a/docs/frontend/api-integration.md
+++ b/docs/frontend/api-integration.md
@@ -193,6 +193,8 @@ React Query manages server state (fetching, caching, synchronization) with minim
 npm install react-query
 ```
 
+**Current Version:** This project uses React Query v3. For newer projects, consider React Query v4+ (renamed to @tanstack/react-query) which uses object-based API syntax.
+
 ### Setup
 
 **No setup required** - React Query is used directly in components without a provider in the current implementation.
@@ -205,6 +207,7 @@ import axios from 'axios';
 import { api } from '../api/config';
 
 function Products() {
+  // React Query v3 syntax (current)
   const { data, isLoading, error } = useQuery('products', async () => {
     const response = await axios.get(`${api.baseURL}${api.endpoints.products}`);
     return response.data;
@@ -330,11 +333,18 @@ try {
 } catch (error) {
   if (axios.isAxiosError(error)) {
     if (error.response?.status === 404) {
-      alert('Product not found');
+      // Display user-friendly error in UI
+      setErrorMessage('Product not found');
     } else if (error.response?.status === 500) {
-      alert('Server error. Please try again later.');
+      // Display user-friendly error in UI
+      setErrorMessage('Server error. Please try again later.');
     } else {
-      alert('An error occurred');
+      // Display generic error in UI
+      setErrorMessage('An error occurred');
+    }
+    // Log error for debugging (in development only)
+    if (import.meta.env.DEV) {
+      console.error('API Error:', error);
     }
   }
 }
diff --git a/docs/frontend/components.md b/docs/frontend/components.md
index 98b489a..3e7f4fb 100644
--- a/docs/frontend/components.md
+++ b/docs/frontend/components.md
@@ -311,7 +311,14 @@ const [showModal, setShowModal] = useState(false);
 Uses React Query for data fetching:
 
 ```typescript
+// React Query v3 syntax (current version in this project)
 const { data: products, isLoading, error } = useQuery('products', fetchProducts);
+
+// Note: For React Query v4+, use object syntax:
+// const { data, isLoading, error } = useQuery({
+//   queryKey: ['products'],
+//   queryFn: fetchProducts
+// });
 ```
 
 **Key Functions:**
diff --git a/docs/frontend/testing.md b/docs/frontend/testing.md
index 154b819..0eb884b 100644
--- a/docs/frontend/testing.md
+++ b/docs/frontend/testing.md
@@ -426,7 +426,7 @@ import Products from './Products';
 
 // Mock axios
 vi.mock('axios');
-const mockedAxios = axios as jest.Mocked<typeof axios>;
+const mockedAxios = vi.mocked(axios);
 
 describe('Products', () => {
   const queryClient = new QueryClient({