# Release Management Platform - Frontend

Modern React TypeScript frontend for the Release Management Platform, built with Material-UI and real-time SignalR integration.

## Features

- **Dashboard**: Overview of packages, projects, and active publications
- **Package Management**: Create, edit, and manage software packages
- **Real-time Publishing**: Live progress tracking with WebSocket updates
- **Project Monitoring**: Build status and history from CruiseControl.NET
- **Responsive Design**: Works on desktop and mobile devices

## Technology Stack

- **React 18+** with TypeScript
- **Material-UI** for component library and theming
- **Vite** for fast development and building
- **React Query** for server state management
- **SignalR** for real-time updates
- **React Hook Form** with Yup validation
- **React Router** for navigation

## Project Structure

```
src/
├── components/          # Reusable UI components
│   ├── Layout/         # App layout and navigation
│   ├── Packages/       # Package management components
│   ├── Publishing/     # Publishing dashboard components
│   └── common/         # Shared components
├── hooks/              # Custom React hooks
├── services/           # API clients and services
├── types/              # TypeScript type definitions
├── contexts/           # React contexts and providers
├── pages/              # Page components
└── utils/              # Utility functions
```

## Getting Started

### Development

1. Install dependencies:
```bash
npm install
```

2. Start the development server:
```bash
npm run dev
```

The application will be available at http://localhost:3000

### Building for Production

```bash
npm run build
```

### Docker Deployment

Build the Docker image:
```bash
docker build -t release-management-frontend .
```

Run the container:
```bash
docker run -p 3000:80 release-management-frontend
```

## Configuration

The frontend is configured to proxy API requests to the backend services:

- `/api/*` → API Gateway on port 5000
- `/hubs/*` → SignalR hubs on port 5000

For production deployment, configure the nginx.conf file or environment variables as needed.

## Key Components

### Package Management
- **PackageList**: Displays all packages with filtering and search
- **PackageForm**: Create and edit package configurations
- Supports tabbed interface for basic info, configuration, storage, and help center settings

### Publishing Dashboard
- **PublishingDashboard**: Real-time view of active publications
- **ProgressBar**: Visual progress indicators for publishing steps
- Live updates via SignalR for step completion and progress

### Real-time Updates
- SignalR integration for live publishing progress
- Build status updates from CruiseControl.NET
- Automatic UI refresh on publication completion

## API Integration

The frontend integrates with the following backend services:

- **Package Service**: CRUD operations for packages
- **Project Service**: CruiseControl.NET integration
- **Publication Service**: Publishing workflow management
- **SignalR Hub**: Real-time notifications

## Development Guidelines

- Use TypeScript for type safety
- Follow Material-UI design patterns
- Implement proper error handling and loading states
- Use React Query for server state management
- Write reusable components with proper prop interfaces
- Follow responsive design principles

## Environment Variables

Create a `.env.local` file for local development:

```env
VITE_API_BASE_URL=http://localhost:5000
VITE_SIGNALR_HUB_URL=http://localhost:5000/hubs
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

1. Follow the existing code style and patterns
2. Write TypeScript interfaces for all data structures
3. Include proper error handling and loading states
4. Test responsive behavior on different screen sizes
5. Document complex components and hooks

---

## 📝 Developer Notes for Future Development

### Architecture Decisions & Patterns

#### **State Management Strategy**
- **React Query**: Used for all server state (packages, projects, publications)
- **Local State**: useState/useReducer for UI-only state
- **Context API**: Only for truly global state (currently just QueryProvider)
- **No Redux**: Kept simple with React Query + local state

#### **Component Architecture**
```
Pages -> Layout -> Feature Components -> Common Components
```
- **Pages**: Route-level components, minimal logic
- **Feature Components**: Domain-specific (Packages, Publishing)  
- **Common Components**: Reusable UI elements
- **Layout**: Navigation and app shell

#### **API Integration Patterns**
- **Services Layer**: Clean separation of API logic
- **Custom Hooks**: Encapsulate data fetching and mutations
- **Error Boundaries**: Not implemented yet - consider adding
- **Optimistic Updates**: Implemented in mutation hooks

### 🔧 Technical Implementation Notes

#### **SignalR Integration**
```typescript
// SignalR connection lifecycle managed in useSignalR hook
// Automatic reconnection enabled
// Group-based subscriptions for publication updates
```

**Important**: SignalR connection state should be displayed in UI (connection indicator in AppLayout)

#### **Form Handling**
- **React Hook Form + Yup**: Chosen for performance and TypeScript support
- **Tabbed Forms**: PackageForm uses Material-UI Tabs
- **Dynamic Fields**: Build selection depends on project selection

#### **Real-time Updates Flow**
```
1. User triggers publish -> API call
2. SignalR sends progress updates -> useSignalR hook
3. Hook invalidates React Query cache -> UI updates
4. Publication completes -> Final UI refresh
```

### 🚨 Known Issues & TODOs

#### **Missing Components**
- [ ] **Projects Page**: Currently just placeholder
- [ ] **History Page**: Publication history view needed
- [ ] **Settings Page**: User preferences, API configuration
- [ ] **User Management**: Authentication UI
- [ ] **Error Boundaries**: Global error handling

#### **UX Improvements Needed**
- [ ] **Loading Skeletons**: Replace spinners with skeleton screens
- [ ] **Toast Notifications**: Success/error feedback
- [ ] **Keyboard Navigation**: Accessibility improvements
- [ ] **Mobile Optimization**: Touch gestures, better responsive design
- [ ] **Dark Mode**: Theme switcher

#### **Performance Optimizations**
- [ ] **Virtualization**: For large lists (packages, publications)  
- [ ] **Code Splitting**: Route-based lazy loading
- [ ] **Bundle Analysis**: webpack-bundle-analyzer equivalent for Vite
- [ ] **Image Optimization**: If images are added later

### 🔐 Security Considerations

#### **Current Implementation**
- JWT tokens stored in localStorage (not ideal for production)
- CORS handled by backend
- CSP headers in nginx.conf
- Input validation with Yup schemas

#### **Production Security TODOs**
- [ ] **HttpOnly Cookies**: Move JWT to secure cookies
- [ ] **CSRF Protection**: If switching to cookies
- [ ] **Content Security Policy**: Strengthen CSP rules
- [ ] **Input Sanitization**: XSS prevention for rich text fields

### 🎨 UI/UX Design System

#### **Material-UI Customizations**
```typescript
// Theme customization in App.tsx
// Custom shadows for cards/papers
// Color palette matches backend architecture diagram
```

#### **Component Patterns**
- **StatusChip**: Consistent status display with icons/colors
- **ProgressBar**: Reusable for publishing workflows  
- **LoadingSpinner**: Consistent loading states
- **ErrorDisplay**: Standard error handling UI

#### **Responsive Breakpoints**
```typescript
// Material-UI defaults:
xs: 0px, sm: 600px, md: 900px, lg: 1200px, xl: 1536px
// Drawer collapses below lg (1200px)
```

### 🧪 Testing Strategy (Not Implemented)

#### **Recommended Testing Approach**
```bash
# Unit Tests: React Testing Library + Jest
npm install --save-dev @testing-library/react @testing-library/jest-dom

