Task_Reporter/openspec/changes/archive/2025-12-01-add-react-frontend/design.md

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