adserver-dashboard 1.0.0

package/docs/AI_REFERENCE.md

@@ -0,0 +1,459 @@
+# AI Development Reference Specification
+
+This document serves as the canonical reference for AI agents working on this repository. All automated code generation, testing, and documentation should follow these guidelines.
+
+## Table of Contents
+1. [Project Overview](#project-overview)
+2. [Repository Structure](#repository-structure)
+3. [Coding Standards](#coding-standards)
+4. [Testing Requirements](#testing-requirements)
+5. [Component Patterns](#component-patterns)
+6. [Internationalization (i18n)](#internationalization-i18n)
+7. [Accessibility (a11y)](#accessibility-a11y)
+8. [State Management](#state-management)
+9. [API Integration](#api-integration)
+10. [Definition of Done](#definition-of-done)
+11. [AI Workflow Instructions](#ai-workflow-instructions)
+
+---
+
+## Project Overview
+
+| Aspect | Description |
+|--------|-------------|
+| **Type** | React Single Page Application (SPA) |
+| **Tech Stack** | React 18, TypeScript, Vite, TailwindCSS |
+| **UI Library** | `@moving-walls/design-system` (npm package) |
+| **Deployment** | Static site to S3 + CloudFront |
+
+---
+
+## Repository Structure
+
+```
+├── client/src/
+│   ├── components/          # React components
+│   ├── hooks/               # Custom React hooks
+│   ├── lib/                 # Utility functions
+│   │   └── __tests__/       # Unit tests
+│   ├── pages/               # Page components
+│   ├── contexts/            # React context providers
+│   └── locales/             # i18n translation files
+├── shared/                  # Shared TypeScript types
+├── e2e/                     # Playwright E2E tests
+├── docs/                    # Documentation
+├── terraform/               # AWS infrastructure
+└── .ci/                     # GitLab CI/CD pipelines
+```
+
+---
+
+## Coding Standards
+
+### TypeScript
+
+| Rule | Requirement |
+|------|-------------|
+| Strict mode | Enabled |
+| No `any` type | Use proper typing or `unknown` |
+| Interface naming | PascalCase, no `I` prefix |
+| Enum naming | PascalCase for enum, UPPER_CASE for values |
+| File naming | kebab-case for files, PascalCase for components |
+
+### React Patterns
+
+```typescript
+// CORRECT: Functional component with explicit typing
+interface ButtonProps {
+  variant?: 'primary' | 'secondary';
+  size?: 'sm' | 'md' | 'lg';
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+
+export function Button({ variant = 'primary', size = 'md', children, onClick }: ButtonProps) {
+  return (
+    <button className={cn(buttonVariants({ variant, size }))} onClick={onClick}>
+      {children}
+    </button>
+  );
+}
+
+// WRONG: Using React.FC (avoid)
+// WRONG: Inline object destructuring without interface
+```
+
+### Import Order
+
+```typescript
+// 1. React and framework imports
+import React, { useState, useEffect } from 'react';
+
+// 2. Third-party libraries
+import { useQuery } from '@tanstack/react-query';
+import { format } from 'date-fns';
+
+// 3. Design system components
+import { Button, Card } from '@moving-walls/design-system';
+
+// 4. Internal components (absolute imports)
+import { DealCard } from '@/components/deals/deal-card';
+
+// 5. Internal utilities
+import { cn } from '@/lib/utils';
+
+// 6. Types
+import type { Deal } from '@shared/types';
+
+// 7. Styles (if any)
+import './styles.css';
+```
+
+### Allowed Libraries
+
+| Category | Library | Usage |
+|----------|---------|-------|
+| UI Components | @moving-walls/design-system | Primary UI library |
+| UI Primitives | Radix UI | Accessible primitives |
+| Styling | TailwindCSS | Utility-first CSS |
+| State (Server) | TanStack Query | API data fetching |
+| State (Client) | Redux Toolkit | Complex client state (e.g., maps) |
+| Forms | React Hook Form + Zod | Form handling and validation |
+| Dates | date-fns | Date manipulation |
+| i18n | i18next | Translations |
+| Maps | Mapbox GL | Geofencing features |
+| Routing | wouter | Client-side routing |
+
+---
+
+## Testing Requirements
+
+### Coverage Thresholds
+
+| Metric | Threshold |
+|--------|-----------|
+| Statements | 80% |
+| Branches | 75% |
+| Functions | 80% |
+| Lines | 80% |
+
+### Test File Naming
+
+```
+component.tsx          → component.test.tsx
+utils.ts               → utils.test.ts
+useCustomHook.ts       → useCustomHook.test.ts
+```
+
+### Test Structure
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from './button';
+
+describe('Button', () => {
+  describe('rendering', () => {
+    it('should render children', () => {
+      render(<Button>Click me</Button>);
+      expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
+    });
+  });
+
+  describe('interactions', () => {
+    it('should call onClick when clicked', async () => {
+      const handleClick = vi.fn();
+      render(<Button onClick={handleClick}>Click</Button>);
+      await userEvent.click(screen.getByRole('button'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+```
+
+### Test Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Run all tests |
+| `npm run test:coverage` | Run with coverage |
+| `npm run test:watch` | Watch mode |
+| `npm run test:e2e` | Playwright E2E tests |
+
+---
+
+## Component Patterns
+
+### Using Design System Components
+
+```typescript
+import { Button, Card, CardHeader, CardContent, Badge } from '@moving-walls/design-system';
+
+export function DealCard({ deal }: { deal: Deal }) {
+  return (
+    <Card>
+      <CardHeader>
+        <h3>{deal.name}</h3>
+        <Badge variant={deal.status === 'active' ? 'success' : 'default'}>
+          {deal.status}
+        </Badge>
+      </CardHeader>
+      <CardContent>
+        <p>{deal.description}</p>
+        <Button onClick={() => handleEdit(deal.id)}>Edit</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### Custom Component Pattern
+
+```typescript
+import * as React from 'react';
+import { cn } from '@/lib/utils';
+
+export interface CustomCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: 'default' | 'bordered';
+}
+
+export const CustomCard = React.forwardRef<HTMLDivElement, CustomCardProps>(
+  ({ className, variant = 'default', ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'rounded-lg p-4',
+          variant === 'bordered' && 'border border-gray-200',
+          className
+        )}
+        {...props}
+      />
+    );
+  }
+);
+CustomCard.displayName = 'CustomCard';
+```
+
+---
+
+## Internationalization (i18n)
+
+### Supported Languages
+
+| Code | Language | Direction |
+|------|----------|-----------|
+| en | English | LTR |
+| zh | Chinese (Simplified) | LTR |
+| ja | Japanese | LTR |
+| ar | Arabic | RTL |
+
+### Translation File Structure
+
+```
+client/src/locales/
+├── en/
+│   ├── common.json
+│   ├── deals.json
+│   ├── creatives.json
+│   └── navigation.json
+├── zh/
+├── ja/
+└── ar/
+```
+
+### Translation Keys Pattern
+
+```json
+{
+  "deals": {
+    "title": "Deals",
+    "createDeal": "Create Deal",
+    "form": {
+      "name": "Deal Name",
+      "budget": "Budget"
+    }
+  }
+}
+```
+
+### Usage in Components
+
+```typescript
+import { useTranslation } from 'react-i18next';
+
+function DealsPage() {
+  const { t } = useTranslation('deals');
+  
+  return (
+    <h1>{t('title')}</h1>
+  );
+}
+```
+
+---
+
+## Accessibility (a11y)
+
+### Required WCAG 2.1 AA Compliance
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Focus indicators | Visible focus ring on all interactive elements |
+| Keyboard navigation | All actions accessible via keyboard |
+| Screen reader support | Proper ARIA labels and roles |
+| Color contrast | Minimum 4.5:1 for text |
+| Skip links | "Skip to main content" link |
+| Form labels | All inputs have associated labels |
+
+---
+
+## State Management
+
+### Server State (TanStack Query)
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function useDeals() {
+  return useQuery({
+    queryKey: ['deals'],
+    queryFn: () => api.getDeals(),
+    staleTime: 5 * 60 * 1000,
+  });
+}
+
+function useCreateDeal() {
+  const queryClient = useQueryClient();
+  
+  return useMutation({
+    mutationFn: (data: CreateDealInput) => api.createDeal(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['deals'] });
+    },
+  });
+}
+```
+
+### Client State (Redux Toolkit)
+
+Only use for complex client-side state like:
+- Geofencing map state
+- Multi-step wizard data
+- Undo/redo functionality
+
+---
+
+## API Integration
+
+### API Response Pattern
+
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  status: 'success' | 'error';
+  message?: string;
+}
+
+interface PaginatedResponse<T> extends ApiResponse<T[]> {
+  pagination: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const response = await api.createDeal(data);
+  toast.success(t('deals.created'));
+} catch (error) {
+  if (error instanceof ApiError) {
+    toast.error(error.message);
+  } else {
+    toast.error(t('errors.unexpected'));
+  }
+}
+```
+
+---
+
+## Definition of Done
+
+### Code Changes Checklist
+
+- [ ] TypeScript compiles without errors
+- [ ] All tests pass
+- [ ] Coverage thresholds met
+- [ ] No console.log statements (except debug builds)
+- [ ] No hardcoded strings (use i18n)
+- [ ] Accessibility requirements met
+- [ ] Mobile responsive (if UI)
+- [ ] Documentation updated (if API change)
+
+### PR Requirements
+
+- [ ] Descriptive commit message
+- [ ] No merge conflicts
+- [ ] CI/CD pipeline passes
+- [ ] Code review approved
+
+---
+
+## AI Workflow Instructions
+
+### When Making Changes
+
+1. **Read existing code** before modifying
+2. **Follow existing patterns** in the codebase
+3. **Run tests** after changes
+4. **Check coverage** doesn't drop
+5. **Update translations** for all 4 languages
+
+### When to Defer to Humans
+
+- Security-sensitive changes (auth, encryption)
+- Database schema migrations
+- API contract changes
+- Third-party service integrations
+- Production deployment decisions
+
+### Updating This Document
+
+When project conventions change:
+1. Update this document first
+2. Apply changes to codebase
+3. Update replit.md if architecture changes
+
+---
+
+## Quick Reference
+
+### Path Aliases
+
+| Alias | Target |
+|-------|--------|
+| `@/*` | `./client/src/*` |
+| `@shared/*` | `./shared/*` |
+
+### Design System Import
+
+```typescript
+// All components from npm package
+import { Button, Card, Dialog, Sheet, Table } from '@moving-walls/design-system';
+```
+
+### Useful Commands
+
+```bash
+npm run dev              # Start dev server
+npm test                 # Run tests
+npm run test:coverage    # Coverage report
+npm run build            # Build for production
+npm run test:e2e         # E2E tests
+```

package/docs/MWDesign-Prompt.md

@@ -0,0 +1,132 @@
+# MWDesign System - AI Prompt Template
+
+Copy and inject this prompt at the start of your chat sessions to ensure consistent use of the MWDesign system components.
+
+---
+
+## Injectable Prompt
+
+```
+You are building a React application using the MWDesign System (@moving-walls/design-system). Follow these guidelines strictly:
+
+## Component Library
+
+Import all components from the npm package:
+
+```tsx
+import { Button, Card, Input, Badge, Dialog, Sheet } from '@moving-walls/design-system';
+```
+
+## Core Components Reference
+
+### Form Controls
+- `Button` - variants: default, secondary, outline, ghost, destructive; sizes: sm, default, lg
+- `Input` - props: type, error, disabled
+- `Textarea` - props: rows, disabled
+- `Checkbox`, `RadioGroup` - props: checked, onCheckedChange
+- `Switch` - props: checked, onCheckedChange
+- `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`
+- `DatePicker`, `Calendar`
+
+### Display Components
+- `Card`, `CardHeader`, `CardContent`, `CardFooter`, `CardTitle`, `CardDescription`
+- `Badge` - variants: default, secondary, destructive, outline
+- `Alert`, `AlertTitle`, `AlertDescription`
+- `Avatar`, `AvatarImage`, `AvatarFallback`
+- `Progress`, `Skeleton`, `Separator`
+- `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`
+
+### Layout Components
+- `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+- `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+- `ScrollArea`
+
+### Feedback Components
+- `Spinner` - loading indicator
+- Use toast notifications via context
+
+### Overlay Components
+- `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogTrigger`
+- `Sheet`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetTrigger`
+- `Popover`, `PopoverTrigger`, `PopoverContent`
+- `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`
+- `Tooltip`, `TooltipTrigger`, `TooltipContent`
+
+### Navigation
+- `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbSeparator`
+
+### Icons
+- Use `lucide-react` icons directly
+- `import { Search, Plus, Check, ChevronDown } from 'lucide-react';`
+
+## Key Patterns
+
+### Button with Icon
+```tsx
+import { Button } from '@moving-walls/design-system';
+import { Plus } from 'lucide-react';
+
+<Button>
+  <Plus className="mr-2 h-4 w-4" /> Add New
+</Button>
+```
+
+### Dropdown Menu
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from '@moving-walls/design-system';
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">Options</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onClick={() => handleEdit()}>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem className="text-red-600">Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### Dialog
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogTrigger } from '@moving-walls/design-system';
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    <div className="py-4">Content here</div>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Styling Guidelines
+
+- Use Tailwind CSS classes for custom styling
+- Dark mode: Use `dark:` prefix for dark mode styles
+- Spacing: Follow 4pt grid (4, 8, 12, 16, 24, 32, 48px)
+
+## DO NOT
+
+- Do not use raw HTML elements when design system components exist
+- Do not install additional UI libraries (no Chakra, Material UI, Ant Design, etc.)
+- Do not create custom button/input/modal components from scratch
+- Do not use inline styles when Tailwind classes are available
+```
+
+---
+
+## Usage
+
+1. Copy the content between the triple backticks above
+2. Paste it at the beginning of your chat session
+3. The AI will follow MWDesign conventions for all component usage