# Datafold React Application (v2.0.0)

A modern React application for managing schemas, mutations, queries, and data operations with comprehensive state management and SCHEMA-002 compliance enforcement.

## Architecture Overview

This application follows a **simplified, modular architecture** designed for maintainability, testability, and performance:

- **🎯 Centralized State Management**: Redux Toolkit for predictable state updates
- **🔌 Unified API Client**: Standardized HTTP communication with retry logic and caching
- **🪝 Custom Hooks**: Reusable business logic encapsulation
- **🧩 Modular Components**: Extracted, reusable UI components
- **📋 SCHEMA-002 Compliance**: Built-in enforcement at all architectural layers
- **⚡ Performance Optimized**: Request deduplication, caching, and memoization

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Access to Datafold backend API
- Valid authentication credentials

### Installation

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

### Development Server

The application runs on `http://localhost:5173` with hot module replacement (HMR) enabled.

## Project Structure

```
src/
├── api/                    # Unified API client system
│   ├── core/              # Core client functionality
│   ├── clients/           # Specialized API clients
│   └── endpoints.ts       # API endpoint definitions
├── components/            # Reusable UI components
│   ├── form/             # Form field components
│   ├── schema/           # Schema-related components
│   └── tabs/             # Tab content components
├── constants/             # Centralized configuration
├── hooks/                 # Custom React hooks
├── store/                 # Redux store and slices
├── styles/               # Global styles and themes
├── test/                 # Testing utilities and integration tests
├── types/                # TypeScript type definitions
└── utils/                # Utility functions
```

## Key Features

### 🔐 Authentication & Security

- **Cryptographic Authentication**: Ed25519 key-based authentication
- **Message Signing**: Automatic payload signing for secure API calls
- **Key Management**: Secure private key storage and management

### 📊 Schema Management

- **SCHEMA-002 Compliance**: Only approved schemas available for operations
- **State Transitions**: Available → Approved → Blocked state management
- **Range Schema Support**: Specialized handling for time-series data
- **Real-time Updates**: Live schema state synchronization

### 🔍 Query & Mutation Operations

- **Interactive Query Builder**: Visual query construction
- **Mutation Forms**: Type-safe data modification interfaces
- **Range Operations**: Specialized range schema operations
- **Validation**: Comprehensive input validation and error handling

### 🎨 User Interface

- **Responsive Design**: Mobile-first, accessible interface
- **Tab Navigation**: Authentication-aware navigation system
- **Form Components**: Reusable, validated form fields
- **Error Handling**: User-friendly error messages and recovery

## Architecture Patterns

### Custom Hooks for Business Logic

```jsx
// Schema management
const { approvedSchemas, isLoading, error } = useApprovedSchemas();

// Range schema operations
const { isRange, formatRangeMutation } = useRangeSchema();

// Form validation
const { validate, errors, isFormValid } = useFormValidation();
```

### Redux State Management

```jsx
// Centralized state with Redux Toolkit
const schemas = useAppSelector(selectApprovedSchemas);
const dispatch = useAppDispatch();

// Async operations with automatic error handling
dispatch(fetchSchemas());
```

### Unified API Client

```jsx
// Standardized API calls with built-in features
import { schemaClient, mutationClient } from './api';

const schemas = await schemaClient.getApprovedSchemas();
const result = await mutationClient.executeMutation(mutation);
```

## SCHEMA-002 Compliance

The application enforces **SCHEMA-002** compliance at multiple levels:

- **Hook Level**: Only approved schemas returned from data hooks
- **Component Level**: Form components filter to approved schemas only
- **API Level**: Client validates schema state before operations
- **Store Level**: Redux selectors automatically filter by approval state

This ensures that users can only perform mutations and queries on approved schemas, maintaining data integrity and operational safety.

## Development Guidelines

### Component Development

1. **Single Responsibility**: Each component has one clear purpose
2. **Props Interface**: Use TypeScript for prop definitions
3. **Accessibility**: Include ARIA attributes and keyboard navigation
4. **Error Boundaries**: Handle errors gracefully

### Hook Development

1. **Pure Functions**: No side effects in custom hooks
2. **Error Handling**: Comprehensive error scenarios
3. **Testing**: Isolated unit tests for all hooks
4. **Documentation**: Complete JSDoc documentation