# E2E Tests: Playwright or Cypress
npm install --save-dev playwright

# Component Testing: Storybook
npm install --save-dev @storybook/react
```

#### **Test Priorities**
1. **Critical User Flows**: Package creation, publishing workflow
2. **Real-time Features**: SignalR connection handling
3. **Form Validation**: Package form edge cases
4. **API Error Handling**: Network failure scenarios

### 🚀 Deployment Notes

#### **Environment Configuration**
```bash
# Development
VITE_API_BASE_URL=http://localhost:5000

# Production
VITE_API_BASE_URL=https://api.yourdomain.com
```

#### **Docker Multi-stage Build**
- Stage 1: Node.js build environment
- Stage 2: Nginx serving static files
- nginx.conf proxies API requests to backend

#### **Monitoring & Observability**
- [ ] **Error Tracking**: Sentry or similar
- [ ] **Analytics**: User behavior tracking
- [ ] **Performance**: Core Web Vitals monitoring
- [ ] **Logging**: Frontend error logging

### 🔄 Integration with Backend Services

#### **Expected API Endpoints**
```typescript
// Based on implementation.md architecture:
GET    /api/packages              # List packages
POST   /api/packages              # Create package  
GET    /api/packages/{id}         # Get package details
PUT    /api/packages/{id}         # Update package
DELETE /api/packages/{id}         # Delete package
POST   /api/packages/{id}/publish # Start publishing

GET    /api/projects              # List projects
GET    /api/projects/{id}/builds  # Get project builds
GET    /api/builds/{id}/commits   # Get build commits

GET    /api/publications          # List publications
GET    /api/publications/active   # Active publications
POST   /api/publications/{id}/cancel  # Cancel publication
```

#### **SignalR Hub Events**
```typescript
// Expected events from backend SignalR hub:
'PublishingProgress'     // Step progress updates
'BuildStatusUpdate'      # Project build status changes  
'PublicationCompleted'   // Publication finished successfully
'PublicationFailed'      // Publication failed with error
```

### 💡 Future Enhancement Ideas

#### **Advanced Features**
- **Bulk Operations**: Select multiple packages for batch publishing
- **Publishing Templates**: Reusable configuration templates
- **Workflow Visualization**: Visual pipeline representation
- **Audit Trail**: Detailed action history with user attribution
- **Notifications**: Email/Slack integration for publish completion
- **Rollback**: Revert to previous package versions

#### **Developer Experience**
- **Hot Reload**: Already implemented with Vite
- **TypeScript Strict Mode**: Enable stricter type checking
- **ESLint Rules**: Add more React-specific linting rules
- **Prettier**: Code formatting consistency
- **Husky**: Pre-commit hooks for quality checks

### 🤝 Team Collaboration Notes

#### **Code Review Checklist**
- [ ] TypeScript interfaces defined for new data structures
- [ ] Loading and error states handled
- [ ] Mobile responsiveness tested
- [ ] SignalR subscriptions properly cleaned up
- [ ] React Query cache invalidation logic correct
- [ ] Form validation covers edge cases

#### **Naming Conventions**
- **Components**: PascalCase (PackageList.tsx)
- **Hooks**: camelCase with 'use' prefix (usePackages.ts)
- **Types**: PascalCase interfaces/enums (Package, PackageStatus)
- **Files**: PascalCase for components, camelCase for utilities

This frontend implementation provides a solid foundation for the Release Management Platform. The architecture is scalable and the patterns established should guide future development efforts.