b8eed72f96
Closes FUNCTIONAL_AUDIT.md §4 #1: WebRTC 1:1 calls had working signaling but no NAT traversal, so calls between two peers behind symmetric NAT (corporate firewalls, mobile carrier CGNAT, Incus container default networking) failed silently after the SDP exchange. Backend: - GET /api/v1/config/webrtc (public) returns {iceServers: [...]} built from WEBRTC_STUN_URLS / WEBRTC_TURN_URLS / *_USERNAME / *_CREDENTIAL env vars. Half-config (URLs without creds, or vice versa) deliberately omits the TURN block — a half-configured TURN surfaces auth errors at call time instead of falling back cleanly to STUN-only. - 4 handler tests cover the matrix. Frontend: - services/api/webrtcConfig.ts caches the config for the page lifetime and falls back to the historical hardcoded Google STUN if the fetch fails. - useWebRTC fetches at mount, hands iceServers synchronously to every RTCPeerConnection, exposes a {hasTurn, loaded} hint. - CallButton tooltip warns up-front when TURN isn't configured instead of letting calls time out silently. Ops: - infra/coturn/turnserver.conf — annotated template with the SSRF- safe denied-peer-ip ranges, prometheus exporter, TLS for TURNS, static lt-cred-mech (REST-secret rotation deferred to v1.1). - infra/coturn/README.md — Incus deploy walkthrough, smoke test via turnutils_uclient, capacity rules of thumb. - docs/ENV_VARIABLES.md gains a 13bis. WebRTC ICE servers section. Coturn deployment itself is a separate ops action — this commit lands the plumbing so the deploy can light up the path with zero code changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| .husky | ||
| .storybook | ||
| dev_audit/frontend | ||
| docs | ||
| lighthouse-reports | ||
| public | ||
| scripts | ||
| src | ||
| visual-tests | ||
| .dockerignore | ||
| .env.example | ||
| .env.storybook | ||
| .gitignore | ||
| .prettierignore | ||
| .prettierrc.json | ||
| .size-limit.json | ||
| all_components.txt | ||
| analyze_lint.py | ||
| covered_components.txt | ||
| Dockerfile | ||
| Dockerfile.dev | ||
| Dockerfile.production | ||
| e2e_test_output.json | ||
| env.remote-r720.example | ||
| eslint.config.js | ||
| full_test_result.txt | ||
| index.html | ||
| jest.config.js | ||
| lint_results.txt | ||
| lint_results_2.txt | ||
| lint_results_3.txt | ||
| lint_results_final.txt | ||
| lint_results_final_v2.txt | ||
| lostpixel.config.ts | ||
| nginx.conf | ||
| nginx.production.conf | ||
| openapitools.json | ||
| orval.config.ts | ||
| package.json | ||
| postcss.config.js | ||
| README.md | ||
| RUNTIME_ISSUES.json | ||
| stryker.config.mjs | ||
| tailwind.config.ts | ||
| tsconfig.app.json | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| tsconfig.tsbuildinfo | ||
| vite.config.ts | ||
| vitest.config.ts | ||
| vitest.shims.d.ts | ||
| vitest.storybook.config.ts | ||
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
npm install
Development
npm run dev
The application will be available at http://localhost:5173.
Building
npm run build
Setup Steps
1. Environment Variables
Copy .env.example to .env and configure:
# 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:
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:
# 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 servernpm run dev:lab- Start with lab environment (real database)npm run dev:mocks- Start with MSW mocks enabled
Building
npm run build- Build for productionnpm run preview- Preview production build
Testing
npm test- Run unit tests (Vitest)npm run test:ui- Run tests with UInpm run test:e2e- Run E2E tests (Playwright)
Code Quality
npm run lint- Run ESLintnpm run lint:fix- Fix ESLint issuesnpm run lint:ui- Run ESLint onsrc/componentsandsrc/featuresonlynpm run report:arbitrary- Report Tailwind arbitrary values (w-[...], gap-[...], etc.) for migrationnpm run typecheck- Type check without emitting filesnpm run fmt- Format code with Prettier
Type Generation & Validation
npm run generate:types- Generate TypeScript types from OpenAPI specnpm run validate:schemas- Validate Zod schemasnpm run validate:types- Type checknpm 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
- Follow the existing code style
- Run
npm run validate:allbefore committing - Ensure all tests pass:
npm test - 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:
cd ../../veza-backend-api
swag init # Generate OpenAPI spec
Build Errors
-
Clear node_modules and reinstall:
rm -rf node_modules package-lock.json npm install -
Clear Vite cache:
rm -rf node_modules/.vite
Type Errors
Run type generation and validation:
npm run generate:types
npm run validate:types