### State Management

1. **Normalized State**: Flat, normalized data structures
2. **Immutability**: Use Redux Toolkit's Immer integration
3. **Async Operations**: Use createAsyncThunk for API calls
4. **Selectors**: Memoized selectors for derived state

## Testing Strategy

### Testing Pyramid

- **Unit Tests**: Hooks, utilities, and components (70%)
- **Integration Tests**: Component + API integration (25%)
- **End-to-End Tests**: Complete user workflows (5%)

### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run integration tests
npm run test:integration
```

### Test Utilities

The application provides comprehensive testing utilities:

```jsx
// Hook testing
import { renderHookWithProviders } from '../test/utils/hookUtils';

// Component testing with Redux
import { renderWithProviders } from '../test/utils/testUtils';

// API mocking
import { createMockApiClient } from '../test/utils/apiMocks';
```

## Performance Considerations

### Optimizations Implemented

- **Request Deduplication**: Prevents duplicate API calls
- **Response Caching**: Configurable TTL-based caching
- **Memoized Selectors**: Prevents unnecessary re-computations
- **Component Memoization**: React.memo for pure components
- **Code Splitting**: Lazy loading for route components

### Monitoring

```jsx
// Built-in performance metrics
const apiMetrics = apiClient.getMetrics();
console.log('Cache hit rate:', apiMetrics.cacheHitRate);
console.log('Average response time:', apiMetrics.averageResponseTime);
```

## Configuration

### Environment Variables

```bash
# Development
VITE_API_BASE_URL=http://localhost:8080
VITE_ENABLE_API_LOGGING=true
VITE_CACHE_TTL_MS=300000

# Production
VITE_API_BASE_URL=https://api.datafold.com
VITE_ENABLE_API_LOGGING=false
VITE_CACHE_TTL_MS=600000
```

### Build Configuration

The application uses Vite for fast development and optimized production builds:

- **Fast Refresh**: Instant updates during development
- **Tree Shaking**: Eliminates unused code
- **Code Splitting**: Automatic chunk optimization
- **Asset Optimization**: Image and font optimization

## Documentation

### Complete Documentation Suite

- **[Architecture Guide](./ARCHITECTURE.md)**: Detailed architectural overview
- **[Migration Guide](./MIGRATION.md)**: Upgrading from legacy architecture
- **[Testing Guide](./TESTING.md)**: Testing strategies and utilities
- **[API Documentation](./docs/)**: Complete API reference

### Code Documentation

All components, hooks, and utilities include comprehensive JSDoc documentation:

```jsx
/**
 * Custom hook for managing approved schemas with SCHEMA-002 compliance
 * @returns {UseApprovedSchemasResult} Hook result with schemas and utilities
 * @example
 * const { approvedSchemas, isLoading } = useApprovedSchemas();
 */
```

## Contributing

### Development Workflow

1. Create feature branch from `main`
2. Implement changes with tests
3. Update documentation as needed
4. Run full test suite
5. Submit pull request with description

### Code Standards

- **TypeScript**: Strong typing for all new code
- **ESLint**: Enforced code quality standards
- **Prettier**: Consistent code formatting
- **Testing**: Minimum 80% test coverage
- **Documentation**: JSDoc for all public APIs

## Support & Resources

### Getting Help

- **Architecture Questions**: See [ARCHITECTURE.md](./ARCHITECTURE.md)
- **Migration Issues**: See [MIGRATION.md](./MIGRATION.md)
- **Testing Help**: See [TESTING.md](./TESTING.md)
- **API Questions**: Check [API Documentation](./docs/)

### Common Patterns

- **Schema Operations**: Using `useApprovedSchemas` hook
- **Form Validation**: Using `useFormValidation` hook
- **Range Schemas**: Using `useRangeSchema` utilities
- **Error Handling**: Using unified error types

## Version History

| Version | Date | Description |
|---------|------|-------------|
| 2.0.0 | 2025-06-24 | Complete architecture redesign with React simplification |
| 1.x | Prior | Legacy architecture (deprecated) |

---

**Built with modern React patterns for the Datafold ecosystem** 🚀

For detailed implementation guidance, see the [Architecture Documentation](./ARCHITECTURE.md).
