# Frontend Architecture Design

## Context
Task Reporter needs a frontend to enable factory personnel to use the incident response system. The application must work on internal network only, support real-time collaboration, and integrate with existing backend APIs.

**Stakeholders**: Line operators, supervisors, engineers, managers
**Constraints**: On-premise deployment, internal network only, no external CDN

## Goals / Non-Goals

### Goals
- Provide intuitive UI for incident management workflow
- Enable real-time collaboration via WebSocket
- Support file upload with image preview
- Work offline-first where possible (local state)
- Responsive design for desktop and tablet

### Non-Goals
- Mobile app (web responsive is sufficient)
- Offline mode with sync (requires backend changes)
- Multi-language i18n (Chinese-only for initial release)
- PWA capabilities (not required for internal use)

## Decisions

### 1. Framework: React 18 + Vite
**Decision**: Use React 18 with Vite for fast development and build
**Rationale**:
- Vite provides fast HMR and build times
- React 18 concurrent features for better UX
- Large ecosystem and team familiarity
- Static build can be served by FastAPI

**Alternatives considered**:
- Vue 3: Good option, but team has more React experience
- Next.js: SSR not needed for internal SPA
- Vanilla JS: Too much boilerplate for complex app

### 2. State Management: Zustand + React Query
**Decision**: Use Zustand for client state, React Query for server state
**Rationale**:
- Zustand: Minimal boilerplate, TypeScript-friendly
- React Query: Automatic caching, refetching, optimistic updates
- Clear separation between client and server state

**Alternatives considered**:
- Redux Toolkit: More boilerplate than needed
- Context only: Not suitable for complex state
- SWR: React Query has better DevTools

### 3. Styling: Tailwind CSS
**Decision**: Use Tailwind CSS for utility-first styling
**Rationale**:
- Fast development with utility classes
- Consistent design system
- Small bundle size with purging
- Good for component-based architecture

**Alternatives considered**:
- CSS Modules: More boilerplate
- Styled Components: Runtime overhead
- Ant Design: Too opinionated, Chinese license concerns

### 4. WebSocket: Native WebSocket with reconnection
**Decision**: Use native WebSocket API with custom reconnection logic
**Rationale**:
- Backend uses native WebSocket (not Socket.IO)
- Simple protocol, no heavy library needed
- Custom reconnection gives more control

**Alternatives considered**:
- Socket.IO client: Backend doesn't use Socket.IO
- SockJS: Unnecessary fallbacks for modern browsers

### 5. Directory Structure
```
frontend/
├── src/
│   ├── components/       # Reusable UI components
│   │   ├── common/       # Buttons, inputs, modals
│   │   ├── chat/         # Chat-related components
│   │   ├── room/         # Room management components
│   │   └── file/         # File upload/preview
│   ├── pages/            # Route pages
│   │   ├── Login.tsx
│   │   ├── RoomList.tsx
│   │   ├── RoomDetail.tsx
│   │   └── NotFound.tsx
│   ├── hooks/            # Custom React hooks
│   │   ├── useAuth.ts
│   │   ├── useWebSocket.ts
│   │   └── useRoom.ts
│   ├── stores/           # Zustand stores
│   │   ├── authStore.ts
│   │   └── chatStore.ts
│   ├── services/         # API client functions
│   │   ├── api.ts        # Axios instance
│   │   ├── auth.ts
│   │   ├── rooms.ts
│   │   └── files.ts
│   ├── types/            # TypeScript types
│   ├── utils/            # Utility functions
│   └── App.tsx           # Root component
├── public/
├── index.html
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── tsconfig.json
```

## Risks / Trade-offs

### Risk: WebSocket connection stability
**Mitigation**: Implement exponential backoff reconnection, connection status indicator, message queue for offline messages

### Risk: Large file uploads blocking UI
**Mitigation**: Use chunked uploads with progress indicator, background upload queue

### Risk: Token expiry during long sessions
**Mitigation**: Auto-refresh tokens before expiry, graceful re-authentication flow

## API Integration

### Authentication
- POST `/api/auth/login` - Returns internal token
- Store token in localStorage
- Attach `Authorization: Bearer {token}` to all requests

### WebSocket Connection
- Connect to `/api/ws/{room_id}?token={token}`
- Handle message types: message, edit_message, delete_message, typing, system

### File Upload
- POST `/api/rooms/{room_id}/files` with multipart/form-data
- Display progress during upload
- Show thumbnail for images after upload

## Open Questions
- [ ] Should we bundle the frontend with FastAPI or serve separately?
  - **Answer**: Bundle with FastAPI for simpler deployment (single container)
- [ ] Image thumbnail generation - frontend or backend?
  - **Answer**: Backend generates thumbnails, frontend displays from MinIO URL