{"id":48776658,"url":"https://github.com/zlovtnik/frontend","last_synced_at":"2026-04-13T13:03:08.132Z","repository":{"id":321322075,"uuid":"1082110314","full_name":"zlovtnik/frontend","owner":"zlovtnik","description":"A TypeScript/Bun/React frontend application for the Actix Web REST API backend with JWT authentication, multi-tenant support, and comprehensive functional programming patterns.","archived":false,"fork":false,"pushed_at":"2026-01-22T20:14:46.000Z","size":1624,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T12:54:33.827Z","etag":null,"topics":["actix-web","ant-design","bun","fp-ts","functional-programming","multi-tenancy","pattern-matching","railway-oriented-programming","react","rest-api-jwt-authentication","result-types","tailwindcss","typescript","validation","zod"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zlovtnik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T18:45:55.000Z","updated_at":"2026-01-22T20:14:51.000Z","dependencies_parsed_at":"2025-10-29T03:39:56.243Z","dependency_job_id":null,"html_url":"https://github.com/zlovtnik/frontend","commit_stats":null,"previous_names":["zlovtnik/frontend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zlovtnik/frontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zlovtnik%2Ffrontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zlovtnik%2Ffrontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zlovtnik%2Ffrontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zlovtnik%2Ffrontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zlovtnik","download_url":"https://codeload.github.com/zlovtnik/frontend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zlovtnik%2Ffrontend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31753552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actix-web","ant-design","bun","fp-ts","functional-programming","multi-tenancy","pattern-matching","railway-oriented-programming","react","rest-api-jwt-authentication","result-types","tailwindcss","typescript","validation","zod"],"created_at":"2026-04-13T13:03:07.427Z","updated_at":"2026-04-13T13:03:08.121Z","avatar_url":"https://github.com/zlovtnik.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Actix Web REST API Frontend\n\nA modern TypeScript/Bun/React frontend application for the Actix Web REST API backend with JWT authentication, multi-tenant support, and comprehensive functional programming patterns.\n\n## 🚀 Frontend Technology Stack\n\n### Core Frontend Technologies (Frontend-Only)\n- **Runtime \u0026 Package Manager**: Bun 1.0+ (Fast runtime, bundler, and test runner)\n- **Programming Language**: TypeScript 5.9+ (Type-safe, compiled to JavaScript)\n- **UI Framework**: React 18.3.1+ (Virtual DOM, component-based architecture)\n- **Routing Library**: React Router DOM 6.x (Declarative client-side routing)\n- **Form Management**: React Hook Form 7.x (Performant form validation and state management)\n- **UI Component Library**: Ant Design (antd) 5.27.4+ (Enterprise-grade UI components)\n- **CSS Framework**: Tailwind CSS 4.1.14+ (Utility-first CSS with custom color palette)\n- **Build Tool \u0026 Dev Server**: Vite 5.0+ (Fast HMR, optimized bundling)\n- **CSS Processor**: PostCSS 8.5.6+ with Autoprefixer 10.4.21+ (CSS transformations and vendor prefixes)\n- **Query String Parsing**: QS 6.14.0+ (Query string serialization/deserialization)\n- **Icons**: Ant Design Icons 6.1.0+ (Consistent iconography with UI components)\n- **Typography Plugin**: Tailwind Typography 0.5.19+ (Tailwind utilities for rich text)\n- **Testing Runner**: Bun's built-in test runner (Jest-compatible)\n\n### Functional Programming \u0026 Error Handling\n- **Result Types**: neverthrow 8.2.0+ (Railway-oriented programming with Result\u003cT, E\u003e)\n- **Pattern Matching**: ts-pattern 5.8.0+ (Exhaustive pattern matching for error handling)\n- **Functional Utilities**: fp-ts 2.16.11+ (Advanced functional programming utilities)\n- **Validation**: Zod 4.1.12+ (Runtime type validation with functional patterns)\n- **Date Handling**: dayjs 1.11.18+ (Lightweight date manipulation)\n\n## 📦 Installation\n\n1. Ensure Bun is installed: https://bun.sh\n2. Install dependencies:\n   ```bash\n   bun install\n   ```\n\n## 🏃 Development\n\nStart the development server with hot reload in development mode:\n\n```bash\nNODE_ENV=development bun run dev\n```\n\nOr in production mode:\n\n```bash\nNODE_ENV=production bun run dev\n```\n\nThe application will be available at `http://localhost:3000`\n\n## 🏗️ Building\n\nBuild for production:\n\n```bash\nbun run build\n```\n\nPreview production build:\n\n```bash\nbun run preview\n```\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\nbun run test\n```\n\nRun tests in watch mode:\n\n```bash\nbun run test:watch\n```\n\n## 🔧 Configuration\n\n### Environment Variables Setup\n\n⚠️ **IMPORTANT**: The application requires proper environment configuration to run. Follow these steps:\n\n#### 1. Create Environment Files\n\nCopy the example file to create your environment-specific configuration:\n\n```bash\n# For development\ncp .env.example .env.development\n\n# For production\ncp .env.example .env.production\n```\n\n#### 2. Required Environment Variables\n\nThe following variables are **REQUIRED** for the application to function:\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `VITE_API_URL` | Backend API endpoint URL | `http://localhost:8000/api` |\n\n#### 3. Optional Environment Variables\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|---------|\n| `VITE_APP_NAME` | Application display name | `Actix Web REST API` | `My App` |\n| `VITE_JWT_STORAGE_KEY` | LocalStorage key for JWT token | `auth_token` | `jwt_token` |\n| `VITE_DEBUG` | Enable debug logging | `false` | `true` |\n| `NODE_ENV` | Node environment (auto-set) | `development` | `production` |\n\n#### 4. Environment Files by Environment\n\nVite automatically loads environment-specific `.env` files:\n\n- `.env` - Loaded in all environments (base configuration)\n- `.env.development` - Development environment (loaded during `bun run dev`)\n- `.env.production` - Production environment (loaded during `bun run build`)\n- `.env.local` - Local overrides (git-ignored, highest priority)\n\n**Example `.env.development`:**\n```env\nVITE_API_URL=http://localhost:8000/api\nVITE_DEBUG=true\n```\n\n**Example `.env.production`:**\n```env\nVITE_API_URL=https://api.yourdomain.com/api\nVITE_DEBUG=false\n```\n\n#### 5. Environment Variable Validation\n\nThe application performs comprehensive validation of environment variables:\n\n**Build-Time Validation** (via `scripts/validate-env.js`):\n- Validates required variables are present\n- Checks URL format validity\n- Warns about invalid optional variables\n- Prevents builds with missing configuration\n\n**Runtime Validation** (via `src/config/env.ts`):\n- Validates configuration on app startup\n- Displays user-friendly error UI if validation fails\n- Provides helpful troubleshooting steps in development mode\n\n**What Happens if Variables are Missing?**\n\n- **Development Mode**: Clear error message with quick fix instructions\n- **Production Mode**: Build fails with detailed error message before deployment\n- **Runtime**: Application shows configuration error UI instead of broken page\n\n#### 6. Accessing Environment Variables in Code\n\n**❌ WRONG - Direct access:**\n```typescript\nconst apiUrl = import.meta.env.VITE_API_URL; // Type-unsafe, no validation\n```\n\n**✅ CORRECT - Use the config utility:**\n```typescript\nimport { getEnv } from '@/config/env';\n\nconst config = getEnv();\nconst apiUrl = config.apiUrl; // Type-safe, validated\n```\n\n#### 7. Troubleshooting\n\n**Problem: \"Configuration Error\" screen on startup**\n\nSolution:\n1. Check if `.env.development` or `.env.production` exists\n2. Verify `VITE_API_URL` is set and is a valid URL\n3. Restart the development server after making changes\n\n**Problem: Build fails with environment variable error**\n\nSolution:\n1. Ensure the appropriate `.env.production` file exists\n2. Check that `VITE_API_URL` is set for the target environment\n3. Verify URL format includes protocol (http:// or https://)\n\n**Problem: Changes to `.env` not taking effect**\n\nSolution:\n1. Restart the Vite dev server (`bun run dev`)\n2. For production builds, run `bun run build` again\n3. Clear browser cache if testing built files\n\nNote: Vite only exposes environment variables that start with `VITE_` to the client-side code. Never store secrets or API keys in these variables as they are embedded in the client-side bundle.\n\n### TypeScript Configuration\n\nThe project uses TypeScript 5.9+ with strict type checking enabled. Key configurations:\n\n- **Module System**: ESNext with Preserve mode for optimal Bun compatibility\n- **Path Aliases**: Configured for clean imports (e.g., `@/components/*`)\n- **Type Definitions**: \n  - `vite/client` - Vite environment types\n  - `@types/bun` - Bun runtime types\n  - Custom `vite-env.d.ts` - Application-specific environment types\n\n**Verify TypeScript Configuration:**\n```bash\nbun run tsc --noEmit  # Type-check without emitting files\n```\n\nValidation is performed automatically during the build process. If validation fails, the build will be aborted with clear error messages.\n\nTo manually validate environment variables:\n\n```bash\nnode scripts/validate-env.js\n```\n\n### TypeScript Configuration\n\nThe tsconfig.json is optimized for Bun runtime with:\n- Bun types included\n- JSX transform configured\n- Path aliases for clean imports\n\n## 🏛️ Architecture\n\n### Application Structure\n\n```\nsrc/\n├── components/        # Reusable UI components (Ant Design based)\n├── contexts/         # React context providers for global state\n├── pages/           # Route-based page components\n├── services/        # API client and business logic services\n├── domain/          # Pure business logic (functional programming)\n│   ├── auth.ts      # Authentication domain logic\n│   ├── contacts.ts  # Contact management logic\n│   ├── tenants.ts   # Tenant management logic\n│   └── rules/       # Business rules modules\n├── hooks/           # Custom React hooks with Result types\n├── utils/           # Pure utility functions\n├── types/           # TypeScript type definitions\n├── validation/      # Zod schemas and validation\n├── transformers/    # Data transformation pipelines\n├── test-utils/      # Testing utilities and mocks\n└── main.tsx         # Application entry point\n```\n\n### Core Features\n\n#### Functional Programming Architecture\n- **Domain Layer**: Pure business logic with zero dependencies\n- **Railway-Oriented Programming**: Result\u003cT, E\u003e types for explicit error handling\n- **Pattern Matching**: Exhaustive error handling with ts-pattern\n- **Type Safety**: Strict TypeScript with branded types and discriminated unions\n\n#### Authentication \u0026 Multi-Tenancy\n- JWT-based authentication with automatic token refresh\n- Multi-tenant frontend with tenant isolation\n- Secure token storage with httpOnly consideration\n- Role-based route protection with domain logic\n\n#### User Interface\n- Responsive design for all device types\n- Form validation with real-time feedback using Zod schemas\n- Modal dialogs for user interactions\n- Loading states and error handling with Result types\n- Accessibility compliant (WCAG guidelines)\n\n#### CRUD Operations\n- Address book/contact management with domain validation\n- Create, read, update, delete operations with error handling\n- Search and filtering functionality\n- Paginated data display with optimistic updates\n\n## 🔗 API Integration\n\nThe frontend integrates with the existing Actix Web REST API:\n\n- **Authentication**: `/api/auth/login`, `/api/auth/logout`\n- **Health**: `/api/health`, `/api/ping`\n- **Tenants**: `/api/tenants`\n- **Address Book**: `/api/address-book`\n\n## 🎯 Performance Optimizations\n\n- **Bun Runtime**: Significantly faster than Node.js\n- **Hot Reload**: Instant code changes reflection\n- **Bundle Optimization**: Tree shaking and code splitting\n- **Caching**: HTTP response caching where appropriate\n\n## 🧪 Testing Strategy\n\n### Comprehensive Test Suite\n- **Unit Tests**: Component logic, utilities, and domain functions (95%+ coverage)\n- **Integration Tests**: API service interactions with MSW mocking\n- **Component Tests**: React Testing Library with user-centric testing\n- **Domain Tests**: Pure function testing with property-based testing\n- **Error Handling Tests**: Result type validation and error scenarios\n\n### Testing Infrastructure\n- **Test Runner**: Bun's built-in test runner (Jest-compatible)\n- **DOM Environment**: Happy DOM for lightweight component testing\n- **API Mocking**: MSW (Mock Service Worker) for network-level mocking\n- **Test Utilities**: Custom render functions with provider support\n- **Coverage**: Target 85%+ code coverage with detailed reporting\n\n### Testing Patterns\n```typescript\n// Result-based testing\nconst result = await userService.getUser(userId);\nresult.match(\n  (user) =\u003e expect(user).toHaveProperty('id', userId),\n  (error) =\u003e expect.fail(`Expected success but got error: ${error.message}`)\n);\n\n// Component testing with providers\nrenderWithAuth(\u003cContactForm /\u003e, { user: mockUser });\nexpect(screen.getByRole('form')).toBeInTheDocument();\n\n// Property-based testing\nfc.assert(fc.property(fc.string(), (email) =\u003e {\n  const result = validateEmail(email);\n  return result.isOk() || result.isErr();\n}));\n```\n\n## 🚀 Deployment\n\n### Static Site Hosting\n\nDeploy to any static hosting platform:\n\n1. Build the application: `bun run build`\n2. Deploy the `dist/` directory contents\n3. Configure environment variables if needed\n\n### Supported Platforms\n\n- **Vercel**: Recommended for React applications\n- **Netlify**: Good for static sites with serverless functions\n- **Cloudflare Pages**: Excellent for global performance\n\n## 🤝 Development Guidelines\n\n### Functional Programming Patterns\n\n#### Railway-Oriented Programming\n```typescript\n// ✅ CORRECT: Use Result types for error handling\nconst result = await userService.getUser(userId);\nresult.match(\n  (user) =\u003e setUser(user),\n  (error) =\u003e showError(error.message)\n);\n\n// ❌ WRONG: Don't use try/catch for API calls\ntry {\n  const user = await userService.getUser(userId);\n  setUser(user);\n} catch (error) {\n  showError(error.message);\n}\n```\n\n#### Domain Layer Usage\n```typescript\n// Import domain functions\nimport { authenticateUser, AuthRules } from '@/domain';\n\n// Use pure functions for business logic\nconst sessionResult = authenticateUser(credentials, authResponse);\nsessionResult.match(\n  (session) =\u003e updateAuthState(session),\n  (error) =\u003e handleAuthError(error)\n);\n```\n\n#### Pattern Matching for Errors\n```typescript\nimport { match } from 'ts-pattern';\n\nconst errorUI = match(error)\n  .with({ type: 'network', retryable: true }, (e) =\u003e \u003cRetryableError error={e} /\u003e)\n  .with({ type: 'auth' }, (e) =\u003e \u003cAuthError error={e} /\u003e)\n  .with({ type: 'validation' }, (e) =\u003e \u003cValidationError error={e} /\u003e)\n  .otherwise((e) =\u003e \u003cGenericError error={e} /\u003e);\n```\n\n### Code Style\n\n- **Strict TypeScript**: All strict mode rules enabled\n- **Result Types**: Use Result\u003cT, E\u003e instead of throwing exceptions\n- **Pure Functions**: Domain logic must be pure and testable\n- **Pattern Matching**: Use ts-pattern for exhaustive error handling\n- **Branded Types**: Use branded types for validated data\n\n### Security Considerations\n\n- **HTTPS everywhere**: All production traffic encrypted\n- **Secure token storage**: httpOnly cookies preferred over localStorage\n- **XSS prevention**: React's built-in escaping + Content Security Policy\n- **CSRF protection**: Handled by backend with proper headers\n- **Input validation**: Zod schemas for all user input\n- **Error handling**: No sensitive information in error messages\n\n## 📈 Monitoring \u0026 Analytics\n\n- Client-side performance monitoring\n- Error tracking and reporting\n- Core Web Vitals measurement\n- User experience analytics\n\n## 🚀 Recent Improvements \u0026 Achievements\n\n### ✅ Completed Enhancements (Latest Release)\n\n#### Functional Programming Architecture\n- **Domain Layer**: Complete business logic extraction with 75+ pure functions\n- **Railway-Oriented Programming**: Result\u003cT, E\u003e types throughout the application\n- **Pattern Matching**: Exhaustive error handling with ts-pattern\n- **Type Safety**: Strict TypeScript with branded types and discriminated unions\n\n#### Testing Infrastructure\n- **Comprehensive Test Suite**: 180+ passing tests with 95%+ coverage target\n- **MSW Integration**: Network-level API mocking for realistic testing\n- **Component Testing**: React Testing Library with custom render utilities\n- **Property-Based Testing**: Fast-check integration for domain functions\n\n#### Error Handling \u0026 Validation\n- **TypedValidationError**: Enhanced error shape and validation details\n- **Gender Field Validation**: Required gender field with proper enum handling\n- **Form Validation**: Zod schemas with real-time feedback\n- **Error Boundaries**: Enhanced with recovery strategies and pattern matching\n\n#### Component Enhancements\n- **Testability Attributes**: data-testid attributes for better testing\n- **Accessibility**: ARIA labels and keyboard navigation support\n- **Loading States**: Skeleton screens and optimistic updates\n- **Modal Interactions**: Enhanced confirmation dialogs with proper callbacks\n\n### 🎯 Next Phase Improvements\n\n#### Performance Enhancements\n- **Code Splitting**: Implement React.lazy() and Suspense for route-based code splitting\n- **Bundle Analysis**: Use vite-bundle-analyzer to identify optimization opportunities\n- **Image Optimization**: Add lazy loading and WebP format support\n- **Caching Strategies**: Implement service worker for better asset caching\n\n#### Advanced Testing\n- **End-to-End Testing**: Introduce Playwright for comprehensive user workflows\n- **Visual Regression Tests**: Add Chromatic for UI change detection\n- **Accessibility Testing**: Implement axe-core for automated a11y testing\n- **Performance Testing**: Set up Lighthouse CI for continuous monitoring\n\n#### Developer Experience\n- **Storybook Integration**: Create component library documentation\n- **Git Hooks**: Implement Husky with commitlint for consistent commits\n- **Hot Reloading**: Enhanced development experience with better error reporting\n- **Type Checking**: Automated TypeScript validation in CI/CD\n\n#### State Management \u0026 Architecture\n- **Context Optimization**: Consider Zustand for complex state management\n- **API Layer**: Enhanced caching with React Query or SWR\n- **Error Tracking**: Sentry integration for production error monitoring\n- **Internationalization**: i18n support with react-i18next\n\n#### UI/UX Enhancements\n- **Dark Mode**: System-aware dark mode with Tailwind\n- **Progressive Web App**: Offline support and installability\n- **Advanced Animations**: Framer Motion for smooth transitions\n- **Responsive Design**: Enhanced mobile and tablet experiences\n\n#### Build \u0026 Deployment\n- **Environment-specific Builds**: Staging, production, and development configurations\n- **CI/CD Pipeline**: GitHub Actions for automated testing and deployment\n- **Security Headers**: CSP, HSTS, and other security headers\n- **Monitoring**: Application insights and performance tracking\n\n## 🔄 Roadmap\n\n### Phase 2 Features\n- Progressive Web App (PWA) capabilities\n- Advanced UI component library\n- Mobile-responsive native features\n\n### Phase 3 Features\n- Real-time WebSocket integration\n- Advanced caching strategies\n- Offline-first functionality\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🙋 Support\n\nFor support and questions:\n- Check the existing backend API documentation\n- Refer to the technical specifications in `target_tech_spec.pdf`\n- Open an issue on the project repository\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzlovtnik%2Ffrontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzlovtnik%2Ffrontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzlovtnik%2Ffrontend/lists"}