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

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

useHosts

Manages host data:

• Fetches list of hosts
• Gets individual host details
• Provides refetch function

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

useTopology

Manages network topology:

• Fetches topology graph data
• Provides refetch function

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

useWebSocket

Manages WebSocket connection:

• Auto-reconnect on disconnect
• Message handling
• Connection status

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

API Integration

REST Endpoints

All endpoints are proxied through Vite dev server:

// 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

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

Styling

TailwindCSS

Custom theme configuration in tailwind.config.js:

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:

<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:

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

Example test structure:

tests/
├── components/
├── hooks/
├── pages/
└── utils/

Deployment

Build for Production

npm run build

Static Hosting

Upload dist/ to:

• Netlify
• Vercel
• GitHub Pages
• AWS S3 + CloudFront

Web Server Configuration

Nginx example:

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:

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

npm run lint

TypeScript

npx tsc --noEmit

Format (if Prettier is added)

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
• React Flow Documentation
• TailwindCSS Documentation
• Vite Documentation