veza/apps/web/README.md

# Veza Frontend

React + TypeScript frontend application for the Veza audio collaboration platform.

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Backend API running (see `veza-backend-api/README.md`)

### Installation

```bash
npm install
```

### Development

```bash
npm run dev
```

The application will be available at `http://localhost:5173`.

### Building

```bash
npm run build
```

## Setup Steps

### 1. Environment Variables

Copy `.env.example` to `.env` and configure:

```bash
# API Configuration
VITE_API_URL=http://localhost:8080/api/v1
VITE_WS_URL=ws://localhost:8081
VITE_STREAM_URL=http://localhost:8082

# Optional: Enable MSW mocks for development
VITE_USE_MSW=0
```

See `.env.example` for all available environment variables.

### 2. Type Generation

TypeScript types are generated from the OpenAPI specification. To regenerate types:

```bash
npm run generate:types
```

This script:
- Reads `veza-backend-api/openapi.yaml`
- Generates TypeScript types to `src/types/generated/`
- Creates barrel exports for easy importing

**Note**: Types are automatically generated in CI/CD before type checking.

### 3. Validation

Validate types and schemas:

```bash
# Type checking
npm run validate:types

# Schema validation
npm run validate:schemas

# Both
npm run validate:all
```

## Available Scripts

### Development
- `npm run dev` - Start development server
- `npm run dev:lab` - Start with lab environment (real database)
- `npm run dev:mocks` - Start with MSW mocks enabled

### Building
- `npm run build` - Build for production
- `npm run preview` - Preview production build

### Testing
- `npm test` - Run unit tests (Vitest)
- `npm run test:ui` - Run tests with UI
- `npm run test:e2e` - Run E2E tests (Playwright)

### Code Quality
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Fix ESLint issues
- `npm run lint:ui` - Run ESLint on `src/components` and `src/features` only
- `npm run report:arbitrary` - Report Tailwind arbitrary values (w-[...], gap-[...], etc.) for migration
- `npm run typecheck` - Type check without emitting files
- `npm run fmt` - Format code with Prettier

### Type Generation & Validation
- `npm run generate:types` - Generate TypeScript types from OpenAPI spec
- `npm run validate:schemas` - Validate Zod schemas
- `npm run validate:types` - Type check
- `npm run validate:all` - Run all validations

## Project Structure

```
apps/web/
├── src/
│   ├── components/     # Reusable UI components
│   ├── features/       # Feature modules (auth, tracks, playlists, etc.)
│   ├── hooks/          # Custom React hooks
│   ├── services/       # API clients and services
│   ├── stores/         # Zustand state management (UI state stores)
│   │                   # Note: Feature stores (auth, chat) are in features/*/store/
│   ├── types/          # TypeScript types
│   │   └── generated/  # Auto-generated types from OpenAPI
│   ├── utils/          # Utility functions
│   └── styles/         # Global styles and design tokens
├── e2e/                # End-to-end tests (Playwright)
├── scripts/            # Build and utility scripts
└── public/             # Static assets
```

## Design System

The application uses the Kodo design system. **Single source of truth** for layout, spacing, shadows, and transitions: `docs/DESIGN_TOKENS.md`. Shell layout: `docs/APP_SHELL.md`.

- **Colors**: Kodo color palette (see `src/styles/COLOR_USAGE.md`)
- **Components**: Design system components in `src/components/ui/`
- **Typography**: Type scale and hierarchy (see `docs/DESIGN_TOKENS.md`, `src/styles/TYPOGRAPHY_GUIDE.md`)
- **Spacing**: Spacing scale (see `docs/SPACING_GUIDE.md`) — no arbitrary values (e.g. `w-[300px]`, `gap-[7px]`) without justification.

**Visual regression**: `npm run visual:capture`, `npm run visual:compare`, `npm run visual:update` (see `visual-tests/README.md`). **Arbitrary values report**: `npm run report:arbitrary` to list Tailwind arbitrary patterns for migration. **New full-layout page**: see `docs/FULL_LAYOUT_PAGE.md`.

## ESLint Rules

The project enforces:

- **Typography**: Use type scale classes (text-xs, text-sm, etc.) instead of arbitrary sizes
- **Spacing**: Use spacing scale (gap-0 through gap-24) instead of arbitrary values
- **Colors**: Use Kodo design system colors instead of Tailwind defaults
- **Components**: Use design system Button component instead of native `<button>`

See `eslint.config.js` for full rule configuration.

## Contributing

1. Follow the existing code style
2. Run `npm run validate:all` before committing
3. Ensure all tests pass: `npm test`
4. Type generation runs automatically in CI/CD

## Documentation

- **Architecture Guide**: `docs/ARCHITECTURE.md` (MUST READ)
- **Component Usage**: `src/components/COMPONENT_USAGE.md`
- **Color Usage**: `src/styles/COLOR_USAGE.md`
- **Typography**: `src/styles/TYPOGRAPHY_GUIDE.md`
- **Spacing**: `src/styles/SPACING_GUIDE.md`

## Troubleshooting

### Type Generation Fails

Ensure `veza-backend-api/openapi.yaml` exists and is valid:

```bash
cd ../../veza-backend-api
swag init  # Generate OpenAPI spec
```

### Build Errors

1. Clear node_modules and reinstall:
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

2. Clear Vite cache:
   ```bash
   rm -rf node_modules/.vite
   ```

### Type Errors

Run type generation and validation:

```bash
npm run generate:types
npm run validate:types
```