werkzeuge/teamleader_test/frontend/DEVELOPMENT.md

# Network Scanner Frontend - Development Guide

## Architecture

### Component Structure

```
App (Router)
  └── Layout (Navigation)
      ├── Dashboard
      │   ├── ScanForm
      │   └── Statistics
      ├── NetworkPage
      │   ├── NetworkMap (ReactFlow)
      │   │   └── HostNode (Custom)
      │   └── HostDetails (Modal)
      ├── HostsPage
      │   ├── HostTable
      │   └── HostDetails (Modal)
      └── ScansPage
          └── ScansList
```

### State Management

- **Local State**: React hooks (useState, useEffect)
- **Custom Hooks**: Data fetching and WebSocket management
- **No Global State**: Each page manages its own data

### Data Flow

1. **REST API** → Custom hooks → Components → UI
2. **WebSocket** → Custom hooks → State updates → UI refresh

## Custom Hooks

### useScans

Manages scan data:
- Fetches list of scans
- Polls for updates
- Provides refetch function

```typescript
const { scans, loading, error, refetch } = useScans();
```

### useHosts

Manages host data:
- Fetches list of hosts
- Gets individual host details
- Provides refetch function

```typescript
const { hosts, loading, error, refetch } = useHosts();
const { host, loading, error } = useHost(hostId);
```

### useTopology

Manages network topology:
- Fetches topology graph data
- Provides refetch function

```typescript
const { topology, loading, error, refetch } = useTopology();
```

### useWebSocket

Manages WebSocket connection:
- Auto-reconnect on disconnect
- Message handling
- Connection status

```typescript
const { isConnected, reconnect } = useWebSocket({
  onScanProgress: (data) => { ... },
  onScanComplete: (data) => { ... },
  onHostDiscovered: (data) => { ... },
});
```

## API Integration

### REST Endpoints

All endpoints are proxied through Vite dev server:

```typescript
// Development: http://localhost:3000/api/* → http://localhost:8000/api/*
// Production: Configure your web server proxy

scanApi.startScan(request)
scanApi.getScanStatus(id)
scanApi.listScans()
scanApi.cancelScan(id)

hostApi.listHosts(params)
hostApi.getHost(id)
hostApi.getHostByIp(ip)
hostApi.getHostServices(id)
hostApi.getHostStatistics()
hostApi.deleteHost(id)

topologyApi.getTopology()
topologyApi.getNeighbors(id)
```

### WebSocket Messages

```typescript
type WSMessage = {
  type: 'scan_progress' | 'scan_complete' | 'host_discovered' | 'error';
  data: any;
};
```

## Styling

### TailwindCSS

Custom theme configuration in `tailwind.config.js`:

```javascript
colors: {
  primary: { ... },  // Blue shades
  slate: { ... },    // Dark theme
}
```

### Color Scheme

- Background: `slate-900`
- Cards: `slate-800`
- Borders: `slate-700`
- Text primary: `slate-100`
- Text secondary: `slate-400`
- Accent: `primary-500` (blue)

### Responsive Design

Mobile-first approach with breakpoints:
- `sm`: 640px
- `md`: 768px
- `lg`: 1024px
- `xl`: 1280px

## Network Map (React Flow)

### Custom Node Component

`HostNode.tsx` renders each host as a custom node:

```typescript
<HostNode
  data={{
    ip: string,
    hostname: string | null,
    type: 'gateway' | 'server' | 'workstation' | 'device',
    status: 'up' | 'down',
    service_count: number,
    color: string,
    onClick: () => void,
  }}
/>
```

### Layout Algorithm

Currently using circular layout. Can be replaced with:
- Force-directed (d3-force)
- Hierarchical (dagre)
- Manual positioning

### Node Types

- **Gateway**: Blue, Globe icon
- **Server**: Green, Server icon
- **Workstation**: Purple, Monitor icon
- **Device**: Amber, Smartphone icon
- **Unknown**: Gray, HelpCircle icon

## Adding New Features

### New API Endpoint

1. Add type to `src/types/api.ts`
2. Add service method to `src/services/api.ts`
3. Create custom hook in `src/hooks/`
4. Use in component

### New Page

1. Create component in `src/pages/`
2. Add route to `App.tsx`
3. Add navigation item to `Layout.tsx`

### New Component

1. Create in `src/components/`
2. Follow existing patterns
3. Use TypeScript for props
4. Add proper error handling

## Performance Optimization

### Current Optimizations

- React.memo for node components
- Debounced search
- Lazy loading (can be added)
- Code splitting (can be added)

### Potential Improvements

1. **Virtual scrolling** for large host lists
2. **Lazy loading** for routes
3. **Service worker** for offline support
4. **Caching** with React Query or SWR

## Testing

Currently no tests included. Recommended setup:

```bash
npm install -D vitest @testing-library/react @testing-library/jest-dom
```

Example test structure:
```
tests/
├── components/
├── hooks/
├── pages/
└── utils/
```

## Deployment

### Build for Production

```bash
npm run build
```

### Static Hosting

Upload `dist/` to:
- Netlify
- Vercel
- GitHub Pages
- AWS S3 + CloudFront

### Web Server Configuration

Nginx example:
```nginx
server {
  listen 80;
  server_name yourdomain.com;
  root /path/to/dist;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api {
    proxy_pass http://localhost:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}
```

## Environment Variables

Create `.env.production` for production:

```env
VITE_API_URL=https://api.yourdomain.com
VITE_WS_URL=wss://api.yourdomain.com
```

## Troubleshooting

### WebSocket Connection Issues

- Check CORS settings on backend
- Verify WebSocket URL
- Check browser console for errors

### API Connection Issues

- Verify backend is running
- Check proxy configuration in `vite.config.ts`
- Check network tab in browser dev tools

### Build Errors

- Clear `node_modules` and reinstall
- Check Node.js version (18+)
- Update dependencies

## Code Quality

### ESLint

```bash
npm run lint
```

### TypeScript

```bash
npx tsc --noEmit
```

### Format (if Prettier is added)

```bash
npx prettier --write src/
```

## Browser DevTools

### React DevTools

Install extension for component inspection.

### Network Tab

Monitor API calls and WebSocket messages.

### Console

Check for errors and warnings.

## Contributing

1. Follow existing code style
2. Add TypeScript types for all new code
3. Test in multiple browsers
4. Update documentation

## Resources

- [React Documentation](https://react.dev)
- [React Flow Documentation](https://reactflow.dev)
- [TailwindCSS Documentation](https://tailwindcss.com)
- [Vite Documentation](https://vitejs.dev)